Office Add-ins

https://learn.microsoft.com/en-us/office/dev/add-ins/
Admin
The Office Add-ins platform allows developers to build solutions using familiar web technologies...
Tokens:784,735
Snippets:6,767
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get started with Office Add-in project structure

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/resources/resources-github-copilot-prompt-library

Use this prompt to understand the typical file structure of an Office Add-in project and the steps to get started in Visual Studio Code.

```text
Show me the typical structure of an Office Add-in project and 
explain the functionality of each file. Explain the steps and 
commands to get started in *Visual Studio Code*.
```

--------------------------------

### Sideload command examples

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-office-add-ins-for-testing

Examples of the npm start command using specific SharePoint and OneDrive document URLs.

```bash
npm run start -- web --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
```

```bash
npm run start -- web --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
```

```bash
npm run start -- web --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP
```

--------------------------------

### Install office-addin-mock

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/unit-testing

Command to install the library as a development dependency in your project root.

```bash
npm install office-addin-mock --save-dev
```

--------------------------------

### Install a new add-in

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/outlook-on-send-addins

Reads the add-in manifest file and installs it as an organization app.

```PowerShell
$Data=Get-Content -Path '.\Contoso Message Body Checker.xml' -Encoding Byte -ReadCount 0
```

```PowerShell
New-App -OrganizationApp -FileData $Data -DefaultStateForUser Enabled
```

--------------------------------

### Get the start time of an appointment

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/get-or-set-the-time-of-an-appointment

This example demonstrates how to retrieve the start time of an appointment being composed using the getAsync method. It includes a callback function to handle the asynchronous result and displays the time in both UTC and local formats.

```javascript
let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getStartTime();
    }
});

// Gets the start time of the appointment being composed.
function getStartTime() {
    item.start.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        const startTime = asyncResult.value;
        // Display the start time in UTC format on the page.
        write(`The start time in UTC is: ${startTime.toUTCString()}`);
        // Display the start time in local time on the page.
        write(`The start time in local time is: ${startTime.toLocaleString()}`);
    });
}

// Writes to a div with id="message" on the page.
function write(message) {
    document.getElementById("message").innerText += message;
}
```

--------------------------------

### Complete Startup.cs Configuration Example

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/tutorials/migrate-vsto-to-office-add-in-shared-code-library-tutorial

A full example of a Startup class configured with CORS for development purposes.

```C#
public class Startup
{
  public Startup(IConfiguration configuration)
    {
      Configuration = configuration;
    }

    readonly string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

    public IConfiguration Configuration { get; }

    // NOTE: The following code configures CORS for the localhost:44397 port.
    // This is for development purposes. In production code, you should update this to 
    // use the appropriate allowed domains.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddCors(options =>
        {
            options.AddPolicy(MyAllowSpecificOrigins,
            builder =>
            {
                builder.WithOrigins("https://localhost:44397")
                .AllowAnyMethod()
                .AllowAnyHeader();
            });
        });
        services.AddControllers();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseCors(MyAllowSpecificOrigins);

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}
```

--------------------------------

### Start add-in in web browser

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/tutorials/powerpoint-tutorial-yo

Start the local web server and open the add-in in a web-based PowerPoint document.

```command line
npm run start -- web --document {url}

```

--------------------------------

### Example manifest cache path

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/troubleshoot-outlook-add-in-activation

A concrete example of a full path to a manifest installed for a specific user.

```text
C:\Users\john\appdata\Local\Microsoft\Office\16.0\WEF\{8D8445A4-80E4-4D6B-B7AC-D4E6AF594E73}\GoRshCWa7vW8+jhKmyiDhA==\Manifests\b3d7d9d5-6f57-437d-9830-94e2aaccef16_1.2
```

--------------------------------

### Start add-in in PowerPoint

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/tutorials/powerpoint-tutorial-yo

Start the local web server and launch PowerPoint with the add-in loaded.

```command line
npm start

```

--------------------------------

### Example Registry script for trusted catalog

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins

An example of a completed TrustNetworkShareCatalog.reg file with a valid GUID and network path.

```text
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\TrustedCatalogs\{01234567-89ab-cedf-0123-456789abcedf}]
"Id"="{01234567-89ab-cedf-0123-456789abcedf}"
"Url"="\\\\TestServer\\OfficeAddinManifests"
"Flags"=dword:00000001
```

--------------------------------

### Get ExtendedProperty tags in Chrome

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/web-services

Example of using getElementsByTagName without a prefix, which works in browsers like Chrome.

```javascript
const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("ExtendedProperty")
});
```

