Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[WXP] (shared runtime) Document support in the unified manifest #4752

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

[WXP] (shared runtime) Document support in the unified manifest #4752

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7835fbb
Add unified manifest support
samantharamon Aug 22, 2024
d46b750
Apply minor changes
samantharamon Aug 23, 2024
abef267
Merge branch 'main' into samramon-shared-runtime-unified-manifest
samantharamon Sep 6, 2024
152d5b1
Update configure-your-add-in-to-use-a-shared-runtime.md
Rick-Kirkham Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 82 additions & 59 deletions docs/develop/configure-your-add-in-to-use-a-shared-runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,62 +10,99 @@ ms.localizationpriority: high

[!include[Shared runtime requirements](../includes/shared-runtime-requirements-note.md)]

You can configure your Office Add-in to run all of its code in a single [shared runtime](../testing/runtimes.md#shared-runtime). This enables better coordination across your add-in and access to the DOM and CORS from all parts of your add-in. It also enables additional features such as running code when the document opens, or enabling or disabling ribbon buttons. To configure your add-in to use a shared runtime, follow the instructions in this article.
You can configure your Office Add-in to run all of its code in a single [shared runtime](../testing/runtimes.md#shared-runtime). With a shared runtime, you'll have better coordination across your add-in and access to the DOM and CORS from all parts of your add-in. You'll also have access to additional features, such as running code when the document opens or activating ribbon buttons in certain contexts. To configure your add-in to use a shared runtime, follow the instructions in this article.

## Create the add-in project

If you are starting a new project, use the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md) to create an Excel, PowerPoint, or Word add-in project.
If you're starting a new project, use the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md) to create an Excel, PowerPoint, or Word add-in project.

Run the command `yo office --projectType taskpane --name "my office add in" --host <host> --js true`, where `<host>` is one of the following values.
> [!TIP]
> If you're using the Yeoman generator to create custom functions in Excel, select the following options:
>
> - **Project type**: `Excel Custom Functions using a Shared Runtime`
> - **Script type**: `JavaScript`

- excel
- powerpoint
- word
If your add-in uses an add-in only manifest, you can also use the steps in this article to update a Visual Studio project to use the shared runtime. However, you may need to update the XML schemas for the manifest. For more information, see [Troubleshoot development errors with Office Add-ins](../testing/troubleshoot-development-errors.md#manifest-schema-validation-errors-in-visual-studio-projects).

> [!IMPORTANT]
> The `--name` argument value must be in double quotation marks, even if it has no spaces.
## Configure the manifest

You can use different options for the **--projecttype**, **--name**, and **--js** command-line options. For the full list of options, see [Yeoman generator for Office Add-ins](https://github.com/OfficeDev/generator-office).
Follow these steps to configure a new or existing project to use a shared runtime. These steps assume you have generated your project using the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md). Select the tab for the type of manifest your add-in is using.

The generator will create the project and install supporting Node components. You can also use the steps in this article to update a Visual Studio project to use the shared runtime. However, you may need to update the XML schemas for the manifest. For more information, see [Troubleshoot development errors with Office Add-ins](../testing/troubleshoot-development-errors.md#manifest-schema-validation-errors-in-visual-studio-projects).
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)

## Configure the manifest
> [!NOTE]
> Implementing a shared runtime with the unified manifest for Microsoft 365 is in public developer preview. This shouldn't be used in production add-ins. We invite you to try it out in test or development environments. For more information, see the [Public developer preview app manifest schema](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview).

1. Open your add-in project in Visual Studio Code.
1. Open the **manifest.json** file.
1. Add the following object to the "extensions.runtimes" array. Note the following about this markup.
- The [SharedRuntime 1.1 requirement set](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets#sharedruntime-api-11) is specified in the "requirements.capabilities" object. This configures your add-in to run in a shared runtime on supported clients. For a list of clients that support the SharedRuntime 1.1 requirement set, see [Shared runtime requirement sets](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets).
- The "id" of the runtime is set to the descriptive name "SharedRuntime".
- The "lifetime" property is set to "long", so that your add-in can take advantage of features, such as starting your add-in when the document opens, continuing to run code after the task pane is closed, or using CORS and DOM from custom functions. If you set the property to "short" in this example, your add-in will start when one of your ribbon buttons is pressed, but it may shut down after your ribbon handler is done running. Similarly, your add-in will start when the task pane is opened, but it may shut down when the task pane is closed.

```json
"runtimes": [
"requirements": {
"capabilities": [
{
"name": "SharedRuntime",
"minVersion": "1.1"
}
]
},
"id": "SharedRuntime",
"type": "general",
"code": {
"page": "https://localhost:3000/taskpane.html"
},
"lifetime": "long",
"actions": [
...
]
]
```

1. Save your changes.

Follow these steps for a new or existing project to configure it to use a shared runtime. These steps assume you have generated your project using the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md).
# [Add-in only manifest](#tab/xmlmanifest)

1. Start Visual Studio Code and open your add-in project.
1. Open your add-in project in Visual Studio Code.
1. Open the **manifest.xml** file.
1. For an Excel or PowerPoint add-in, update the requirements section to include the [shared runtime](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets). Be sure to remove the `CustomFunctionsRuntime` requirement if it is present. The XML should appear as follows.
1. Update the requirements section to include the [shared runtime](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets) as follows.

```xml
<Hosts>
<Host Name="Workbook"/>
<Host ...>
</Hosts>
<Requirements>
<Sets DefaultMinVersion="1.1">
<Set Name="SharedRuntime" MinVersion="1.1"/>
</Sets>
</Requirements>
<DefaultSettings>
```

1. Find the **\<VersionOverrides\>** section and add the following **\<Runtimes\>** section. The lifetime needs to be **long** so that your add-in code can run even when the task pane is closed. The `resid` value is **Taskpane.Url**, which references the **taskpane.html** file location specified in the `<bt:Urls>` section near the bottom of the **manifest.xml** file.
1. Find the **\<VersionOverrides\>** section and add the following **\<Runtimes\>** section. Note the following about this markup.
- The lifetime needs to be **long** so that your add-in can take advantage of features, such as starting your add-in when the document opens, continuing to run code after the task pane is closed, or using CORS and DOM from custom functions. If you set the lifetime to **short** in this example, your add-in will start when one of your ribbon buttons is pressed, but it may shut down after your ribbon handler is done running. Similarly, your add-in will start when the task pane is opened, but it may shut down when the task pane is closed.
- The `resid` value is **Taskpane.Url**, which references the **taskpane.html** file location specified in the `<bt:Urls>` section near the bottom of the **manifest.xml** file.

> [!IMPORTANT]
> The shared runtime won't load if the `resid` uses different values in the manifest. If you change the value to something other than **Taskpane.Url**, be sure to also change the value in all locations shown in the following steps in this article.
>
> Also, the **\<Runtimes\>** section must be entered after the **\<Host\>** element in the exact order shown in the following XML.
> [!IMPORTANT]
> The shared runtime won't load if the `resid` uses different values in the manifest. If you change the value to something other than **Taskpane.Url**, be sure to also change the value in all locations shown in the following steps in this article.

```xml
<VersionOverrides ...>
<Hosts>
<Host ...>
<Runtimes>
<Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>
...
</Host>
```
- The **\<Runtimes\>** section must be entered after the **\<Host\>** element in the exact order shown in the following XML.

> [!NOTE]
> If your add-in includes the **\<Runtimes\>** element in the manifest (required for a shared runtime) and the conditions for using WebView2 (Microsoft Edge Chromium-based) are met, it uses that control. If the conditions are not met, then it uses the Trident (Internet Explorer 11) webview control regardless of the Windows or Microsoft 365 version. For more information, see [Runtimes](/javascript/api/manifest/runtimes) and [Browsers and webview controls used by Office Add-ins](../concepts/browsers-used-by-office-web-add-ins.md).

```xml
<VersionOverrides ...>
<Hosts>
<Host ...>
<Runtimes>
<Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>
...
</Host>
```

1. If you generated an Excel add-in with custom functions, find the **\<Page\>** element. Then change the source location from **Functions.Page.Url** to **Taskpane.Url**.

Expand All @@ -87,7 +124,9 @@ Follow these steps for a new or existing project to configure it to use a shared
...
```

1. Save the **manifest.xml** file.
1. Save your changes.

---

## Configure the webpack.config.js file

Expand Down Expand Up @@ -136,10 +175,10 @@ The **webpack.config.js** will build multiple runtime loaders. You need to modif

## Test your Office Add-in changes

You can confirm that you are using the shared runtime correctly by using the following instructions.
Confirm that you're using the shared runtime correctly by using the following instructions.

1. Open the **taskpane.js** file.
1. Replace the entire contents of the file with the following code. This will display a count of how many times the task pane has been opened. Adding the onVisibilityModeChanged event is only supported in a shared runtime.
1. Replace the entire contents of the file with the following code. This will display a count of how many times the task pane has been opened. Adding the `onVisibilityModeChanged` event is only supported in a shared runtime.

```javascript
/*global document, Office*/
Expand All @@ -151,8 +190,8 @@ You can confirm that you are using the shared runtime correctly by using the fol
document.getElementById("app-body").style.display = "flex";

updateCount(); // Update count on first open.
Office.addin.onVisibilityModeChanged(function (args) {
if (args.visibilityMode === "Taskpane") {
Office.addin.onVisibilityModeChanged((args) => {
if (args.visibilityMode === Office.VisibilityMode.taskpane) {
updateCount(); // Update count on subsequent opens.
}
});
Expand All @@ -170,45 +209,29 @@ You can confirm that you are using the shared runtime correctly by using the fol
npm start
```

Each time you open the task pane, the count of how many times it has been opened will be incremented. The value of **_count** will not be lost because the shared runtime keeps your code running even when the task pane is closed.
Each time you open the task pane, the count of how many times it has been opened will be incremented. The value of **_count** won't be lost because the shared runtime keeps your code running even when the task pane is closed.

When you're ready to stop the dev server and uninstall the add-in, run the following command.

```command&nbsp;line
npm stop
```

## Runtime lifetime

When you add the **\<Runtime\>** element, you also specify a lifetime with a value of `long` or `short`. Set this value to `long` to take advantage of features such as starting your add-in when the document opens, continuing to run code after the task pane is closed, or using CORS and DOM from custom functions.

> [!NOTE]
> The default lifetime value is `short`, but we recommend using `long` in Excel, PowerPoint, and Word add-ins. If you set your runtime to `short` in this example, your add-in will start when one of your ribbon buttons is pressed, but it may shut down after your ribbon handler is done running. Similarly, your add-in will start when the task pane is opened, but it may shut down when the task pane is closed.

```xml
<Runtimes>
<Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>
```

> [!NOTE]
> If your add-in includes the **\<Runtimes\>** element in the manifest (required for a shared runtime) and the conditions for using WebView2 (Microsoft Edge Chromium-based) are met, it uses that control. If the conditions are not met, then it uses the Trident (Internet Explorer 11) webview control regardless of the Windows or Microsoft 365 version. For more information, see [Runtimes](/javascript/api/manifest/runtimes) and [Browsers and webview controls used by Office Add-ins](../concepts/browsers-used-by-office-web-add-ins.md).

## About the shared runtime

On Windows or on Mac, your add-in will run code for ribbon buttons, custom functions, and the task pane in separate runtime environments. This creates limitations such as not being able to easily share global data, and not being able to access all CORS functionality from a custom function.
On Windows or on Mac, your add-in will run code for ribbon buttons, custom functions, and the task pane in separate runtime environments. This creates limitations, such as not being able to easily share global data, and not being able to access all CORS functionality from a custom function.

However, you can configure your Office Add-in to share code in the same runtime (also referred to as a shared runtime). This enables better coordination across your add-in and access to the task pane DOM and CORS from all parts of your add-in.

Configuring a shared runtime enables the following scenarios.

- Your Office Add-in can use additional UI features.
- [Enable and Disable Add-in Commands](../design/disable-add-in-commands.md)
- [Enable and disable add-in commands](../design/disable-add-in-commands.md)
- [Run code in your Office Add-in when the document opens](run-code-on-document-open.md)
- [Show or hide the task pane of your Office Add-in](show-hide-add-in.md)
- The following are available for Excel add-ins only.
- [Add Custom keyboard shortcuts to your Office Add-ins (preview)](../design/keyboard-shortcuts.md)
- [Create custom contextual tabs in Office Add-ins (preview)](../design/contextual-tabs.md)
- [Add custom keyboard shortcuts to your Office Add-ins](../design/keyboard-shortcuts.md)
- [Create custom contextual tabs in Office Add-ins](../design/contextual-tabs.md)
- Custom functions will have full CORS support.
- Custom functions can call Office.js APIs to read spreadsheet document data.

Expand All @@ -223,8 +246,8 @@ Don't design your add-in to use multiple task panes if you are planning to use a
## See also

- [Call Excel APIs from a custom function](../excel/call-excel-apis-from-custom-function.md)
- [Add custom keyboard shortcuts to your Office Add-ins (preview)](../design/keyboard-shortcuts.md)
- [Create custom contextual tabs in Office Add-ins (preview)](../design/contextual-tabs.md)
- [Add custom keyboard shortcuts to your Office Add-ins](../design/keyboard-shortcuts.md)
- [Create custom contextual tabs in Office Add-ins](../design/contextual-tabs.md)
- [Enable and Disable Add-in Commands](../design/disable-add-in-commands.md)
- [Run code in your Office Add-in when the document opens](run-code-on-document-open.md)
- [Show or hide the task pane of your Office Add-in](show-hide-add-in.md)
Expand Down