[Excel] (Custom functions) Add new cache clear guidance (#5152)

* [Excel] (Custom functions) Add new cache clear guidance

* Fix typo

* Update docs/excel/custom-functions-troubleshooting.md

Co-authored-by: Copilot <[email protected]>

* Incorporate code review feedback, add TIP from PM

* Add notes for how to disable and how to call in office.onready

* Adjust comment spacing and date

* Add shared runtime requirement

---------

Co-authored-by: Copilot <[email protected]>

Author: alison-mk

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