--------------------------------

### Start the add-in project

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/excel-custom-functions-quickstart

Run the appropriate npm command based on your package.json configuration to start the local web server and open Excel with the add-in loaded.

```bash
npm run start:desktop
```

```bash
npm run start
```

--------------------------------

### Get ExtendedProperty tags in Trident webview

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/web-services

Example of using getElementsByTagName with the 't:' prefix, required for compatibility with the Trident (Internet Explorer) webview.

```javascript
const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
});
```

--------------------------------

### Start add-in from command line

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/custom-functions-debugging

Commands to start the add-in for desktop or web environments. Use the web command with a specific document URL.

```bash
npm run start:desktop
```

```bash
npm run start
```

```bash
npm run start -- web --document {url}
```

--------------------------------

### Get location using enhancedLocation.getAsync

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/get-or-set-the-location-of-an-appointment

This example shows how to retrieve appointment locations by calling getAsync on mailbox.item.enhancedLocation and processing the results in a callback function.

```javascript
let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        item.enhancedLocation.getAsync(callbackFunction);
    });
}

function callbackFunction(asyncResult) {
    asyncResult.value.forEach(function (place) {
        console.log("Display name: " + place.displayName);
        console.log("Type: " + place.locationIdentifier.type);
        if (place.locationIdentifier.type === Office.MailboxEnums.LocationType.Room) {
            console.log("Email address: " + place.emailAddress);
        }
    });
}
```

--------------------------------

### Create sample chart and data

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-charts-data-labels

The setup function initializes a 'Sample' worksheet with a table of data, while the createChart function generates a line chart based on that data.

```javascript
async function setup() {
    await Excel.run(async (context) => {
        const existingSheet = context.workbook.worksheets.getItemOrNullObject("Sample");
        await context.sync();

        if (!existingSheet.isNullObject) {
            existingSheet.delete();
            await context.sync();
        }

        const sheet = context.workbook.worksheets.add("Sample");

        const salesTable = sheet.tables.add("A1:E1", true);
        salesTable.name = "SalesTable";

        salesTable.getHeaderRowRange().values = [["Product", "Qtr1", "Qtr2", "Qtr3", "Qtr4"]];

        salesTable.rows.add(null, [
            ["Frames", 5000, 7000, 6544, 5377],
            ["Saddles", 400, 323, 276, 1451],
            ["Brake levers", 9000, 8766, 8456, 9812],
            ["Chains", 1550, 1088, 692, 2553],
            ["Mirrors", 225, 600, 923, 344],
            ["Spokes", 6005, 7634, 4589, 8765]
        ]);

        sheet.activate();
        await createChart(context);
    });
}

async function createChart(context: Excel.RequestContext) {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    const chart = worksheet.charts.add(
        Excel.ChartType.lineMarkers,
        worksheet.getRange("A1:E7"),
        Excel.ChartSeriesBy.rows
    );

    chart.axes.categoryAxis.setCategoryNames(worksheet.getRange("B1:E1"));
    chart.name = "PartChart";

    // Place the chart below the sample data.
    chart.top = 125;
    chart.left = 5;
    chart.height = 300;
    chart.width = 450;

    chart.title.text = "Bicycle Part Production";
    chart.legend.position = "Bottom";

    await context.sync();
}
```

--------------------------------

### Get the spill range from a formula

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-ranges-dynamic-arrays

This example sets a dynamic array formula in cell G4 and retrieves the range of cells that the formula spills into.

```javascript
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");

    // Set G4 to a formula that returns a dynamic array.
    let targetCell = sheet.getRange("G4");
    targetCell.formulas = [["=A4:D4"]];

    // Get the address of the cells that the dynamic array spilled into.
    let spillRange = targetCell.getSpillingToRange();
    spillRange.load("address");

    // Sync and log the spilled-to range.
    await context.sync();

    // This will log the range as "G4:J4".
    console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});
```

--------------------------------

### Configure package.json scripts

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/debug-desktop-using-edge-chromium

Add the start:desktop and dev-server scripts to your package.json file. Replace $MANIFEST_FILE$ with your manifest path and $SERVER_START$ with your server command.

```json
"start:desktop": "office-addin-debugging start $MANIFEST_FILE$ desktop",
"dev-server": "$SERVER_START$"
```

--------------------------------

### Set the start time of an appointment using setAsync

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/get-or-set-the-time-of-an-appointment

This example demonstrates how to initialize the Office.js library and use the setAsync method to update the start time of an appointment to two days from the current date. It includes a callback function to verify the success or failure of the operation.

