From 7835fbb9ad16168c57a43c1355e562045be78734 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Thu, 22 Aug 2024 15:37:49 -0700 Subject: [PATCH 1/3] Add unified manifest support --- ...ure-your-add-in-to-use-a-shared-runtime.md | 135 ++++++++++-------- 1 file changed, 78 insertions(+), 57 deletions(-) diff --git a/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md b/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md index 7e2a31575..830b51090 100644 --- a/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md +++ b/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md @@ -10,62 +10,97 @@ 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 --js true`, where `` 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). -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": [ + ... + ] + ] + ``` -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 - + - ``` -1. Find the **\** section and add the following **\** 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 `` section near the bottom of the **manifest.xml** file. +1. Find the **\** section and add the following **\** 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 `` 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 **\** section must be entered after the **\** 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 - - - - - - - ... - - ``` + - The **\** section must be entered after the **\** element in the exact order shown in the following XML. + + > [!NOTE] + > If your add-in includes the **\** 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 + + + + + + + ... + + ``` 1. If you generated an Excel add-in with custom functions, find the **\** element. Then change the source location from **Functions.Page.Url** to **Taskpane.Url**. @@ -89,6 +124,8 @@ Follow these steps for a new or existing project to configure it to use a shared 1. Save the **manifest.xml** file. +--- + ## Configure the webpack.config.js file The **webpack.config.js** will build multiple runtime loaders. You need to modify it to load only the shared runtime via the **taskpane.html** file. @@ -136,7 +173,7 @@ 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. @@ -151,8 +188,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. } }); @@ -170,39 +207,23 @@ 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. - -## Runtime lifetime - -When you add the **\** 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 - - - -``` - -> [!NOTE] -> If your add-in includes the **\** 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). +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. ## 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. @@ -221,8 +242,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) From d46b75010802e9815037e945803f6caf9ffe5901 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Fri, 23 Aug 2024 13:11:01 -0700 Subject: [PATCH 2/3] Apply minor changes --- .../configure-your-add-in-to-use-a-shared-runtime.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md b/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md index 830b51090..183e90d56 100644 --- a/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md +++ b/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md @@ -2,7 +2,7 @@ title: Configure your Office Add-in to use a shared runtime description: Configure your Office Add-in to use a shared runtime to support additional ribbon, task pane, and custom function features. ms.topic: how-to -ms.date: 05/20/2023 +ms.date: 08/23/2024 ms.localizationpriority: high --- @@ -26,7 +26,7 @@ If your add-in uses an add-in only manifest, you can also use the steps in this ## Configure the manifest -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). +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. # [Unified manifest for Microsoft 365](#tab/jsonmanifest) @@ -62,6 +62,8 @@ Follow these steps to configure a new or existing project to use a shared runtim ] ``` +1. Save your changes. + # [Add-in only manifest](#tab/xmlmanifest) 1. Open your add-in project in Visual Studio Code. @@ -122,7 +124,7 @@ Follow these steps to configure a new or existing project to use a shared runtim ... ``` -1. Save the **manifest.xml** file. +1. Save your changes. --- @@ -176,7 +178,7 @@ The **webpack.config.js** will build multiple runtime loaders. You need to modif 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*/ From 152d5b10b3d27e6de44f3ae0d7a264b4e73c5c35 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Mon, 7 Oct 2024 14:52:54 -0700 Subject: [PATCH 3/3] Update configure-your-add-in-to-use-a-shared-runtime.md --- docs/develop/configure-your-add-in-to-use-a-shared-runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md b/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md index 44b8caa8f..a1e10da03 100644 --- a/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md +++ b/docs/develop/configure-your-add-in-to-use-a-shared-runtime.md @@ -22,7 +22,7 @@ If you're starting a new project, use the [Yeoman generator for Office Add-ins]( > - **Project type**: `Excel Custom Functions using a Shared Runtime` > - **Script type**: `JavaScript` -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). +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). ## Configure the manifest