Redigera

Dela via

JavaScript-only runtime for custom functions

Custom functions that don't use a shared runtime rely on a JavaScript-only runtime. This runtime is optimized for fast calculation but has fewer APIs available.

Important

Note that Excel custom functions are available on the following platforms.

  • Office on the web
  • Office on Windows
    • Microsoft 365 subscription
    • retail perpetual Office 2016 and later
    • volume-licensed perpetual/LTSC Office 2021 and later
  • Office on Mac

Excel custom functions aren't currently supported in the following:

  • Office on iPad
  • volume-licensed perpetual versions of Office 2021 or earlier on Windows

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.

Note

We recommend using custom functions with a shared runtime, unless you have a specific reason not to use a shared runtime. For more information about runtimes, see Runtimes in Office Add-ins.

This JavaScript-only runtime provides access to APIs in the OfficeRuntime namespace that can be used by custom functions and the task pane (which runs in a different runtime) to store data.

Request external data

Within a custom function, you can request external data by using an API like Fetch or by using XmlHttpRequest (XHR), a standard web API that issues HTTP requests to interact with servers.

Be aware that custom functions must use additional security measures when making XmlHttpRequests, requiring Same Origin Policy and simple CORS.

A simple CORS implementation cannot use cookies and only supports simple methods (GET, HEAD, POST). Simple CORS accepts simple headers with field names Accept, Accept-Language, Content-Language. You can also use a Content-Type header in simple CORS, provided that the content type is application/x-www-form-urlencoded, text/plain, or multipart/form-data.

Store and access data

Within a custom function that doesn't use a shared runtime, you can store and access data by using the OfficeRuntime.storage object. The Storage object is a persistent, unencrypted, key-value storage system that provides an alternative to localStorage, which cannot be used by custom functions that use the JavaScript-only runtime. The Storage object offers 10 MB of data per domain. Domains can be shared by more than one add-in.

The Storage object is a shared storage solution, meaning multiple parts of an add-in are able to access the same data. For example, tokens for user authentication may be stored in the Storage object because it can be accessed by both a custom function (using the JavaScript-only runtime) and a task pane (using a full webview runtime). Similarly, if two add-ins share the same domain (for example, www.contoso.com/addin1, www.contoso.com/addin2), they are also permitted to share information back and forth through the Storage object. Note that add-ins which have different subdomains will have different instances of Storage (for example, subdomain.contoso.com/addin1, differentsubdomain.contoso.com/addin2).

Because the Storage object can be a shared location, it is important to realize that it is possible to override key-value pairs.

The following methods are available on the Storage object.

  • getItem
  • getItems
  • setItem
  • setItems
  • removeItem
  • removeItems
  • getKeys

Note

There's no method for clearing all information (such as clear). Instead, you should instead use removeItems to remove multiple entries at a time.

OfficeRuntime.storage example

The following code sample calls the OfficeRuntime.storage.setItem method to set a key and value into storage.

function StoreValue(key, value) {

  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
      return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
      return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

Compare with shared runtime

Need UI integration or Office.js objects and events? Move those functions to a shared runtime.

Next steps

Learn how to debug custom functions.

See also

  • Last updated on