Bewerken

Delen via

Automatically open a task pane when an add-in is installed

  • Artikel

You can configure your add-in's task pane to launch immediately after it's installed. This feature increases usage.

By default, task pane add-ins that do not include any add-in commands open the task pane immediately upon installation. However, when an add-in has one or more add-in commands, then the user is notified of new add-in, but the add-in doesn't launch automatically. This historic default behavior is changing so add-ins that do have add-in commands will launch automatically in some situations. In addition, if the add-in has more than one task pane page, it's possible for you to control whether the add-in launches upon installation and, if so, which page opens in the task pane.

Note

  • This feature applies only to add-ins installed by an end-user, not to centrally deployed add-ins.
  • This feature doesn't apply to Content add-ins or Mail (Outlook) add-ins.
  • This feature applies only to add-ins that have at least one add-in command of the type "task pane command".

New behavior

The new behavior is as follows:

  • If the add-in has just one task pane command, then the add-in's ribbon tab is selected and the task pane opens automatically upon installation. You don't need to configure anything.
  • If the add-in has multiple task pane commands, and one is configured to be the default (see Configure default task pane), then the add-in's ribbon tab is selected and the default task pane opens automatically upon installation.
  • If the add-in has multiple task pane commands, but none is configured to be the default, then the add-in's ribbon tab is selected automatically upon installation and a callout appears near it notifying the user of the new add-in, but no task pane is opened. This is the same as the historic default behavior.

Note

If for any reason, the add-in command that launches the task pane cannot be manually selected by a user at start up, such as when it's configured to be disabled at start up, then it won't be automatically opened regardless of configuration.

Configure default task pane in the manifest

The process for specifying the default task pane depends on the type of manifest the add-in uses.

Note

The unified manifest for Microsoft 365 can be used in production Outlook add-ins. It's available only as a preview for Excel, PowerPoint, and Word add-ins.

To specify the default task pane, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to be the default. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must be an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized as the default and the others will be ignored.

The following example shows a "view" value set to "Office.AutoShowTaskpaneWithDocument".

"runtimes": [
    {
        ...
        "code": {
            "page": "https://contoso.com/taskpane.html"
        },
        "actions": [
            {
                "id": "ShowTaskPane",
                "type": "openPage",
                "view": "Office.AutoShowTaskpaneWithDocument"
            }
        ]
    }
]

Tip

If you want your add-in to automatically launch whenever the user reopens the document, you need to take further configuration steps. For details and advice about when to use this feature, see Automatically open a task pane with a document.

See also