FormSettings DesktopSettings deprecation in Office Add-ins for Outlook No ratings yet.

Background information

Office Add-ins for Outlook can be displayed in two modes:

  • On the grey bar under the subject field, and in the form of a pane inside the message when expanded
  • Within a task pane on the right of the Outlook item currently displayed

The “Grey Bar” display is being deprecated and moving forward, we recommend only displaying add-ins in the add-in task pane as indicated above.

With the introduction of the new version of Outlook Web App (AKA React OWA), Office Add-ins for Outlook might not display if the manifest declares FormSettings / DesktopSettings.

React OWA

React OWA can be toggled on by selecting Try the new Outlook on the top of the page as illustrated below:

Try the new Outlook toggle

In the legacy Outlook Web App, the add-ins “Grey Bar” is located below the subject line. This is used for add-ins whose manifest declares FormSettings / DesktopSettings.

The screenshot below illustrates an add-in called OurOffice365App, rendered on the grey bar.

“Grey Bar” add-ins

FormSettings / DesktopSettings

We do not recommend using the FormSettings/DesktopSettings in the legacy section of the manifest to show the “gray bar” entry point of add-ins. Such add-ins won’t be supported moving forward.

Add-ins that declare FormSettings / DesktopSettings are not available in the new (React) OWA and will eventually be deprecated in other clients.

Our recommendation is moving to Contextual Add-ins or Add-in commands for an optimal experience.

IMPORTANT: Please note add-ins declaring the FormSettings / DesktopSettings element will fail the Office Store validation.

However, Grey-bar Add-ins can be used as fallback mechanism to support older client if required.

Moving to a supported model – VersionOverrrides

The below example shows the deprecated FormSettings / DesktopSettings element.

<?xml version="1.0"?>
  <Form xsi:type="ItemRead">
      <SourceLocation DefaultValue="https://localhost:3000/index.html"/>

The FormSettings / DesktopSettings section should instead be replaced by an ExtensionPoint declaration, under VersionOverrides as illustrated below.

<?xml version="1.0"?>
<VersionOverrides xmlns="" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="" xsi:type="VersionOverridesV1_1">
      <bt:Sets DefaultMinVersion="1.3">
        <bt:Set Name="Mailbox"/>
      <Host xsi:type="MailHost">
          <FunctionFile resid="functionFile"/>
          <!-- Message Read -->
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <!-- Use the default tab of the ExtensionPoint or create your own with <CustomTab id="myTab"> -->
            <OfficeTab id="TabDefault">
              <!-- Up to 6 Groups added per Tab -->
              <Group id="msgReadGroup">
                <Label resid="groupLabel"/>
                <!-- Launch the add-in : task pane button -->
                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                  <Label resid="paneReadButtonLabel"/>
                    <Title resid="paneReadSuperTipTitle"/>
                    <Description resid="paneReadSuperTipDescription"/>
                    <bt:Image size="16" resid="icon16"/>
                    <bt:Image size="32" resid="icon32"/>
                    <bt:Image size="80" resid="icon80"/>
                  <Action xsi:type="ShowTaskpane">
                    <SourceLocation resid="messageReadTaskPaneUrl"/>
                <!-- Go to to learn how to add more Controls: ExecuteFunction and Menu -->

Backing information

This information was first made available on the Outlook: Developer Blog under Requirement: New Office store policies and deprecated features:

More information

For more information on the VersionOverrides element of the Office Add-in manifest please visit


Type Date Author / Editor Notes
Original 3rd Sept 2019 Rui Silva  

Please rate this


Leave a Reply

Your email address will not be published. Required fields are marked *