```javascript
let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setStartTime();
    }
});

// Sets the start time of the appointment being composed.
function setStartTime() {
    // Get the current date and time, then add two days to the date.
    const startDate = new Date();
    startDate.setDate(startDate.getDate() + 2);

    item.start.setAsync(
        startDate,
        { asyncContext: { optionalVariable1: 1, optionalVariable2: 2 } },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the start time.");
            /*
                Run additional operations appropriate to your scenario and
                use the optionalVariable1 and optionalVariable2 values as needed.
            */
        });
}
```

--------------------------------

### Start sideloading with Office-Addin-Debugging

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-add-in-with-unified-manifest

Use this command to zip the unified manifest and referenced icons, sideload the add-in to the Office application, and start a local server.

```command line
npx office-addin-debugging start <relative-path-to-unified-manifest> desktop
```

--------------------------------

### Configure formFactors in manifest

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/develop/specify-office-hosts-and-api-requirements-unified

Use the extensions.requirements.formFactors property to restrict add-in installation to specific device types. This example limits the add-in to desktop devices.

```json
"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop"
            ]
        },
        ...
    }
]
```

--------------------------------

### Initialize Office add-in in taskpane.ts

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/tutorials/word-tutorial

Initial setup for the Office.onReady function in src/taskpane/taskpane.ts to verify the host is Word.

```javascript
/*
 * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 * See LICENSE in the project root for license information.
 */

/* global document, Office, Word */

Office.onReady((info) => {
  if (info.host === Office.HostType.Word) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
  }
});
```

--------------------------------

### Get a range by address

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-ranges-get

Use getRange(address) when you already know the cell reference. This example retrieves B2:C5 from the Sample worksheet and logs its address.

```javascript
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:C5");

    range.load("address");
    await context.sync();

    console.log(`The address of the range B2:C5 is "${range.address}"`);
});
```

--------------------------------

### Get the active cell using getActiveCell()

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-workbooks

Retrieves the user's current focus in the workbook as a Range object. This example loads the cell address and logs it to the console.

```javascript
await Excel.run(async (context) => {
    const activeCell = context.workbook.getActiveCell();
    activeCell.load("address");
    await context.sync();

    console.log(`The active cell is ${activeCell.address}`);
});
```

--------------------------------

### Start the development server

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/develop/configure-your-add-in-to-use-a-shared-runtime

Command to launch the project after applying the shared runtime code changes.

```bash
npm start
```

--------------------------------

### Start local development server on Mac

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/excel-quickstart-jquery

Starts the local web server for testing on a Mac.

```bash
npm run dev-server
```

--------------------------------

### Get item subject using makeEwsRequestAsync

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/web-services

This example demonstrates the getSubjectRequest function to build the SOAP XML, the sendRequest function to initiate the call, and the callback function to process the response.

```javascript
function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}
```

--------------------------------

### Build a sales worksheet with ranges

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-core-concepts

This example demonstrates how to populate a worksheet with headers and product data, apply formulas for calculations, and format the output as currency.

```javascript
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Create the headers and format them to stand out.
    const headers = [["Product", "Quantity", "Unit Price", "Totals"]];
    const headerRange = sheet.getRange("B2:E2");
    headerRange.values = headers;
    headerRange.format.fill.color = "#4472C4";
    headerRange.format.font.color = "white";

    // Create the product data rows.
    const productData = [
        ["Almonds", 6, 7.5],
        ["Coffee", 20, 34.5],
        ["Chocolate", 10, 9.56]
    ];
    const dataRange = sheet.getRange("B3:D5");
    dataRange.values = productData;

    // Create the formulas to total the amounts sold.
    const totalFormulas = [
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    const totalRange = sheet.getRange("E3:E6");
    totalRange.formulas = totalFormulas;
    totalRange.format.font.bold = true;

    // Display the totals as US dollar amounts.
    totalRange.numberFormat = [["$0.00"]];

    await context.sync();
});
```

--------------------------------

### Get a named range

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-ranges-get

Use a named range when the worksheet already defines a meaningful name for a block of cells. This example retrieves the range named MyRange from the Sample worksheet.

```javascript
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("MyRange");

    range.load("address");
    await context.sync();

    console.log(`The address of the range "MyRange" is "${range.address}"`);
});
```

--------------------------------

### Run yo office with --details parameter

Source: https://learn.microsoft.com/en-us/office/dev/add-ins/develop/yeoman-generator-overview

Use the --details parameter to display help information for all available command line parameters.

```bash
yo office --details
```
Tokens:
Raw