ExtensionPoint element

Article
01/19/2024

Defines where an add-in exposes functionality in the Office UI. The <ExtensionPoint> element is a child element of AllFormFactors, DesktopFormFactor or MobileFormFactor.

Add-in type: Task pane, Mail

Valid only in these VersionOverrides schemas:

Task pane 1.0
Mail 1.0
Mail 1.1

For more information, see Version overrides in the manifest.

Attributes

Attribute	Required	Description
xsi:type	Yes	The type of extension point being defined. Possible values depend on the Office host application defined in the grandparent <Host> element value.

Extension points for Excel, OneNote, PowerPoint, and Word add-in commands

There are three types of extension points available in some or all of these hosts.

PrimaryCommandSurface (Valid for Word, Excel, PowerPoint, and OneNote) - The ribbon in Office.
ContextMenu (Valid for Word, Excel, PowerPoint, and OneNote) - The shortcut menu that appears when you select and hold (or right-click) in the Office UI.
CustomFunctions (Valid only for Excel) - A custom function written in JavaScript for Excel.

See the following subsections for the child elements and examples of these types of extension points.

PrimaryCommandSurface

The primary command surface in Word, Excel, PowerPoint, and OneNote is the ribbon.

Child elements

Element	Description
CustomTab	Required if you want to add a custom tab to the ribbon (using PrimaryCommandSurface). If you use the <CustomTab> element, you can't use the <OfficeTab> element. The id attribute is required. There can be no more than one <CustomTab> child element.
OfficeTab	Required if you want to extend a default Office app ribbon tab (using PrimaryCommandSurface). If you use the <OfficeTab> element, you can't use the <CustomTab> element.

Important

There can be no more than one <ExtensionPoint> element in the add-in that has a child <CustomTab> element; and that one <ExtensionPoint> element can have only one <CustomTab>, so there is only one <CustomTab> element across all <ExtensionPoint> elements.

Example

The following example shows how to use the <ExtensionPoint> element with PrimaryCommandSurface. It adds a custom tab to the ribbon.

Important

For elements that contain an ID attribute, make sure you provide a unique ID.

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso.MyTab1">
    <Label resid="residLabel4" />
    <Group id="Contoso.Group1">
      <Label resid="residLabel4" />
      <Icon>
        <bt:Image size="16" resid="icon1_32x32" />
        <bt:Image size="32" resid="icon1_32x32" />
        <bt:Image size="80" resid="icon1_32x32" />
      </Icon>
      <Tooltip resid="residToolTip" />
      <Control xsi:type="Button" id="Contoso.Button1">
          <!-- information about the control -->
      </Control>
      <!-- other controls, as needed -->
    </Group>
  </CustomTab>
</ExtensionPoint>

ContextMenu

A context menu is a shortcut menu that appears when you right-click in the Office UI.

Child elements

Element	Description
OfficeMenu	Required if you're adding add-in commands to a default context menu (using ContextMenu). The id attribute must be set to one of the following strings: ContextMenuText if the context menu should open when a user right-clicks on the selected text. ContextMenuCell if the context menu should open when the user right-clicks on a cell on an Excel spreadsheet.

Example

The following adds a custom context menu to the cells in an Excel spreadsheet.

<ExtensionPoint xsi:type="ContextMenu">
  <OfficeMenu id="ContextMenuCell">
    <Control xsi:type="Menu" id="Contoso.ContextMenu2">
            <!-- information about the control -->
    </Control>
    <!-- other controls, as needed -->
  </OfficeMenu>
</ExtensionPoint>

CustomFunctions

A custom function written in JavaScript or TypeScript for Excel.

Child elements

Element	Description
Script	Required. Links to the JavaScript file with the custom function's definition and registration code.
Page	Required. Links to the HTML page for your custom functions.
MetaData	Required. Defines the metadata settings used by a custom function in Excel.
Namespace	Optional. Defines the namespace used by a custom function in Excel.

Example

<ExtensionPoint xsi:type="CustomFunctions">
  <Script>
    <SourceLocation resid="Functions.Script.Url"/>
  </Script>
  <Page>
    <SourceLocation resid="Shared.Url"/>
  </Page>
  <Metadata>
    <SourceLocation resid="Functions.Metadata.Url"/>
  </Metadata>
  <Namespace resid="Functions.Namespace"/>
</ExtensionPoint>

Extension points for Outlook

MessageReadCommandSurface
MessageComposeCommandSurface
AppointmentOrganizerCommandSurface
AppointmentAttendeeCommandSurface
Module (can only be used in the DesktopFormFactor)
MobileMessageReadCommandSurface
MobileOnlineMeetingCommandSurface
MobileLogEventAppointmentAttendee
LaunchEvent
Events
DetectedEntity
ReportPhishingCommandSurface (preview)

MessageReadCommandSurface

