Implementing the IRibbonExtensibility Interface

An Outlook add-in that customizes the Ribbon must implement two interfaces:

• Extensibility.IDTExtensibility2
• Office.IRibbonExtensibility

In Visual C# and Visual Basic add-ins, these interfaces must be implemented in the same class.

When implementing Office.IRibbonExtensibility, use the IRibbonExtensibility.GetCustomUI method to return custom Ribbon XML markup to Outlook. When and how Outlook calls GetCustomUI is unique among Office applications:

• Outlook calls GetCustomUI when the user or a programmatic action opens an item in an Outlook Inspector.
• Outlook calls GetCustomUI when the Ribbon is loaded for the first time for a given Ribbon ID.
• Viewing an item in the Reading Pane does not cause Outlook to call GetCustomUI because the Ribbon is not displayed in the Reading Pane.

The Ribbon ID is a string that is passed from Outlook to GetCustomUI, specifying the Ribbon to be loaded. Add-in developers can use this string to determine which custom Ribbon XML markup to return to the application. A Ribbon ID can also be used to determine the type of Outlook item to be displayed.

In some cases such as a MailItem or PostItem, Outlook calls GetCustomUI once when the first compose note is displayed (where RibbonID = Microsoft.Outlook.Mail.Compose) and another time when the first read note is displayed (where RibbonID = Microsoft.Outlook.Mail.Read).

The unique Ribbon IDs used by Outlook are listed in the following table.

Note
Sticky notes do not implement the Ribbon, so IPM.StickyNote is not listed in the table of Ribbon IDs and message classes.

You will notice that message class is represented as IPM.Type.* in most cases in the table. This notation means that either the first instance of the base message class (for example, IPM.Contact) or a derived custom message class (IPM.Contact.ShoeStore) that appears in an Inspector will cause Outlook to call GetCustomUI. Note that because a base message class shares the same Ribbon XML with custom message classes that are derived from it, and Outlook calls GetCustomUI only once per Ribbon ID, it is not possible to specify a Ribbon XML markup that will be exclusively applied to a derived custom message class and not the base message class. However, if you are only interested in having controls appearing in the Ribbon on Inspectors for one custom message class and not all other message classes with the same base message class, do the following:

1. In GetCustomUI, return Ribbon XML markup for the Ribbon ID for the custom message class (for example, IPM.Contact.ShoeStore) to the Ribbon. All Ribbons used by items with the same base message class (for example, IPM.Contact) will contain the controls that have been added.
2. In the Ribbon XML, specify IRibbonControl.Context callbacks for each tab, group, and control that is specific to the custom message class. These callbacks will be used to display the controls for the custom message class and hide the controls for the base message class and all other message classes with the same base message class.
3. In each getVisible callback, cast the IRibbonControl.Context parameter that is passed to the callback to an Outlook Inspector object. Use the MessageClass property of Inspector.CurrentItem to determine whether to return True or False in the getVisible callback.

If you need to customize the Ribbon on all or multiple Outlook message classes, then a different set of recommendations apply:

• If you want to customize the first built-in tab on all Outlook Inspectors, you will have to supply separate Ribbon XML for different Ribbon IDs since built-in first tabs do not have the same name across all Ribbon IDs.
• If you want to customize the Ribbon on multiple Outlook Inspectors, you might have to supply separate Ribbon XML for different Ribbon IDs depending upon the tab name.