You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
13
+
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.
14
14
15
15
## Create the add-in project
16
16
17
-
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.
17
+
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.
18
18
19
-
Run the command `yo office --projectType taskpane --name "my office add in" --host <host> --js true`, where `<host>` is one of the following values.
19
+
> [!TIP]
20
+
> If you're using the Yeoman generator to create custom functions in Excel, select the following options:
21
+
>
22
+
> -**Project type**: `Excel Custom Functions using a Shared Runtime`
23
+
> -**Script type**: `JavaScript`
20
24
21
-
- excel
22
-
- powerpoint
23
-
- word
25
+
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#add-in-only-manifest-schema-validation-errors-in-visual-studio-projects).
24
26
25
-
> [!IMPORTANT]
26
-
> The `--name` argument value must be in double quotation marks, even if it has no spaces.
27
+
## Configure the manifest
27
28
28
-
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).
29
+
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.
29
30
30
-
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#add-in-only-manifest-schema-validation-errors-in-visual-studio-projects).
31
+
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
31
32
32
-
## Configure the manifest
33
+
> [!NOTE]
34
+
> 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).
35
+
36
+
1. Open your add-in project in Visual Studio Code.
37
+
1. Open the **manifest.json** file.
38
+
1. Add the following object to the "extensions.runtimes" array. Note the following about this markup.
39
+
- 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).
40
+
- The "id" of the runtime is set to the descriptive name "SharedRuntime".
41
+
- 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.
42
+
43
+
```json
44
+
"runtimes": [
45
+
"requirements": {
46
+
"capabilities": [
47
+
{
48
+
"name": "SharedRuntime",
49
+
"minVersion": "1.1"
50
+
}
51
+
]
52
+
},
53
+
"id": "SharedRuntime",
54
+
"type": "general",
55
+
"code": {
56
+
"page": "https://localhost:3000/taskpane.html"
57
+
},
58
+
"lifetime": "long",
59
+
"actions": [
60
+
...
61
+
]
62
+
]
63
+
```
64
+
65
+
1. Save your changes.
33
66
34
-
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).
67
+
# [Add-in only manifest](#tab/xmlmanifest)
35
68
36
-
1.Start Visual Studio Code and open your add-in project.
69
+
1. Open your add-in project in Visual Studio Code.
37
70
1. Open the **manifest.xml** file.
38
-
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.
71
+
1. Update the requirements section to include the [shared runtime](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets) as follows.
39
72
40
73
```xml
41
74
<Hosts>
42
-
<HostName="Workbook"/>
75
+
<Host ...>
43
76
</Hosts>
44
77
<Requirements>
45
78
<Sets DefaultMinVersion="1.1">
46
79
<Set Name="SharedRuntime" MinVersion="1.1"/>
47
80
</Sets>
48
81
</Requirements>
49
-
<DefaultSettings>
50
82
```
51
83
52
-
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.
84
+
1. Find the **\<VersionOverrides\>** section and add the following **\<Runtimes\>** section. Note the following about this markup.
85
+
- 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.
86
+
- 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.
53
87
54
-
> [!IMPORTANT]
55
-
> 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.
56
-
>
57
-
> Also, the **\<Runtimes\>** section must be entered after the **\<Host\>** element in the exact order shown in the following XML.
88
+
> [!IMPORTANT]
89
+
> 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.
58
90
59
-
```xml
60
-
<VersionOverrides ...>
61
-
<Hosts>
62
-
<Host ...>
63
-
<Runtimes>
64
-
<Runtimeresid="Taskpane.Url"lifetime="long" />
65
-
</Runtimes>
66
-
...
67
-
</Host>
68
-
```
91
+
- The **\<Runtimes\>** section must be entered after the **\<Host\>** element in the exact order shown in the following XML.
92
+
93
+
> [!NOTE]
94
+
> 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).
95
+
96
+
```xml
97
+
<VersionOverrides ...>
98
+
<Hosts>
99
+
<Host ...>
100
+
<Runtimes>
101
+
<Runtime resid="Taskpane.Url" lifetime="long" />
102
+
</Runtimes>
103
+
...
104
+
</Host>
105
+
```
69
106
70
107
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**.
71
108
@@ -87,7 +124,9 @@ Follow these steps for a new or existing project to configure it to use a shared
87
124
...
88
125
```
89
126
90
-
1. Save the **manifest.xml** file.
127
+
1. Save your changes.
128
+
129
+
---
91
130
92
131
## Configure the webpack.config.js file
93
132
@@ -136,10 +175,10 @@ The **webpack.config.js** will build multiple runtime loaders. You need to modif
136
175
137
176
## Test your Office Add-in changes
138
177
139
-
You can confirm that you are using the shared runtime correctly by using the following instructions.
178
+
Confirm that you're using the shared runtime correctly by using the following instructions.
140
179
141
180
1. Open the **taskpane.js** file.
142
-
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.
181
+
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.
143
182
144
183
```javascript
145
184
/*global document, Office*/
@@ -151,8 +190,8 @@ You can confirm that you are using the shared runtime correctly by using the fol
if (args.visibilityMode===Office.VisibilityMode.taskpane) {
156
195
updateCount(); // Update count on subsequent opens.
157
196
}
158
197
});
@@ -170,40 +209,24 @@ You can confirm that you are using the shared runtime correctly by using the fol
170
209
npm start
171
210
```
172
211
173
-
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.
212
+
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.
174
213
175
214
When you're ready to stop the dev server and uninstall the add-in, run the following command.
176
215
177
216
```command line
178
217
npm stop
179
218
```
180
219
181
-
## Runtime lifetime
182
-
183
-
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.
184
-
185
-
> [!NOTE]
186
-
> 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.
187
-
188
-
```xml
189
-
<Runtimes>
190
-
<Runtime resid="Taskpane.Url" lifetime="long" />
191
-
</Runtimes>
192
-
```
193
-
194
-
> [!NOTE]
195
-
> 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).
196
-
197
220
## About the shared runtime
198
221
199
-
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.
222
+
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.
200
223
201
224
However, you can configure your Office Add-in to share code in the same runtime (alsoreferredtoasasharedruntime). This enables better coordination across your add-in and access to the task pane DOM and CORS from all parts of your add-in.
202
225
203
226
Configuring a shared runtime enables the following scenarios.
204
227
205
228
- Your Office Add-in can use additional UI features.
206
-
- [Enable and Disable Add-in Commands](../design/disable-add-in-commands.md)
229
+
- [Enable and disable add-in commands](../design/disable-add-in-commands.md)
207
230
- [Run code in your Office Add-in when the document opens](run-code-on-document-open.md)
208
231
- [Show or hide the task pane of your Office Add-in](show-hide-add-in.md)
209
232
- The following are available for Excel add-ins only.
0 commit comments