This extension point puts buttons in the command surface for the mail read view. In Outlook desktop, this appears in the ribbon.

Child elements

Element	Description
OfficeTab	Adds the command(s) to the default ribbon tab.
CustomTab	Adds the command(s) to the custom ribbon tab.

OfficeTab example

<ExtensionPoint xsi:type="MessageReadCommandSurface">
  <OfficeTab id="TabDefault">
        <-- OfficeTab Definition -->
  </OfficeTab>
</ExtensionPoint>

CustomTab example

<ExtensionPoint xsi:type="MessageReadCommandSurface">
  <CustomTab id="Contoso.TabCustom2">
        <-- CustomTab Definition -->
  </CustomTab>
</ExtensionPoint>

MessageComposeCommandSurface

This extension point puts buttons on the ribbon for add-ins using mail compose form.

Child elements

Element	Description
OfficeTab	Adds the command(s) to the default ribbon tab.
CustomTab	Adds the command(s) to the custom ribbon tab.

OfficeTab example

<ExtensionPoint xsi:type="MessageComposeCommandSurface">
  <OfficeTab id="TabDefault">
        <-- OfficeTab Definition -->
  </OfficeTab>
</ExtensionPoint>

CustomTab example

<ExtensionPoint xsi:type="MessageComposeCommandSurface">
  <CustomTab id="Contoso.TabCustom3">
        <-- CustomTab Definition -->
  </CustomTab>
</ExtensionPoint>

AppointmentOrganizerCommandSurface

This extension point puts buttons on the ribbon for the form that's displayed to the organizer of the meeting.

Child elements

Element	Description
OfficeTab	Adds the command(s) to the default ribbon tab.
CustomTab	Adds the command(s) to the custom ribbon tab.

OfficeTab example

<ExtensionPoint xsi:type="AppointmentOrganizerCommandSurface">
  <OfficeTab id="TabDefault">
        <-- OfficeTab Definition -->
  </OfficeTab>
</ExtensionPoint>

CustomTab example

<ExtensionPoint xsi:type="AppointmentOrganizerCommandSurface">
  <CustomTab id="Contoso.TabCustom4">
        <-- CustomTab Definition -->
  </CustomTab>
</ExtensionPoint>

AppointmentAttendeeCommandSurface

This extension point puts buttons on the ribbon for the form that's displayed to the attendee of the meeting.

Child elements

Element	Description
OfficeTab	Adds the command(s) to the default ribbon tab.
CustomTab	Adds the command(s) to the custom ribbon tab.

OfficeTab example

<ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">
  <OfficeTab id="TabDefault">
        <-- OfficeTab Definition -->
  </OfficeTab>
</ExtensionPoint>

CustomTab example

<ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">
  <CustomTab id="Contoso.TabCustom5">
        <-- CustomTab Definition -->
  </CustomTab>
</ExtensionPoint>

Module

This extension point puts buttons on the ribbon for the module extension.

Important

Registering Mailbox and Item events is not available with this extension point.

Child elements

Element	Description
OfficeTab	Adds the command(s) to the default ribbon tab.
CustomTab	Adds the command(s) to the custom ribbon tab.

MobileMessageReadCommandSurface

This extension point puts buttons in the command surface for the mail read view in the mobile form factor.

Child elements

Element	Description
Group	Adds a group of buttons to the command surface.

<ExtensionPoint> elements of this type can only have one child element: a <Group> element.

<Control> elements contained in this extension point must have the xsi:type attribute set to MobileButton.

Example

<ExtensionPoint xsi:type="MobileMessageReadCommandSurface">
  <Group id="Contoso.mobileGroup1">
    <Label resid="residAppName"/>
    <Control xsi:type="MobileButton" id="Contoso.mobileButton1">
      <!-- Control definition -->
    </Control>
  </Group>
</ExtensionPoint>

MobileOnlineMeetingCommandSurface

This extension point puts a mode-appropriate toggle in the command surface for an appointment in the mobile form factor. A meeting organizer can create an online meeting. An attendee can subsequently join the online meeting. To learn more about this scenario, see Create an Outlook mobile add-in for an online-meeting provider.

Note

This extension point is only supported on Android and iOS with a Microsoft 365 subscription.

Registering Mailbox and Item events is not available with this extension point.

Child elements

Element	Description
Control	Adds a button to the command surface.

<ExtensionPoint> elements of this type can only have one child element: a <Control> element.

The <Control> element contained in this extension point must have the xsi:type attribute set to MobileButton.

The images specified in the <Icon> element should be in grayscale using hex code #919191 or its equivalent in other color formats.

Example

