Merge branch 'main' into live

Author: github-actions

docs/develop/agents-toolkit-overview.md

@@ -58,7 +58,7 @@ Install the latest version of Agents Toolkit into Visual Studio Code as describe
     - **PowerPoint Desktop (Edge Chromium)**
     - **Word Desktop (Edge Chromium)**
 
-1. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, the desktop version of the Office application you selected opens.
+1. Press <kbd>F5</kbd>. The project builds and a Node dev-server window opens. This process may take a couple of minutes. Eventually, the desktop version of the Office application you selected opens.
 
     > [!NOTE]
     > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.
@@ -82,7 +82,7 @@ Install the latest version of Agents Toolkit into Visual Studio Code as describe
 1. **Close Outlook desktop**.
 1. In Visual Studio Code, open Agents Toolkit.
 1. In the **ACCOUNTS** section, verify that you're signed into Microsoft 365.
-1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select the option, **Outlook Desktop (Edge Chromium)**, and then press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then Outlook desktop will open.
+1. Select **View** | **Run** in Visual Studio Code. In the **RUN AND DEBUG** dropdown menu, select the option, **Outlook Desktop (Edge Chromium)**, and then press <kbd>F5</kbd>. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then Outlook desktop will open.
 
     > [!NOTE]
     > If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts.

docs/excel/custom-functions-troubleshooting.md

@@ -1,5 +1,5 @@
 ---
-ms.date: 06/09/2022
+ms.date: 05/20/2025
 description: Troubleshoot common problems with Excel custom functions.
 title: Troubleshoot custom functions
 ms.topic: troubleshooting
@@ -38,6 +38,47 @@ Generally, these errors correspond to the errors you might already be familiar w
 
 Information about custom functions is cached by Office. Sometimes while developing and repeatedly reloading an add-in with custom functions your changes may not appear. You can fix this by clearing the Office cache. For more information, see [Clear the Office cache](../testing/clear-cache.md).
 
