Share via

extensionRuntimesArray object

  • Article

The extensions.runtimes array configures the sets of runtimes and actions that an Office add-in or Copilot agent can use. For information about runtimes in Office Add-ins, see Runtimes in Office Add-ins.

Properties that reference this object type:

Syntax

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "id": "{string}",
  "type": "general",
  "code": {
    "page": "{string}",
    "script": "{string}"
  },
  "lifetime": "short | long",
  "actions": [
    {
      "id": "{string}",
      "type": "executeFunction | openPage | executeDataFunction",
      "displayName": "{string}",
      "pinnable": {boolean},
      "view": "{string}",
      "multiselect": {boolean},
      "supportsNoItemContext": {boolean}
    }
  ],
  "customFunctions": {
    "functions": [
      {
        extensionFunction object
      }
    ],
    "namespace": {
      extensionCustomFunctionsNamespace object
    },
    "allowCustomDataForDataTypeAny": {boolean}
  }
}

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "id": "{string}",
  "type": "general",
  "code": {
    "page": "{string}",
    "script": "{string}"
  },
  "lifetime": "short | long",
  "actions": [
    {
      "id": "{string}",
      "type": "executeFunction | openPage",
      "displayName": "{string}",
      "pinnable": {boolean},
      "view": "{string}",
      "multiselect": {boolean},
      "supportsNoItemContext": {boolean}
    }
  ]
}

Properties

requirements

Specifies the scopes, formFactors, and Office JavaScript library requirement sets that must be supported on the Office client in order for the runtime to be included in the add-in. For more information, see Specify Office Add-in requirements in the unified manifest for Microsoft 365.

Type
requirementsExtensionElement

Required
—

Constraints

Supported values

id

Specifies the ID for runtime.

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

type

Specifies the type of runtime. The supported enum value for browser-based runtime is general.

Type
string

Required
—

Constraints

Supported values
Allowed values: general.

code

Specifies the location of code for the runtime. Based on runtime.type, add-ins can use either a JavaScript file or an HTML page with an embedded script tag that specifies the URL of a JavaScript file. Both URLs are necessary in situations where the runtime.type is uncertain.

Type
extensionRuntimeCode

Required
✅

Constraints

Supported values

lifetime

Specifies the lifetime of the runtime. The possible values are the following:

short (default): Doesn't preserve state across executions. It enables an Outlook add-in to process unsolicited messages.

long : Preserves the state across executions, allowing the add-in to run indefinitely. For example, task pane code will continue running even when the user closes the task pane. It can also be shared across different features of your add-in. See Configure your Office Add-in to use a shared JavaScript runtime for details.

Type
string

Required
—

Constraints

Supported values
Allowed values: short, long.

actions

Specifies the set of actions supported by the runtime. An action is either running a JavaScript function or opening a view such as a task pane.

Type
Array of extensionRuntimesActionsItem

Required
—

Constraints
Minimum array items: 1. Maximum array items: 20.

Supported values

customFunctions

Type
extensionCustomFunctions

Required
—

Constraints

Supported values

Remarks

To use extensions.runtimes, see create add-in commands, configure the runtime for a task pane, and configure the runtime for the function command.

Examples

{
    "extensions": [
        {
          "runtimes": [
            {
              "requirements": {
                "capabilities": [
                  {
                    "name": "MailBox",
                    "minVersion": "1.10"
                  }
                ]
              },
              "id": "eventsRuntime",
              "type": "general",
              "code": {
                "page": "https://contoso.com/events.html",
                "script": "https://contoso.com/events.js"
              },
              "lifetime": "short",
              "actions": [
                {
                  "id": "onMessageSending",
                  "type": "executeFunction"
                },
                {
                  "id": "onNewMessageComposeCreated",
                  "type": "executeFunction"
                }
              ]
            },
            {
              "requirements": {
                "capabilities": [
                  {
                    "name": "MailBox", "minVersion": "1.1"
                  }
                ]
              },
              "id": "commandsRuntime",
              "type": "general",
              "code": {
                "page": "https://contoso.com/commands.html",
                "script": "https://contoso.com/commands.js"
              },
              "lifetime": "short",
              "actions": [
                {
                  "id": "action1",
                  "type": "executeFunction"
                },
                {
                  "id": "action2",
                  "type": "executeFunction"
                },
                {
                  "id": "action3",
                  "type": "executeFunction"
                }
              ]
            }
          ],
        }
    ]
}

See also