<ExtensionPoint xsi:type="MobileOnlineMeetingCommandSurface">
  <Control xsi:type="MobileButton" id="Contoso.onlineMeetingFunctionButton1">
    <Label resid="residUILessButton0Name" />
    <Icon>
      <bt:Image resid="UiLessIcon" size="25" scale="1" />
      <bt:Image resid="UiLessIcon" size="25" scale="2" />
      <bt:Image resid="UiLessIcon" size="25" scale="3" />
      <bt:Image resid="UiLessIcon" size="32" scale="1" />
      <bt:Image resid="UiLessIcon" size="32" scale="2" />
      <bt:Image resid="UiLessIcon" size="32" scale="3" />
      <bt:Image resid="UiLessIcon" size="48" scale="1" />
      <bt:Image resid="UiLessIcon" size="48" scale="2" />
      <bt:Image resid="UiLessIcon" size="48" scale="3" />
    </Icon>
    <Action xsi:type="ExecuteFunction">
      <FunctionName>insertContosoMeeting</FunctionName>
    </Action>
  </Control>
</ExtensionPoint>

MobileLogEventAppointmentAttendee

This extension point puts a Log action button contextually in the command surface for an appointment in the mobile form factor. Appointment attendees who have the add-in installed can save their appointment notes to an external app in one click. This extension point supports functionality for task pane and function commands. To learn more about this scenario, see Log appointment notes to an external application in Outlook mobile add-ins.

Note

This extension point is only supported on Android and iOS with a Microsoft 365 subscription.

Registering Mailbox and Item events is not available with this extension point.

Child elements

Element	Description
Control	Adds a button to the command surface.

<ExtensionPoint> elements of this type can only have one child element: a <Control> element.

The <Control> element contained in this extension point must have the xsi:type attribute set to MobileButton.

The images specified in the <Icon> element should be in grayscale using hex code #919191 or its equivalent in other color formats.

Example

<ExtensionPoint xsi:type="MobileLogEventAppointmentAttendee">
  <Control xsi:type="MobileButton" id="appointmentReadFunctionButton">
    <Label resid="LogButtonLabel" />
    <Icon>
      <bt:Image resid="Icon.16x16" size="25" scale="1" />
      <bt:Image resid="Icon.16x16" size="25" scale="2" />
      <bt:Image resid="Icon.16x16" size="25" scale="3" />
      <bt:Image resid="Icon.32x32" size="32" scale="1" />
      <bt:Image resid="Icon.32x32" size="32" scale="2" />
      <bt:Image resid="Icon.32x32" size="32" scale="3" />
      <bt:Image resid="Icon.80x80" size="48" scale="1" />
      <bt:Image resid="Icon.80x80" size="48" scale="2" />
      <bt:Image resid="Icon.80x80" size="48" scale="3" />
    </Icon>
    <Action xsi:type="ExecuteFunction">
      <FunctionName>logToCRM</FunctionName>
    </Action>
  </Control>
</ExtensionPoint>

LaunchEvent

This extension point enables an add-in to activate based on supported events in both the desktop and mobile form factors. To learn more about event-based activation and for the full list of supported events, see Configure your Outlook add-in for event-based activation.

Important

Registering Mailbox and Item events is not available with this extension point.

Child elements

Element	Description
LaunchEvents	List of LaunchEvent for event-based activation.
SourceLocation	The location of the source JavaScript file.

Example

<ExtensionPoint xsi:type="LaunchEvent">
  <LaunchEvents>
    <LaunchEvent Type="OnNewMessageCompose" FunctionName="onMessageComposeHandler"/>
    <LaunchEvent Type="OnNewAppointmentOrganizer" FunctionName="onAppointmentComposeHandler"/>
  </LaunchEvents>
  <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
  <SourceLocation resid="WebViewRuntime.Url"/>
</ExtensionPoint>

Events

This extension point adds an event handler for a specified event. For more information about using this extension point, see On-send feature for Outlook add-ins.

Important

Registering Mailbox and Item events is not available with this extension point.

Note

Smart Alerts, which is a newer version of the on-send feature, uses the LaunchEvent extension point to enable event activation in an add-in. To learn more about the key differences between Smart Alerts and the on-send feature, see Differences between Smart Alerts and the on-send feature. We invite you to try out Smart Alerts by completing the walkthrough.

Element	Description
Event	Specifies the event and event handler function.

ItemSend event example

<ExtensionPoint xsi:type="Events">
  <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="itemSendHandler" />
</ExtensionPoint>

DetectedEntity

This extension point adds a contextual add-in activation on a specified entity type. For more information about using this extension point, see Contextual Outlook add-ins.

Important

Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this feature will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. The following APIs will also be retired.

To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins are retired.

An alternative implementation of the Join Meeting button, which is activated by online meeting add-ins, is being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically transition to the alternative implementation to activate the Join Meeting button.
Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Use regular expression activation rules to show an Outlook add-in.

For more information, see Retirement of entity-based contextual Outlook add-ins.

The containing VersionOverrides element must have an xsi:type attribute value of VersionOverridesV1_1.

