Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Defines where an add-in exposes functionality in the Office UI. The
Add-in type: Document, Mail, Presentation, Task pane, Workbook
Valid only in these VersionOverrides schemas:
- Task pane 1.0
- Mail 1.0
- Mail 1.1
For more information, see Version overrides in the add-in only 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 |
Extension points for Excel, Outlook, PowerPoint, and Word
- LaunchEvent - Activates tasks based on application events, such as opening.
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 Activate add-ins with events.
Important
Registering Mailbox and Item events isn't 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. Important: The resid value of the resid value of the |
Example
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 right-click (or select and hold) 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 |
| OfficeTab | Required if you want to extend a default Office app ribbon tab (using PrimaryCommandSurface). If you use the |
Important
There can be no more than one
Example
The following example shows how to use the
Important
For elements that contain an ID attribute, make sure you provide a unique ID.
ContextMenu
A context menu is a shortcut menu that appears when you right-click (or select and hold) 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.
|
Example
The following customizes the context menu opened on the selected text in a supported Office application. The context menu control used is of type Button.
action
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
Extension points for Outlook
- MessageReadCommandSurface
- MessageComposeCommandSurface
- AppointmentOrganizerCommandSurface
- AppointmentAttendeeCommandSurface
- Module (can only be used in the DesktopFormFactor)
- MobileMessageReadCommandSurface
- MobileOnlineMeetingCommandSurface
- MobileLogEventAppointmentAttendee
- Events
- DetectedEntity
- ReportPhishingCommandSurface
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
<-- OfficeTab Definition -->
CustomTab example
<-- CustomTab Definition -->
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
<-- OfficeTab Definition -->
CustomTab example
<-- CustomTab Definition -->
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
<-- OfficeTab Definition -->
CustomTab example
<-- CustomTab Definition -->
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
<-- OfficeTab Definition -->
CustomTab example
<-- CustomTab Definition -->
Module
This extension point adds a module extension add-in to the Outlook navigation bar. It also adds buttons to a custom tab on the ribbon for the module extension. To learn how to create module extensions, see Module extension Outlook add-ins.
Important
Registering Mailbox and Item events isn't available with this extension point.
Child elements
| Element | Description |
|---|---|
| SourceLocation | Specifies the location of the HTML file that sets up the main user interface of the add-in. |
| Label | Specifies the label of the module extension. Its resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a |
| CommandSurface | Adds a group of add-in buttons to a custom tab on the ribbon. |
Example
changeToAssociateRate
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. |
MobileButton.
Example
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 isn't available with this extension point.
Child elements
| Element | Description |
|---|---|
| Control | Adds a button to the command surface. |
The MobileButton.
The images specified in the #919191 or its equivalent in other color formats.
Example
insertContosoMeeting
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 isn't available with this extension point.
Child elements
| Element | Description |
|---|---|
| Control | Adds a button to the command surface. |
The MobileButton.
The images specified in the #919191 or its equivalent in other color formats.
Example
logToCRM
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 isn't 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
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 are now retired. As an alternative solution, implement regular expression rules in your contextual add-in. For guidance on how to implement these rules, see 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
MailboxandItemevents isn't 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
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 ItemHasRegularExpressionMatch rule type.
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.
- If using a single rule, the Highlight attribute MUST be set to
all. - If using a
RuleCollectionrule type withMode="And"to combine multiple rules, at least one of the rules MUST have the Highlight attribute set toall. - If using a
RuleCollectionrule type withMode="Or"to combine multiple rules, all of the rules MUST have the Highlight attribute set toall.
DetectedEntity event example
ReportPhishingCommandSurface
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.
Child elements
| Element | Description |
|---|---|
| ReportPhishingCustomization element | Configures the ribbon button and preprocessing dialog of a spam-reporting add-in. |
Example
onMessageReport
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins