diff --git a/docs/excel/custom-functions-debugging.md b/docs/excel/custom-functions-debugging.md index 0bc32fc7ad..741f90a2fd 100644 --- a/docs/excel/custom-functions-debugging.md +++ b/docs/excel/custom-functions-debugging.md @@ -1,7 +1,7 @@ --- title: Custom functions debugging in a non-shared runtime description: Debug Excel custom functions that don't use a shared runtime. -ms.date: 11/06/2025 +ms.date: 04/21/2026 ms.topic: troubleshooting ms.localizationpriority: medium --- @@ -28,7 +28,7 @@ The process of debugging a custom function for add-ins that don't use a shared r ## Use the browser developer tools to debug custom functions in Excel on the web -Use the browser developer tools to debug custom functions that don't use a shared runtime in Excel on the web. The following steps work for Windows and macOS. +Use the browser developer tools to debug custom functions that don't use a shared runtime in Excel on the web. The following steps apply to custom functions add-ins with the add-in only manifest (**manifest.xml**). Use these steps on Windows or macOS. ### Run your add-in from Visual Studio Code @@ -40,9 +40,9 @@ Use the browser developer tools to debug custom functions that don't use a share 1. Open [Office on the web](https://office.live.com/). 1. Open a new Excel workbook. -1. Select **Home** > **Add-ins**, then select **More Settings**. +1. Select **Home** > **Add-ins**, then select **Advanced...**. 1. On the **Office Add-ins** dialog, select **Upload My Add-in**. -1. **Browse** to the add-in manifest file, and then select **Upload**. +1. **Browse** to the add-in **manifest.xml** file, and then select **Upload**. :::image type="content" source="../images/upload-add-in.png" alt-text="The upload add-in dialog with buttons for browse, upload, and cancel."::: @@ -51,7 +51,7 @@ Use the browser developer tools to debug custom functions that don't use a share ### Start debugging -1. Open your browser's developer tools. In Chrome and most browsers, press F12 to open the developer tools. +1. Open your browser's developer tools. In Chrome and most browsers, use F12 to open the developer tools. 1. In developer tools, open your source code script file using Cmd+P or Ctrl+P (**functions.js** or **functions.ts**). 1. [Set a breakpoint](https://code.visualstudio.com/Docs/editor/debugging#_breakpoints) in the custom function source code. @@ -74,7 +74,7 @@ If you don't use VS Code, run your add-in from the command line using tools such If your add-in doesn't sideload in the document, follow the steps in [Sideload your add-in](#sideload-your-add-in). Then continue to the next section to start debugging. -1. Open your browser's developer tools. In Chrome and most browsers, press F12 to open the developer tools. +1. Open your browser's developer tools. In Chrome and most browsers, use F12 to open the developer tools. 1. In developer tools, open your source code script file (**functions.js** or **functions.ts**). Your custom functions code may be located near the end of the file. 1. In the custom function source code, apply a breakpoint by selecting a line of code. diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index e044db0de0..6ce2889ccb 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -1,7 +1,7 @@ --- title: Manually create JSON metadata for custom functions in Excel description: Define JSON metadata for custom functions in Excel and associate your function ID and name properties. -ms.date: 01/05/2026 +ms.date: 04/20/2026 ms.localizationpriority: medium --- @@ -22,15 +22,48 @@ The following image explains the differences between using `yo office` scaffold :::image type="content" source="../images/custom-functions-json.png" alt-text="Image of differences between using the Yeoman generator for Office Add-ins and writing your own JSON."::: > [!NOTE] -> Remember to connect your manifest to the JSON file you create, through the `` section in your add-in only manifest file if you do not use the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md). +> Remember to connect your manifest to the JSON file you create. In the unified manifest, use the `customFunctions.metadataUrl` property. In the add-in only manifest, use the `` section. If you use the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md), this connection is configured automatically. ## Authoring metadata and connecting to the manifest Create a JSON file in your project and provide all the details about your functions in it, such as the function's parameters. See the [following metadata example](#json-metadata-example) and [the metadata reference](#metadata-reference) for a complete list of function properties. -Ensure your add-in only manifest file references your JSON file in the `` section, similar to the following example. +The way you connect your manifest file to your JSON metadata file depends on which manifest type you're using. + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +In the unified manifest, reference your JSON metadata file using the `customFunctions.metadataUrl` property within the `extensions` array: ```json +{ + "extensions": [ + { + "requirements": { + "scopes": ["workbook"], + "capabilities": [ + { + "name": "CustomFunctionsRuntime", + "minVersion": "1.1" + } + ] + }, + "customFunctions": { + "namespace": { + "id": "CONTOSO", + "name": "CONTOSO" + }, + "metadataUrl": "https://subdomain.contoso.com/config/customfunctions.json" + } + } + ] +} +``` + +# [Add-in only manifest](#tab/xmlmanifest) + +Ensure that your add-in only manifest file references your JSON file in the `` section, similar to the following example. + +```xml @@ -43,6 +76,8 @@ Ensure your add-in only manifest file references your JSON file in the ` ``` +--- + ## JSON metadata example The following example shows the contents of a JSON metadata file for an add-in that defines custom functions. The sections that follow this example provide detailed information about the individual properties within this JSON example. diff --git a/docs/excel/custom-functions-naming.md b/docs/excel/custom-functions-naming.md index eea46eb62f..91710435ad 100644 --- a/docs/excel/custom-functions-naming.md +++ b/docs/excel/custom-functions-naming.md @@ -1,7 +1,7 @@ --- title: Naming and localization for custom functions in Excel description: Learn requirements for names of Excel custom functions and how to localize custom functions. -ms.date: 10/22/2025 +ms.date: 04/20/2026 ms.localizationpriority: medium --- @@ -46,6 +46,31 @@ Fix conflicts by renaming your function or uninstalling the other add-in. For te - For streaming functions, add `STREAM` to the name or include a note in the description. - Use a short vendor prefix in your function names to avoid conflicts with other add-ins. For example, use `CONTOSO_GETPRICE` or `CONTOSO_TAX_CALC`. +## Namespace configuration + +The namespace for your custom functions is configured in the manifest file. The configuration approach depends on which manifest type you're using. + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +In the unified manifest, configure the namespace in the `customFunctions.namespace` object: + +```json +"customFunctions": { + "namespace": { + "id": "CONTOSO", + "name": "CONTOSO" + } +} +``` + +The `id` property is used internally and must remain stable, while the `name` property is the display name that users see in Excel and can be localized. + +# [Add-in only manifest](#tab/xmlmanifest) + +In the add-in only manifest, specify the namespace using the `` element in the `` section. The namespace value should follow the naming guidelines described in this article. + +--- + [!include[manifest guidance](../includes/manifest-guidance.md)] ## Naming constraints quick reference diff --git a/docs/excel/custom-functions-overview.md b/docs/excel/custom-functions-overview.md index 8d316906cd..23f17bb569 100644 --- a/docs/excel/custom-functions-overview.md +++ b/docs/excel/custom-functions-overview.md @@ -1,7 +1,7 @@ --- description: Create an Excel custom function for your Office Add-in. title: Create custom functions in Excel -ms.date: 01/22/2026 +ms.date: 04/20/2026 ms.topic: overview ms.custom: scenarios:getting-started ms.localizationpriority: high @@ -37,7 +37,7 @@ If you use the [Yeoman generator for Office Add-ins](../develop/yeoman-generator |------|-------------|-------------| | **./src/functions/functions.js**
or
**./src/functions/functions.ts** | JavaScript
or
TypeScript | Contains the code that defines custom functions. | | **./src/functions/functions.html** | HTML | Provides a <script> reference to the JavaScript file that defines custom functions. | -| **./manifest.xml** | XML | Specifies the location of multiple files that your custom function use, such as the custom functions JavaScript, JSON, and HTML files. It also lists the locations of task pane files, command files, and specifies which runtime your custom functions should use. | +| **./manifest.xml** or **./manifest.json** | XML or JSON | Specifies the location of multiple files that your custom function use, such as the custom functions JavaScript, JSON, and HTML files. It also lists the locations of task pane files, command files, and specifies which runtime your custom functions should use. The Yeoman generator for Office Add-ins creates a project with an XML manifest. | > [!TIP] > The Yeoman generator for Office Add-ins offers multiple **Excel Custom Functions** projects. We recommend selecting the project type **Excel Custom Functions using a Shared Runtime** and the script type **JavaScript**. @@ -69,13 +69,29 @@ function add(first, second){ ### Manifest file +The manifest file for an add-in that defines custom functions configures the namespace, specifies file locations, and defines the runtime. Select the tab for the manifest type you're using. + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +The unified manifest for an add-in that defines custom functions (**./manifest.json** in the project) does several things. + +- Defines the namespace for your custom functions using the `customFunctions.namespace` object. A namespace prepends itself to your custom functions to help customers identify your functions as part of your add-in. +- Uses the `customFunctions` extension to specify metadata about custom functions, including the JSON metadata file location via the `metadataUrl` property. +- Configures the runtime for custom functions using the `runtimes` array with an `actions.type` property set to `"executeFunction"`. + +To see a full working manifest from a sample add-in, see the manifest in [one of our Office Add-in samples GitHub repositories](https://github.com/OfficeDev/Office-Add-in-samples/blob/main/Samples/excel-shared-runtime-scenario/manifest.json). + +--- + +# [Add-in only manifest](#tab/xmlmanifest) + The add-in only manifest file for an add-in that defines custom functions (**./manifest.xml** in the project that the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md) creates) does several things. - Defines the namespace for your custom functions. A namespace prepends itself to your custom functions to help customers identify your functions as part of your add-in. - Uses `` and `` elements that are unique to a custom functions manifest. These elements contain the information about the locations of the JavaScript, JSON, and HTML files. -- Specifies which runtime to use for your custom function. We recommend always using a shared runtime unless you have a specific need for another runtime, because a shared runtime allows for the sharing of data between functions and the task pane. +- Specifies the runtime to use for your custom function. We recommend that you always use a shared runtime unless you have a specific need for another runtime, because a shared runtime allows for the sharing of data between functions and the task pane. -To see a full working manifest from a sample add-in, see the manifest in the [one of our Office Add-in samples Github repositories](https://github.com/OfficeDev/Office-Add-in-samples/blob/main/Samples/excel-shared-runtime-global-state/manifest.xml). +To see a full working manifest from a sample add-in, see the manifest in [one of our Office Add-in samples GitHub repositories](https://github.com/OfficeDev/Office-Add-in-samples/blob/main/Samples/excel-shared-runtime-global-state/manifest.xml). [!include[manifest guidance](../includes/manifest-guidance.md)] @@ -89,8 +105,6 @@ For more information on coauthoring, see [About coauthoring in Excel](/office/vb Excel custom functions are supported by most Office client applications. Excel custom functions aren't currently supported in **Office on iPad** or **volume-licensed perpetual versions of Office 2021 or earlier on Windows**. For more information, see [Custom functions requirement sets](/javascript/api/requirement-sets/excel/custom-functions-requirement-sets). -[!include[Excel custom functions note](../includes/excel-custom-functions-note.md)] - ## Next steps Want to try out custom functions? Check out the simple [custom functions quick start](../quickstarts/excel-custom-functions-quickstart.md) or the more in-depth [custom functions tutorial](../tutorials/excel-tutorial-create-custom-functions.md) if you haven't already. diff --git a/docs/excel/custom-functions-troubleshooting.md b/docs/excel/custom-functions-troubleshooting.md index 78af4cf54c..1476cbdda4 100644 --- a/docs/excel/custom-functions-troubleshooting.md +++ b/docs/excel/custom-functions-troubleshooting.md @@ -1,5 +1,5 @@ --- -ms.date: 08/26/2025 +ms.date: 04/20/2026 description: Troubleshoot common problems with Excel custom functions. title: Troubleshoot custom functions ms.topic: troubleshooting @@ -10,9 +10,7 @@ ms.localizationpriority: medium When developing custom functions, you may encounter errors in the product while creating and testing your functions. -[!include[Excel custom functions note](../includes/excel-custom-functions-note.md)] - -To resolve issues, you can [enable runtime logging to capture errors](#enable-runtime-logging) and refer to [Excel's native error messages](#check-for-excel-error-messages). Also, check for common mistakes such as [leaving promises unresolved](#ensure-promises-return). +To resolve issues, [enable runtime logging to capture errors](#enable-runtime-logging) and refer to [Excel error messages](#check-for-excel-error-messages). Also, check for common mistakes such as [leaving promises unresolved](#ensure-promises-return). ## Debugging custom functions @@ -28,7 +26,7 @@ If you're testing your add-in in Office on Windows, you should [enable runtime l Excel has a number of built-in error messages which are returned to a cell if there is calculation error. Custom functions only use the following error messages: `#NULL!`, `#DIV/0!`, `#VALUE!`, `#REF!`, `#NAME?`, `#NUM!`, `#N/A`, and `#BUSY!`. -Generally, these errors correspond to the errors you might already be familiar with in Excel. The are only a few exceptions specific to custom functions, listed here: +Generally, these errors correspond to the errors you might already be familiar with in Excel. There are only a few exceptions specific to custom functions, listed here: - A `#NAME?` error generally means there has been an issue registering your functions. For additional information, see [Custom functions showing #NAME? error](#custom-functions-showing-name-error). - A `#N/A` error is also maybe a sign that that function while registered could not be run. This is typically due to a missing `CustomFunctions.associate` command. diff --git a/docs/includes/excel-custom-functions-note.md b/docs/includes/excel-custom-functions-note.md deleted file mode 100644 index c7677cd6b4..0000000000 --- a/docs/includes/excel-custom-functions-note.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!NOTE] -> The unified manifest for Microsoft 365 doesn't currently support custom functions projects. You must use the add-in only manifest for custom functions projects. For more information, see [Office Add-ins manifest](../develop/add-in-manifests.md). diff --git a/docs/quickstarts/excel-custom-functions-quickstart.md b/docs/quickstarts/excel-custom-functions-quickstart.md index be1f9f0925..eed8a870e0 100644 --- a/docs/quickstarts/excel-custom-functions-quickstart.md +++ b/docs/quickstarts/excel-custom-functions-quickstart.md @@ -1,7 +1,7 @@ --- title: Custom functions quick start description: Developing custom functions in Excel quick start guide. -ms.date: 08/22/2024 +ms.date: 04/20/2026 ms.service: excel ms.localizationpriority: high --- @@ -28,7 +28,7 @@ To start, you'll use the Yeoman generator to create the custom functions project The Yeoman generator will create the project files and install supporting Node components. -1. The Yeoman generator will give you some instructions in your command line about what to do with the project, but ignore them and continue to follow our instructions. Navigate to the root folder of the project. +1. The Yeoman generator gives you instructions in your command line about the project, but you should continue to follow the instructions in this article. Navigate to the root folder of the project. ```command line cd "My custom functions add-in"