Note

This element type is available to Outlook clients that support requirement sets 1.6 and later.
Registering Mailbox and Item events is not available with this extension point.

Element	Description
Label	Specifies the label for the add-in in the contextual window.
SourceLocation	Specifies the URL for the contextual window.
Rule	Specifies the rule or rules that determine when an add-in activates.

Label

Required. The label of the group. The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a <String> element in the <ShortStrings> element in the Resources element.

Highlight requirements

The only way a user can activate a contextual add-in is to interact with a highlighted entity. Developers can control which entities are highlighted by using the Highlight attribute of the <Rule> element for ItemHasKnownEntity and ItemHasRegularExpressionMatch rule types.

However, there are some limitations to be aware of. These limitations are in place to ensure that there will always be a highlighted entity in applicable messages or appointments to give the user a way to activate the add-in.

The EmailAddress and Url entity types cannot be highlighted, and therefore cannot be used to activate an add-in.
If using a single rule, the Highlight attribute MUST be set to all.
If using a RuleCollection rule type with Mode="AND" to combine multiple rules, at least one of the rules MUST have the Highlight attribute set to all.
If using a RuleCollection rule type with Mode="OR" to combine multiple rules, all of the rules MUST have the Highlight attribute set to all.

DetectedEntity event example

<ExtensionPoint xsi:type="DetectedEntity">
  <Label resid="residLabelName"/>
  <!--If you opt to include RequestedHeight, it must be between 140px to 450px, inclusive.-->
  <!--<RequestedHeight>360</RequestedHeight>-->
  <SourceLocation resid="residDetectedEntityURL" />
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="MeetingSuggestion" Highlight="all" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" Highlight="none" />
  </Rule>
</ExtensionPoint>

ReportPhishingCommandSurface (preview)

This extension point activates your spam-reporting add-in in the Outlook ribbon and prevents it from appearing at the end of the ribbon or in the overflow menu.

To learn more about how to implement the spam reporting feature in your add-in, see Implement an integrated spam-reporting add-in (preview).

Child elements

Element	Description
ReportPhishingCustomization element (preview)	Configures the ribbon button and preprocessing dialog of a spam-reporting add-in.

Example

<ExtensionPoint xsi:type="ReportPhishingCommandSurface">
  <ReportPhishingCustomization>
    <!-- Configures the ribbon button. -->
    <Control xsi:type="Button" id="ReportingButton">
      <Label resid="ReportingButton.Label"/>
      <Supertip>
        <Title resid="ReportingButton.Label"/>
        <Description resid="ReportingButton.Description"/>
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="Icon.16x16"/>
        <bt:Image size="32" resid="Icon.32x32"/>
        <bt:Image size="64" resid="Icon.64x64"/>
        <bt:Image size="80" resid="Icon.80x80"/>
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>onMessageReport</FunctionName>
      </Action>
    </Control>
    <!-- Configures the preprocessing dialog. -->
    <PreProcessingDialog>
      <Title resid="PreProcessingDialog.Label"/>
      <Description resid="PreProcessingDialog.Description"/>
      <ReportingOptions>
        <Title resid="OptionsTitle.Label"/>
        <Option resid="Option1.Label"/>
        <Option resid="Option2.Label"/>
        <Option resid="Option3.Label"/>
        <Option resid="Option4.Label"/>
      </ReportingOptions>
      <FreeTextLabel resid="FreeText.Label"/>
      <MoreInfo>
        <MoreInfoText resid="MoreInfo.Label"/>
        <MoreInfoUrl resid="MoreInfo.Url"/>
      </MoreInfo>
    </PreProcessingDialog>
    <SourceLocation resid="Commands.Url"/>
  </ReportPhishingCustomization>
</ExtensionPoint>

ExtensionPoint element

Attributes

Extension points for Excel, OneNote, PowerPoint, and Word add-in commands

PrimaryCommandSurface

Child elements

Example

ContextMenu

Child elements

Example

CustomFunctions

Child elements

Example

Extension points for Outlook

MessageReadCommandSurface

Child elements

OfficeTab example

CustomTab example

MessageComposeCommandSurface

Child elements

OfficeTab example

CustomTab example

AppointmentOrganizerCommandSurface

Child elements

OfficeTab example

CustomTab example

AppointmentAttendeeCommandSurface

Child elements

OfficeTab example

CustomTab example

Module

Child elements

MobileMessageReadCommandSurface

Child elements

Example

MobileOnlineMeetingCommandSurface

Child elements

Example

MobileLogEventAppointmentAttendee

Child elements

Example

LaunchEvent

Child elements

Example

Events

ItemSend event example

DetectedEntity

Label

Highlight requirements

DetectedEntity event example

ReportPhishingCommandSurface (preview)

Child elements

Example

Feedback

Additional resources