+### Clear the custom functions cache when your add-in runs
+
+There may be times when you need to clear the custom functions cache for an add-in deployed to your end users, so that add-in updates and custom functions setting changes are incorporated at the same time. Without triggering a custom functions cache clear, changes to the **functions.json** and **functions.js** files may take up to 24 hours to reach your end users, while changes to **taskpane.html** reach end users more quickly.
+
+> [!NOTE]
+> Once this setting is turned on for a document, it takes effect the next time the document is opened with the add-in. It doesn't apply immediately after the function is called.
+
+To ensure that the custom functions cache is cleared by your add-in, add the following code to your **functions.js** file, and then call the `setForceRefreshOn` method in your `Office.onReady` call or other add-in initialization logic.
+
+> [!IMPORTANT]
+> This process for clearing the custom functions cache is only supported for custom functions add-ins that use a [shared runtime](../testing/runtimes.md#shared-runtime).
+
+```javascript
+// To enable custom functions cache clearing, add this method to your functions.js 
+// file, and then call the `setForceRefreshOn` method in your `Office.onReady` call.
+function setForceRefreshOn() {  
+    Office.context.document.settings.set(  
+        'Office.ForceRefreshCustomFunctionsCache',
+        true  
+    );  
+    Office.context.document.settings.saveAsync();  
+}
+```
+
+> [!TIP]
+> Frequently refreshing the custom functions cache can impact performance, so clearing the custom functions cache with `setForceRefreshOn` should only be used during add-in development or to resolve bugs. Once a custom functions add-in is stabilized, stop forcing cache refreshes.
+
+To disable the custom functions cache clear in your add-in, set `Office.ForceRefreshCustomFunctionsCache` to `false` and call the method in your `Office.onReady` call. The following code sample shows an example with a `setForceRefreshOff` method.
+
+```javascript
+// To disable custom functions cache clearing, add this method to your functions.js 
+// file, and then call the `setForceRefreshOff` method in your `Office.onReady` call.
+function setForceRefreshOff() {  
+    Office.context.document.settings.set(  
+        'Office.ForceRefreshCustomFunctionsCache',
+        false  
+    );  
+    Office.context.document.settings.saveAsync();  
+}
+```
+
 ## Common problems and solutions
 
 ### Can't open add-in from localhost: Use a local loopback exemption

docs/images/block-on-send-subject-cc-inforbar.png renamed to docs/images/block-on-send-subject-cc-infobar.png

@@ -4,7 +4,7 @@ description: Nested app authentication and Outlook legacy tokens deprecation FAQ
 ms.service: microsoft-365
 ms.subservice: add-ins
 ms.topic: faq
-ms.date: 05/19/2025
+ms.date: 05/22/2025
 ---
 
 # Nested app authentication and Outlook legacy tokens deprecation FAQ
@@ -24,7 +24,7 @@ Legacy Exchange online tokens have already been turned off for most tenants. We'
 | Date     | Legacy tokens status |
 | -------- | ------------------------------------------------------ |
 | Now | Legacy tokens turned off for most tenants. Admins can reenable legacy tokens via PowerShell. |
-| Jun 2025 | Legacy tokens turned off for all tenants. Admins can no longer reenable legacy tokens via PowerShell and must contact Microsoft for any exception. |
+| Jun 2025 | Legacy tokens turned off for all tenants. Admins can no longer reenable legacy tokens via PowerShell. Admins can request an exception through Microsoft Support at [https://aka.ms/LegacyTokensByOctober](https://aka.ms/LegacyTokensByOctober) (this link requires you to sign in to your tenant). |
 | Oct 2025 | Legacy tokens turned off for all tenants. Exceptions are no longer allowed. |
 
 ### When is NAA generally available for my channel?
@@ -138,7 +138,7 @@ Use the following steps to perform the test.
 
 Yes, there are PowerShell commands you can use to turn legacy tokens on or off in any tenant. For more information on how to turn legacy tokens on or off, see [Turn legacy Exchange Online tokens on or off](turn-exchange-tokens-on-off.md).
 
-In June 2025, legacy tokens will be turned off and you won't be able to turn them back on without a specific exception granted by Microsoft. In October 2025, it won't be possible to turn on legacy tokens and they'll be disabled for all tenants.
+In June 2025, legacy tokens will be turned off and you won't be able to turn them back on. Admins can request an exception through Microsoft Support at [https://aka.ms/LegacyTokensByOctober](https://aka.ms/LegacyTokensByOctober) (this link requires you to sign in to your tenant). In October 2025, it won't be possible to turn on legacy tokens and they'll be disabled for all tenants.
 
 ### How does the admin consent flow work?
 

docs/outlook/faq-nested-app-auth-outlook-legacy-tokens.md

@@ -1,7 +1,7 @@
 ---
 title: Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts
 description: Learn about the Smart Alerts implementation and how it handles the OnMessageSend and OnAppointmentSend events in your event-based Outlook add-in.
-ms.date: 03/11/2025
+ms.date: 05/22/2025
 ms.topic: concept-article
 ms.localizationpriority: medium
 ---
@@ -340,8 +340,9 @@ While Smart Alerts and the [on-send feature](outlook-on-send-addins.md) provide
 |-----|-----|-----|
 |**Minimum supported requirement set**|[Mailbox 1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)|[Mailbox 1.8](/javascript/api/requirement-sets/outlook/requirement-set-1.8/outlook-requirement-set-1.8)|
 |**Supported Outlook clients**|<ul><li>Windows (new and classic)</li><li>Web browser (modern UI)</li><li>Mac (new UI)</li></ul>|<ul><li>Windows (classic)</li><li>Web browser (modern and classic UI)</li><li>Mac (new and classic UI)</li></ul>|
-|**Supported events**|**Add-in only manifest**<ul><li>`OnMessageSend`</li><li>`OnAppointmentSend`</li></ul><br>**Unified manifest for Microsoft 365**<ul><li>`"messageSending"`</li><li>`"appointmentSending"`</li></ul>|**Add-in only manifest**<ul><li>`ItemSend`</li></ul><br>**Unified manifest for Microsoft 365**<ul><li>Not supported</li></ul>|
-|**Manifest extension property**|**Add-in only manifest**<ul><li>`LaunchEvent`</li></ul><br>**Unified manifest for Microsoft 365**<ul><li>`"autoRunEvents"`</li></ul>|**Add-in only manifest**<ul><li>`Events`</li></ul><br>**Unified manifest for Microsoft 365**<ul><li>Not supported</li></ul>|
+|**Supported manifest types**|<ul><li>Unified manifest for Microsoft 365</li><li>Add-in only manifest</li></ul>|Add-in only manifest|
+|**Supported events**|**Add-in only manifest**<ul><li>`OnMessageSend`</li><li>`OnAppointmentSend`</li></ul><br>**Unified manifest for Microsoft 365**<ul><li>`"messageSending"`</li><li>`"appointmentSending"`</li></ul>|`ItemSend`|
+|**Manifest extension property**|**Add-in only manifest**<ul><li>`LaunchEvent`</li></ul><br>**Unified manifest for Microsoft 365**<ul><li>`"autoRunEvents"`</li></ul>|`Events`|
 |**Supported send mode options**|<ul><li>prompt user</li><li>soft block</li><li>block</li></ul><br>To learn more about each option, see [Available send mode options](#available-send-mode-options).|Block|
 |**Maximum number of supported events in an add-in**|One `OnMessageSend` and one `OnAppointmentSend` event.|One `ItemSend` event.|
 |**Add-in deployment**|Add-in can be published to AppSource if its send mode property is set to the **soft block** or **prompt user** option. Otherwise, the add-in must be deployed by an organization's administrator.|Add-in can't be published to AppSource. It must be deployed by an organization's administrator.|

docs/outlook/onmessagesend-onappointmentsend-events.md

@@ -1,16 +1,26 @@
 ---
 title: On-send feature for Outlook add-ins
 description: Provides a way to handle an item or block users from certain actions, and allows an add-in to set certain properties on send.
-ms.date: 04/12/2024
+ms.date: 05/22/2025
 ms.localizationpriority: medium
 ---
 
 # On-send feature for Outlook add-ins
 
-The on-send feature for Outlook add-ins provides a way to handle a message or meeting item, or block users from certain actions, and allows an add-in to set certain properties on send.
+> [!IMPORTANT]
+>
+> We recommend using [Smart Alerts](onmessagesend-onappointmentsend-events.md) instead of the on-send feature to check that certain conditions are met before a mail item is sent. Smart Alerts was released in [requirement set 1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12) and introduced the `OnMessageSend` and `OnAppointmentSend` events.
+>
+> Smart Alerts provides the following benefits.
+>
+> - It offers [send mode options](onmessagesend-onappointmentsend-events.md#available-send-mode-options) when you want to provide your users with optional recommendations instead of mandatory conditions, so that they won't be unnecessarily blocked from sending messages. For example, with the **soft block** option, users can still send messages even if the add-in is unavailable during an outage. This option isn't supported by the on-send feature.
+> - It allows your add-in to be published to AppSource if the send mode property is set to the **prompt user** or **soft block** option. To learn more about publishing an event-based add-in, see [AppSource listing options for your event-based Outlook add-in](autolaunch-store-options.md).
+>
+> The on-send feature should only be used to support older Outlook versions that don't support the Smart Alerts feature. For improved security, we encourage users to upgrade to the latest version of Outlook.
+>
+> For more information on the differences between Smart Alerts and the on-send feature, see [Differences between Smart Alerts and the on-send feature](onmessagesend-onappointmentsend-events.md#differences-between-smart-alerts-and-the-on-send-feature). [Try out Smart Alerts by completing the walkthrough](smart-alerts-onmessagesend-walkthrough.md).
 
-> [!NOTE]
-> The on-send feature isn't supported in add-ins that use the [Unified manifest for Microsoft 365](../develop/unified-manifest-overview.md). Achieve similar effects by using [event-based activation](autolaunch.md) and implementing a handler for the **OnMessageSend** or **OnAppointmentSend** events, or both. See also the note below about Smart Alerts.
+The on-send feature for Outlook add-ins provides a way to handle a message or meeting item, or block users from certain actions, and allows an add-in to set certain properties on send.
 
 For example, use the on-send feature to:
 
@@ -21,14 +31,6 @@ The on-send feature is triggered by the `ItemSend` event type and is UI-less.
 
 For information about limitations related to the on-send feature, see [Limitations](#limitations) later in this article.
 
-> [!NOTE]
-> [Smart Alerts](onmessagesend-onappointmentsend-events.md) is a newer version of the on-send feature. It was released in [requirement set 1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12) and introduced the `OnMessageSend` and `OnAppointmentSend` events. Similar to the on-send feature, Smart Alerts enables your add-in to check that certain conditions are met before a mail item is sent. Smart Alerts differentiates itself from the on-send feature as follows:
->
-> - It offers [send mode options](onmessagesend-onappointmentsend-events.md#available-send-mode-options) when you want to provide your users with optional recommendations instead of mandatory conditions.
-> - It allows your add-in to be published to AppSource if the send mode property is set to the **prompt user** or **soft block** option. To learn more about publishing an event-based add-in, see [AppSource listing options for your event-based Outlook add-in](autolaunch-store-options.md).
->
-> For more information on the differences between Smart Alerts and the on-send feature, see [Differences between Smart Alerts and the on-send feature](onmessagesend-onappointmentsend-events.md#differences-between-smart-alerts-and-the-on-send-feature). We invite you to [try out Smart Alerts by completing the walkthrough](smart-alerts-onmessagesend-walkthrough.md).
-
 ## Supported clients and platforms
 
 The following table shows supported client-server combinations for the on-send feature, including the minimum required Cumulative Update where applicable. Excluded combinations are not supported.
@@ -61,11 +63,11 @@ Validation is done on the client side in Outlook when the send event is triggere
 
 The following screenshot shows an information bar that notifies the sender to add a subject.
 
-![An error message prompting the user to enter a missing subject line.](../images/block-on-send-subject-cc-inforbar.png)
+:::image type="content" source="../images/block-on-send-subject-cc-infobar.png" alt-text="An error message prompting the user to enter a missing subject line.":::
 
 The following screenshot shows an information bar that notifies the sender that blocked words were found.
 
-![An error message telling the user that blocked words were found.](../images/block-on-send-body.png)
+:::image type="content" source="../images/block-on-send-body.png" alt-text="An error message notifying the user that blocked words were found.":::
 
 ## Limitations
 
@@ -77,7 +79,7 @@ The on-send feature currently has the following limitations.
   > [!IMPORTANT]
   > When running `npm run validate` to [validate your add-in's manifest](../testing/troubleshoot-manifest.md), you'll receive the error, "Mailbox add-in containing ItemSend event is invalid. Mailbox add-in manifest contains ItemSend event in VersionOverrides which is not allowed." This message appears because add-ins that use the `ItemSend` event, which is required for this version of the on-send feature, can't be published to AppSource. You'll still be able to sideload and run your add-in, provided that no other validation errors are found.
 
-- **Manifest** – Only one `ItemSend` event is supported per add-in. If you have two or more `ItemSend` events in a manifest, the manifest will fail validation.
+- **Manifest** – The on-send feature is only supported in add-ins that use the [add-in only manifest](../develop/add-in-manifests.md). It isn't supported in add-ins that use the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md). In the add-in only manifest, only one `ItemSend` event is supported per add-in. If you have two or more `ItemSend` events in a manifest, the manifest will fail validation.
 - **Performance** – Multiple roundtrips to the web server that hosts the add-in can affect the performance of the add-in. Consider the effects on performance when you create add-ins that require multiple message- or meeting-based operations.
 - **Send Later** (Mac only) – If there are on-send add-ins, the **Send Later** feature will be unavailable.
 

docs/outlook/outlook-on-send-addins.md

@@ -4,7 +4,7 @@ description: Turn legacy Exchange Online tokens on or off
 ms.service: microsoft-365
 ms.subservice: add-ins
 ms.topic: how-to
-ms.date: 05/19/2025
+ms.date: 05/22/2025
 ---
 
 # Turn legacy Exchange Online tokens on or off
@@ -64,9 +64,26 @@ Blocked: []
 PS C:\>
 ```
 
-The **Allowed** and **Blocked** sections list the IDs of any add-ins that made recent requests. If an add-in ID is listed in the **Allowed** list, it was granted an Exchange token. If an add-in ID is listed in the **Blocked** list, it was denied an access token because access tokens are turned off.
+The **Allowed** and **Blocked** sections list the IDs of any add-ins that made recent requests. If an add-in ID is listed in the **Allowed** list, it was granted an Exchange token. If an add-in ID is listed in the **Blocked** list, it was denied an access token because access tokens are turned off. The following example shows the Script Lab ID being granted a token on May 16, and also blocked from a token on February 25th. Tokens were turned off for the tenant in February, and turned on in May, so Script Lab appears in both sections.
 
-If you have IDs listed in **Allowed** or **Blocked** do additional research to identify the publisher and reach out to them to ensure they are migrating their add-in away from legacy Exchange Online tokens. For more information on identifying publishers, see [Commands to identify the publisher in the FAQ](faq-nested-app-auth-outlook-legacy-tokens.md#what-commands-can-i-use-to-identify-the-publisher).
+```console
+PS C:\> Get-AuthenticationPolicy -AllowLegacyExchangeTokens
+AllowLegacyExchangeTokens: True
+Allowed:
+[
+        { "49d3b812-abda-45b9-b478-9bc464ce5b9c" : "2025-05-16" }
+]
+Blocked:
+[
+        { "49d3b812-abda-45b9-b478-9bc464ce5b9c" : "2025-02-25" }
+]
+```
+
+The report only shows a single entry per add-in. If multiple calls from many users are made from a single add-in for Exchange tokens, those calls appear in the report as one request. The date updates every seven days. In the previous example, the report shows Script lab being granted tokens on May 16. The date won't change unless Script Lab continues to make token requests on May 23rd at which point the report will update the date.
+
+To confirm an add-in is no longer requesting Exchange tokens, run the command after seven days and check that the date doesn't change.
+
+If you have IDs listed in **Allowed** or **Blocked** that are requesting legacy tokens, identify the publisher and reach out to them to ensure they are migrating their add-in away from legacy tokens. For more information on identifying publishers, see [Commands to identify the publisher in the FAQ](faq-nested-app-auth-outlook-legacy-tokens.md#what-commands-can-i-use-to-identify-the-publisher).
 
 > [!NOTE]
 > The `Get-AuthenticationPolicy -AllowLegacyExchangeTokens` command is the only way to view legacy token status. Other commands, such as `Get-AuthenticationPolicy | Format-Table -Auto Name`, don't return the legacy token status.