New in Outlook for developers

This document provides a top-level view of the additions and enhancements for developers in Microsoft Outlook 2013, including mail apps, third party weather data services for the Weather Bar, and inline response. The document also describes changes to the Outlook Social Connector, Office Mobile Service, support for Outlook 2013 coexisting with a previous version of Outlook, and new performance criteria for add-ins. For developers who are ready to get a jump start on the Outlook platform, this document provides you with sufficient information to begin coding against Outlook 2013.

Introduction

Outlook 2013 provide programmability support for a number of new features. Office Add-ins is a new platform that allows developers to use web-based tools such as HTML and JavaScript to build apps that surface within the Outlook Reading Pane or inspector window. Unlike traditional COM Add-ins, apps don’t require that you install or update a DLL on the user’s computer. When a mail app is initialized by the user, the mail app uses the Office Add-ins JavaScript object model to provide contextual information about the selected message in the Outlook rich client and Outlook Web App. Your app runs on your web server and any changes you make in your web content will be immediately reflected in your app running on an Outlook client.

In addition to apps, there is extensibility support for the new Weather Bar, and changes to how Outlook 2013 supports Outlook Social Connector provider extensibility and Office Mobile Services. Other features such as Outlook coexistence and add-in performance monitoring are not related directly to any object model, but they will influence the way that you architect and build your solution.

The following are the important changes for developers in Outlook 2013:

• Mail apps

• Custom weather service for the Weather Bar

• Inline response and other Outlook object model enhancements

• Outlook Social Connector enhancements

• Discontinuing support for Office Mobile Service

• Coexistence with previous Outlook versions

• Performance criteria for keeping add-ins enabled

Note

Objects, properties, methods, and events depicted in this article might change in the RTM release of Outlook 2013. Additional object model features might also be introduced before the RTM release of Outlook 2013. Be sure to obtain the RTM version of Outlook 2013 to test your code changes before you release your solution.

Mail apps

Office Add-ins are a new feature that lets you incorporate web services directly into Outlook without having to write and deploy a traditional Outlook add-in. In Outlook 2013, mail apps provide rich and compelling experiences to users in Outlook or Outlook Web App using a single code base. A mail app displays an app pane adjacent to the Outlook Reading Pane or an inspector to provide web content appropriate for the displayed message or appointment. Apps are created using ubiquitous web technologies such as HTML and JavaScript. Mail apps do require Exchange 2013 and are not available for users with accounts on versions of Exchange previous to Exchange 2013 or with POP3 or IMAP accounts.

The following sections briefly describe the mail apps architecture, activation rules, and security model. These sections are not meant as a comprehensive technical reference. Please consult Office Add-ins for details on the manifest schema, rule conditions, built-in entities and custom regular expressions, the JavaScript Object Model, and submitting a mail app to the Office Store.

Architecture

The architecture of the mail apps platform is beautiful in its simplicity. An Exchange client such as the Outlook rich client or Outlook Web App downloads mail app manifests from the Exchange server. The XML manifest specifies a set of rules that are run on the client and determine whether the app is activated when a user selects an email message or appointment. If the activation rules are satisfied, then the app button will appear on the app bar. For example, in Figure 1 you see that both the Bing Maps and Action Item mail apps have activated based on the content of the selected email message and appear on the app bar.

Figure 1. Mail app showing context sensitive Bing map in Outlook

A mail app is said to be activated when its app button appears on the app bar. Once the user selects the app button, the app pane appears and runs an Initialize event handler in the JavaScript code of your web page hosted on your web server. Figure 2 describes the process that takes place when an Outlook client starts and the user selects an item in Outlook.

Figure 2. Mail app architecture and startup process

The JavaScript code of a mail app can access properties of the selected message or appointment item. Depending on the permission requested by the app, the app can also access custom properties, enumerate entities (such as addresses or meeting suggestions) or regular expression matches, and make Exchange Web Service (EWS) calls.

Activation Rules

Activation rules control when a mail app is activated in the user interface of an Outlook client. Rules are defined in the XML manifest and are applied by the rules evaluation engine to the selected item in the Reading Pane or an inspector window. If the rules evaluate to true, the app button is visible on the app bar. Note the following about rules:

• Multiple rules can be combined for complex activation needs.

  Apply logical And or Or operators.

  Rules can be defined using regular expressions.

  Rules can access known entities such as phone numbers, URLs, and street addresses.

Rule types are as follows.

Type of rule	Description
ItemIs	A rule to check if the item is a specific type (appointment, message or custom message class). For example: ```xml ```
ItemHasKnownEntity	A rule to check if the item has a specific entity. For example: ```xml ````
ItemHasRegularExpressionMatch	A rule to check if there are matches to the specified regular expression.
RuleCollection	Defines a rule composed of multiple rules (combined using And or Or).

Note that rules can recognize known entities or custom regular expressions that you define in the app manifest.

What are known entities? Known entities are parsed by the Exchange server during message transport and stamped on the message for use by the rules evaluation engine. The following table lists some known entities that you can use to create activation rules.

Type of known entity	Activation condition
Address	United States street addresses. For example: 1 Microsoft Way, Redmond, WA 07722
Contact	A personal name related to other entities. For example: Steve Ballmer, Microsoft, 1 Microsoft Way, Redmond, WA 98052
EmailAddress	Any SMTP email address. For example: someone@contoso.com
MeetingSuggestion	A reference to an event or meeting. For example: Let’s meet next Tuesday for lunch.
PhoneNumber	United States telephone numbers. For example: (425) 555-1212
TaskSuggestion	Actionable sentences in an email. For example: Please install Office 2013 on my computer.
Url	A file name or web address. For example: https://microsoft.com

Security model

Your mailbox contains your private information. In a corporate setting, your mailbox contains privileged communications with your customers, suppliers, and your fellow employees. Outlook safeguards that information and ensures that mail apps keep that information secure. When a user acquires a mail app, the user must grant the permission level requested by the app in its manifest. If the user does not grant permission, the app is not installed into the user’s Exchange mailbox. Mail apps use a three-tiered security model. What an app can do depends on the security grant by the end user or administrator, based on the permission requested in the app manifest. Note that apps that require the read/write mailbox permission cannot be installed by an end user. Apps that request the read/write mailbox permission must be installed by a system administrator.

Figure 3. Three-tiered security model for mail apps

Figure 3 and the table below describe the 3 permission levels. Note that the default permission, restricted, restricts an app from accessing personally identifiable information (PII) from the currently selected message. If the user grants an elevated level of permission such as read item, the app can obtain information such as the sender or recipients of the message. Read/write mailbox permission allows the app to call a subset of powerful EWS functions including the ability to create or modify items in a user’s mailbox.

Actor	Permission in manifest	Access
End users installing low trust mail apps	Restricted	Subset of known entities from message: Address, PhoneNumber, Url
End users installing low trust mail apps	ReadItem	All known entities from message: Address, Contact, EmailAddress, MeetingSuggestion, PhoneNumber, TaskSuggestion, Url Custom regular expression matches from message body. JSOM: Recipients/sender/attendees Subject/location Single sign on User profile GetUserIdentityTokenAsync method
Exchange administrators installing high trust mail apps	ReadWriteMailbox	ReadItem access and the following: JSOM: makeEWSRequestAsync method EWS: subset of EWS APIs

Custom weather data service for the Weather Bar

The new Weather Bar in Outlook 2013 uses MSN Weather to provide weather forecasts for user-selected locations. Third party weather data services can plug into Outlook to provide similar weather forecasts. Figure 4 shows the Weather Bar displaying a weather forecast for New York.

Figure 4. The Weather Bar displaying a weather forecast for New York

To plug into the Outlook Weather Bar, a weather data service can implement a web service that supports a simple 2-part protocol:

1. The weather data service supports a base URL to a web service, for example, http://service.contoso.com/data.aspx.

2. Part 1: The web service allows Outlook to append the following parameters to the base URL, to request a location code that corresponds to the user-selected location:

   • outputview=search, which indicates that the request is a location search.

   • weasearchstr=city, where city indicates the user-selected location for weather information.

   • culture=LCID, where LCID indicates the culture of the version of Office installed for the user. The value is defined in [RFC4646] Tags for Identifying Languages

   • src=outlook, which indicates that Outlook is the client application requesting the service.

   The web service response must conform to the Outlook Weather Location XML Schema.

   Figure 5 summarizes part 1 of the protocol to request and respond with a location code for the user-selected location.

   Figure 5. Web service request and response for a location code

   

3. Part 2: The web service also supports Outlook to append the following parameters, to request forecast information for the location code obtained from Part 1:

   • wealocations=code, where code is the location obtained from Part 1.

   • weadegreetype=degreetype, where degreetype can be c for metric or f for imperial units for temperature.

   • culture=LCID, where LCID indicates the culture of the version of Office, similar to that in Part 1.

   • src=outlook, which indicates that Outlook is the client application requesting the service, similar to Part 1.

   The web service response must conform to the Outlook Weather Information XML Schema.

   Figure 6 summarizes part 2 of the protocol to request and respond for weather data for the user-selected location.

   Figure 6. Web service request and response for weather information

   

For more information, see Extending the Weather Bar in Outlook.

Outlook Object Model changes

New objects, properties, methods, events, and enumeration values have been added to the Outlook object model to provide programmability support for new Outlook 2013 features. Additionally, object model improvements address frequent developer requests for changes to the Outlook platform.

Enhancements to existing Outlook objects

The following table lists enhancements to objects, collections, and enumerations that were available in previous versions of Outlook. Only new methods, properties, events, and enumeration values are listed in the New members column.

Table 1. Outlook object model enhancements

Object or enumeration	New members
AppointmentItem	ReadComplete event
ContactItem	ShowCheckAddressDialog method ShowCheckFullNameDialog method ReadComplete event
DistListItem	ReadComplete event
DocumentItem	ReadComplete event
Explorer	ActiveInlineResponse property ActiveInlineResponseWordEditor property InlineResponse event InlineResponseClose event
JournalItem	ReadComplete event
MailItem	ReadComplete event
MeetingItem	ReadComplete event
OlAccountType	olEas enumeration value
OlBusyStatus	olWorkingElsewhere enumeration value
OlObjectClass	olClassPeopleView enumeration value
OlSearchScope	olSearchScopeCurrentStore enumeration value
OlViewType	olPeopleView enumeration value
PostItem	ReadComplete event
RemoteItem	ReadComplete event
ReportItem	ReadComplete event
SharingItem	ReadComplete event
TaskItem	ReadComplete event
TaskRequestAcceptItem	ReadComplete event
TaskRequestDeclineItem	ReadComplete event
TaskRequestItem	ReadComplete event
TaskRequestUpdateItem	ReadComplete event

New objects

The following table lists the new objects introduced in Outlook 2013. All object members are listed in the Properties and Methods column.

Table 2. Outlook object model additions

Object	Properties	Methods
PeopleView	Application	Apply
	Class	Copy
	Filter	Delete
	Language	GoToDate
	LockUserChanges	Reset
	Name	Save
	Parent
	SaveOption
	Session
	SortFields
	Standard
	ViewType
	XML

Deprecated objects and members

The following are the main deprecations in the Outlook object model in this release:

• Support for the To-Do Bar

  Because the To-Do Bar is no longer supported in the Outlook 2013 user interface, attempting to use Explorer.ShowPane(olToDoBar) to display or hide the To-Do Bar returns an error. You should modify any existing code to handle the error or avoid calling ShowPane with the olToDoBar constant for code that runs in Outlook 2013.

• Support for contact linking

  The contact linking feature and its object model support (through the Link and Links objects) has been deprecated. The Links property for each item object now returns Null (Nothing in Visual Basic), and you should modify any existing code to handle this behavior.

• The MobileItem object. See the section Discontinuing support for Office Mobile Service for more information.

The following table lists the objects, members, and enumeration values deprecated in Outlook 2013. Only deprecated object members and enumeration values are listed in the Deprecated members column. Note that while deprecated members are hidden in the Visual Basic object browser, deprecated enumerations or enumeration values are not hidden, but nonetheless should no longer be used in your code.

Object, collection, or enumeration	Deprecated member or enumeration value
AppointmentItem	Links property
CalendarView	DayWeekFont property DayWeekTimeFont property MonthFont property
ContactItem	Links property
DistListItem	Links property
DocumentItem	Links property
Exception	ItemProperties property
JournalItem	Links property
Link	ApplicationClass property Item property Name property Parent property Session property Type property
Links	ApplicationClass property Count property Parent property Session property AddItem method Remove method
MailItem	Links property
MeetingItem	Links property
MobileItem	Properties Actions property Application property Attachments property BillingInformation property Body property Categories property Class property Companies property ConversationIndex property ConversationTopic property CreationTime property Count property EntryID property FormDescription property GetInspector property HTMLBody property Importance property ItemProperties property LastModificationTime property MessageClass property Mileage property MobileFormat property NoAging property OutlookInternalVersion property OutlookVersion property Parent property PropertyAccessor property ReceivedByEntryID property ReceivedByName property ReceivedTime property Recipients property ReplyRecipientNames property ReplyRecipients property Saved property SenderEmailAddress property SenderEmailType property SenderName property SendUsingAccount property Sensitivity property Sent property SentOn property Session property Size property SMILBody property Subject property Submitted property To property UnRead property UserProperties property Methods Close method Copy method Delete method Display method Forward method Move method Reply method ReplyAll method Save method SaveAs method Send method Events AttachmentAdd event AttachmentReadAttachmentRemove event BeforeAttachmentAdd event BeforeAttachmentPreview event BeforeAttachmentRead event BeforeAttachmentSave event BeforeAttachmentWriteToTempFile event BeforeAutoSave event BeforeCheckNames event BeforeDelete event Close event CustomAction event CustomPropertyChange event event Forward event Open event PropertyChange event Read event ReadComplete event Reply event ReplyAll event Send event UnloadWrite event
NoteItem	Links property
OlObjectClass	olLink enumeration value olLinks enumeration value olMobile enumeration value
OlPane	olToDoBar enumeration value
PostItem	Links property
RemoteItem	Links property
ReportItem	Links property
TaskItem	Links property
TaskRequestAcceptItem	Links property
TaskRequestDeclineItem	Links property
TaskRequestItem	Links property
TaskRequestUpdateItem	Links property

Working with an inline response

Outlook 2013 introduces the inline response feature where the user can compose a response in the Reading Pane, rather than opening a new inspector window. If your solution requires adding custom Office Fluent UI controls to the compose note ribbon, or you need to apply business logic or custom functionality to a response message before the response is sent, modify your solution to use the new InlineResponse event on the Explorer object.

Note

You can use inline response only if you have selected in the View menu to display the Reading Pane in the explorer.

The InlineResponse event is the inline equivalent to the NewInspector event on the Inspectors collection object. The NewInspector event fires when a new inspector window is opened. The InlineResponse event fires when the user performs an action that causes an inline response to appear in the Reading Pane as shown in Figure 7 below.

Figure 7. An Inline response is created when user selects a response action

Object model support for inline response

The following members have been added to the Explorer object to provide programmatic support for the inline response feature:

Member	Description
ActiveInlineResponse property	Returns an item object representing the active inline response item in the Reading Pane. Read-only.
ActiveInlineResponseWordEditor property	Returns the Word Document object of the active inline response that is displayed in the Reading Pane. Read-only.
InlineResponse event	Occurs when the user performs an action that causes an inline response to appear in the Reading Pane.

Using the InlineResponse event

Let’s imagine a scenario where your code needs to insert a disclaimer for every compose message including reply, reply all, and forward messages. Since inline response is the default response mode in Outlook 2013, your code must hook up an event handler for the InlineResponse event on the Explorer object. The following C# code hooks up an event handler for the InlineResponse event in the OutlookExplorer class. In this code sample, OutlookExplorer is a wrapper class for a collection of Explorer objects.

public OutlookExplorer(Outlook.Explorer explorer)
{
    m_Window = explorer;

    // Hook up InlineResponse event
    m_Window.InlineResponse += 
        new Outlook.ExplorerEvents_10_InlineResponseEventHandler
        (m_Window_InlineResponse);

    // Hook up other events if applicable.
}

Once the InlineResponse event fires, the sample code creates a MailItem instance of m_Mail and listens to the PropertyChange event for that MailItem object. m_Mail is an event-aware instance variable that you can use to implement any business logic required by your add-in.

The sample code compares the MailItem.Size property to 0 to determine whether the inline response is new or an existing draft. The ActiveInlineResponseWordEditor property returns a Word.Document object, doc, which represents the active inline response for the active Explorer. Using the Word object model, the code adds a disclaimer to the beginning of this doc object.

// InlineResponse fires when the user creates an inline response item
void m_Window_InlineResponse(object Item)
{
    if (Item is Outlook.MailItem)
    {
        m_Mail = Item as Outlook.MailItem;
        // Hook up event-aware instance variable.
        // Use the variable to implement any business logic 
        // required by your add-in.
        m_Mail.PropertyChange += 
            new Outlook.ItemEvents_10_PropertyChangeEventHandler(
                m_Mail_PropertyChange);
        // Implement any business logic.

        // Use mail.Size to determine if item is new 
        // or is a draft inline response.
        // Size == 0 indicates a new inline response.
        if (m_Mail.Size == 0)
        {
            {
                Word.Document doc = 
                    m_Window.ActiveInlineResponseWordEditor as Word.Document;
                Word.Application wdApp = doc.Application as Word.Application;
                Word.Range rng = wdApp.ActiveDocument.Range(Start: 1);
                rng.InsertBefore("My Disclaimer...");
            }
        }
        else
        {
            // Do nothing.
        }
    }
}

Note that the ActiveInlineResponse property returns a MailItem object representing the active inline response item. You can use the same properties and methods of the MailItem object on this item, except for the following:

• MailItem.Actions property

• MailItem.Close method

• MailItem.Copy method

• MailItem.Delete method

• MailItem.Forward method

• MailItem.Move method

• MailItem.Reply method

• MailItem.ReplyAll method

• MailItem.Send method

On the other hand, if no inline response is active, the ActiveInlineResponseWordEditor and ActiveInlineResponse properties return null.

Adding custom controls to the Compose Tools contextual tab

Another possible scenario is that you want to extend the Outlook user interface for an inline reply. To extend the Outlook user interface, you need to use Office Fluent UI extensibility which is not covered in depth in this article. See the links supplied at the end of this article for additional information on extending the Outlook user interface. When an inline response is displayed in Outlook 2013, the user sees the Compose Tools contextual tab displayed on the Office Fluent ribbon. To add your control to the Compose Tools contextual tab, add your custom controls to the <contextualTabs> </contextualTabs> section of ribbon XML that will be passed to the GetCustomUI method of the IRibbonExtensibility interface for the RibbonID equal to “Microsoft.Outlook.Explorer”. You must identify the tabSet element with the appropriate value for the idMso attribute, which in this case is “TabComposeTools”. The following ribbon XML creates the MyButton control shown in Figure 7.

    <contextualTabs>
      <tabSet idMso="TabComposeTools">
        <tab idMso="TabMessage">
          <group label="MyGroup" id="MyComposeToolsGroup">
            <button id="MyButtonInlineResponse"
                    size="large"
                    label="MyButton"
                    imageMso="MagicEightBall"
                    onAction="OnInlineResponseButtonClick" />
          </group>
        </tab>
      </tabSet>
    </contextualTabs>

When the user selects the MyButton control, the OnInlineResponseButtonClick handler is called. The following code sample uses the ActiveInlineResponseWordEditor property to obtain an instance of a Word.Document object. You can then use all the functionality of the Word.Document object to insert and format text as needed by your scenario.

// Callback for inline response custom button.
public void OnInlineResponseButtonClick(Office.IRibbonControl control)
{
    if (control.Context is Outlook.Explorer)
    {
        Outlook.Explorer myExplorer =
            control.Context as Outlook.Explorer;
        Word.Document doc =
        myExplorer.ActiveInlineResponseWordEditor as Word.Document;
        Word.Application wdApp = doc.Application as Word.Application;
        Word.Range rng = wdApp.ActiveDocument.Range(Start: 1,
            End: wdApp.ActiveDocument.Characters.Count);
        rng.InsertBefore("\n" + "My Disclaimer...");
    }
}

Changes to Outlook Social Connector provider extensibility

In Office 2013, the Outlook Social Connector (OSC) has expanded its scope. It allows not only Outlook but all Office client applications that support displaying user presence and the Contact Card to display an aggregation of social information updates applied on a professional or social network site. In addition, SharePoint Server, SharePoint Workspace, and the Lync client also support the OSC.

One major change in OSC provider extensibility in Outlook 2013 is that activities are no longer synchronized using the activities cache. If an OSC provider supports displaying activities, then the provider must synchronize activities on demand to display up-to-date activities.

In addition, providers can now use the OSC XML Schema to communicate extra metadata for a person, for example, askmeabout, businessAddress, interests, skills, schools, website.

For detailed information, see What's New for Providers.

Discontinuing support for Office Mobile Service

In Office 2010, developers can build web services for Office Mobile Service (OMS) to integrate the mobile capabilities of Outlook and SharePoint with mobile devices. In Office 2013, only SharePoint continues to support OMS. Outlook 2013 has also deprecated the MobileItem object and its members. Attempting to create a MobileItem using Application.CreateItem returns E_INVALIDARG.

Coexistence with previous Outlook versions

Coexistence refers to the ability of delivering Outlook 2013 by Click-to-Run on the same computer where Outlook 2007 or Outlook 2010 is present. Coexistence, also known as side-by-side installation, allows the user to try Outlook 2013 without having to uninstall a previous Outlook version. Click-to-Run is the default delivery mechanism for Outlook 2013. Once Outlook 2013 is delivered on a computer, the user can run Outlook 2013 or the previous version of Outlook installed on their computer. Be aware that coexistence does not mean running two versions of Outlook simultaneously. Running two versions of Outlook simultaneously is not supported and Outlook displays an error dialog if you attempt to run a previous version of Outlook while Outlook 2013 is running.

Note

Coexistence of Outlook 2013 is not supported with versions of Outlook prior to Outlook 2007.

Version Support Matrix

This section describes the bitness and installation modes of earlier versions of Outlook that can coexist with Outlook 2013. Note the following:

• MSI refers to the Microsoft Installer (MSI) installation of a previous version of Outlook.

• Supported Windows versions for Office 2013 are Windows 7 and Windows 8 only.

• Windows Server is not supported for Click-to-Run.

• Outlook 2013 does not support coexistence with Outlook 2003 or earlier.

• Outlook 2013 does not support coexistence with the same version of Outlook – that is, Outlook 2013 installed by MSI and Outlook 2013 delivered by Click-to-Run are not supported on the same computer.

• Cross-bitness is not supported. The user must always install the Click-to-Run version that matches the bitness of the down-level MSI install.

Version	Outlook 2007 MSI	Outlook 2010 x86 MSI	Outlook 2010 x64 MSI
Outlook 2013 C2R x86	Yes	Yes	No
Outlook 2013 C2R x64	No	No	Yes

Version-dependent profiles

To support coexistence, Outlook 2013 stores Outlook profiles in a separate hive in the Windows registry. The profile from a previous version of Outlook is migrated to the Outlook 2013 profile hive during the first boot of Outlook 2013. Subsequent changes or additions to the profile for the previous version of Outlook are not migrated during subsequent boots of Outlook 2013.

Profiles hive in Windows Registry

Unlike previous versions of Outlook that stored profiles in a version-independent manner under HKCU\Software\Microsoft\Windows NT\Windows Messaging Subsystem\Profiles, Outlook 2013 stores profiles in a versioned hive under the following key:

HKEY_CURRENT_USER\Software\Microsoft\Office\<version>\Outlook\Profiles

where <version> is a string representing the xx.0 major version, such as 15.0 for Outlook 2013.

Calling MAPI profile APIs

There are no changes for applications to read profile data from a profile hive. After initializing MAPI (for either a down-level version or the most current MAPI version, depending on the application’s requirements), an application can use common MAPI profile APIs to read values from the appropriate profile hive.

If an application initializes MAPI for Outlook 2013, MAPI profile APIs read or write profile data to the versioned hive. If the application initializes MAPI for a previous version of Outlook, MAPI profile APIs read or write profile data to the version-independent hive.

App Path registration

To prevent down-level applications from loading the wrong MAPI version, Outlook 2013 modifies the App Path registration in the registry. A down-level version of an application loading the wrong MAPI version can result in a crash in the application attempting to load MAPI. Typically, previous versions of Outlook have written the Outlook App Path to the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\OUTLOOK.EXE

Previous versions of Click-to-Run did not modify the App Path for Outlook. Delivering Outlook 2013 by Click-To-Run modifies the App Path as follows:

• Installs patches for Outlook 2007 or Outlook 2010 to remove the dependency on App Path.

  Modify the App Path to point to the Outlook 2013 path for Outlook.exe.

  The default path for Outlook.exe for Outlook 2013 is C:\Program Files\Microsoft Office 15\root\office15.

MAPI Versioning

Applications that use MAPI calls the MAPIInitialize function to initialize a MAPI session. By default, applications that initialize MAPI use the version of MAPI provided by Outlook 2013. If you need to use a different version of MAPI, see the following topics in the Outlook 2013 MAPI Reference.

• Building MAPI Applications on 32-Bit and 64-Bit Platforms

• How to: Link to MAPI Functions

• How to: Choose a Specific Version of MAPI to Load

Simple MAPI

Simple MAPI refers to the API that allows applications to send mail with attachments using MAPISendMail or the new MAPISendMailW API introduced with Windows 8.

• The only supported Simple MAPI APIs are MAPISendMail (Windows 7) or MapiSendMailW (Windows 8).

  Developers should consider modifying existing Simple MAPI code to use MAPISendMailW (Windows 8) or MAPISendMailHelper (Windows 7) with full Unicode support and the ability to display a modeless Outlook inspector.

  If Outlook is not running or Outlook 2013 is running, calling MAPISendMail or MAPISendMailW displays an Outlook 2013 inspector.

  If a previous version of Outlook is running, calling MAPISendMail or MAPISendMailW displays the following error:

  This action is not supported while an older version of Outlook is running.

Protocol handlers

During installation, Outlook 2013 is registered as the default protocol handler for the common protocols listed in the following table. Outlook 2013, Outlook 2010, and Outlook 2007 support these protocols.

Protocol	Description
feed:, feeds:	Handler for RSS feeds
mailto:	Handler for MailTo links that display an Outlook inspector
stssync:	Handler for SharePoint sync
outlook:	Outlook protocol can only be used from Outlook item body or folder home page
webcal:	Handler for webcal protocol

Note the following if Outlook 2013 is present with an older version of Outlook on the same computer:

• If no previous version of Outlook is running, calling the protocol handler invokes Outlook 2013 to handle the protocol handler request.

If a previous version of Outlook is running, calling the protocol handler uses a command line handoff to invoke the previous version of Outlook to handle the request.

File Associations

During installation, Outlook 2013 is registered as the default handler for the common file associations listed in the following table. Outlook 2013, Outlook 2010, and Outlook 2007 support all these file extensions.

File association	Description
.eml	Email message
.fdm	Outlook form definition
.hol	Outlook holiday
.ics	iCalendar file
.msg	Outlook message item
.oft	Outlook item template
.pst	Outlook data file
.vcf	vCard file
.vcs	vCalendar file

Note the following if Outlook 2013 is present with an older version of Outlook on the same computer:

• If no previous version of Outlook is running, opening an item from the file system opens the item in Outlook 2013. This action starts Outlook 2013 if it is not already running.

• If a previous version of Outlook is running, opening an item from the file system cause Outlook 2013 to launch and hand off the request to that previous version of Outlook.

Co-creating an Outlook Application object

Add-ins should use the Application object passed back in the OnConnection event (native add-ins) or ThisAddin_Startup event (managed add-ins built using Visual Studio Tools for Office). If your application co-creates an Outlook.Application object using CreateObject or another function that provides the ability to co-create an instance of Outlook.Application, you should be aware of the following in a coexistence environment:

• If Outlook is not running or Outlook 2013 is running, calling CreateObject(“Outlook.Application”) returns an Outlook.Application object that represents Outlook 2013.

• If a previous version of Outlook is running, calling CreateObject returns an Outlook.Application object that represents the previous version of Outlook.

• Examine the Application.Version property to determine the version of Outlook that is running.

Detecting Click-to-Run

To detect the existence of Outlook in the Click-to-Run environment, verify that the VirtualOutlook key exists in the following registry key:

HKLM\Software\Microsoft\Office\15.0\Common\InstallRoot\Virtual\VirtualOutlook

If the VirtualOutlook key exists, then Outlook has been delivered as a Click-to-Run application.

Ensuring your solution will run in the coexistence environment

Since coexistence is the default delivery mode, you should test your solution against Outlook 2013 and previous versions of Outlook and check for the following possible issues:

• Add-ins are registered in version-independent hive in the Windows registry under

  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Outlook\Addins

  or

  HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Outlook\Addins

  Since the add-in registration is version-independent, your add-in should run when Outlook 2013 or a previous version of Outlook is running. Be sure to test an updated version of your add-in against Outlook 2013 and previous Outlook versions. The add-in should detect the Outlook version using Application.Version and adjust gracefully to the running Outlook version.

• Remove dependencies on App Path from your code.

• Do not use the Windows registry to enumerate profiles. Instead use the MAPI profile APIs.

Performance criteria for keeping add-ins enabled

Extending the add-in resiliency pillar of Outlook 2010, Outlook 2013 monitors add-in performance metrics such as add-in startup, shutdown, folder switch, item open, and invoke frequency. Outlook records the elapsed time in milliseconds for each performance monitoring metric.

For example, the startup metric measures the time required by each connected add-in during Outlook startup. Outlook then computes the median startup time over 5 successive iterations. If the median startup time exceeds 1000 milliseconds (1 second), then Outlook disables the add-in and displays a notification to the user that an add-in has been disabled. The user has the option of always enabling the add-in, in which case Outlook will not disable the add-in even if the add-in exceeds the 1000 millisecond performance threshold

Monitoring add-in performance for default disabling

Outlook uses the following criteria to determine if it should disable an add-in. The user has the option of always enabling an add-in and exempting the add-in from the add-in disabling criteria.

Criteria	Threshold (in milliseconds)	Description
Startup	1000	Measures the time in milliseconds for the add-in to complete startup using the IDTExtensibility2_OnConnection event. By default, if the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in.
Shutdown	500	Measures the time in milliseconds for the add-in to complete shutdown using the IDTExtensibility2_OnDisconnection event. Only applies to add-ins that request slow shutdown. Add-ins that use fast shutdown are not subject to this criteria. If the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in on the next startup of Outlook.
Folder switch	500	Measures the time in milliseconds for the add-in to complete folder switch using the BeforeFolderSwitch and FolderSwitch events on the Explorer object. By default, if the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in.
Item open	500	Measures the time in milliseconds for the add-in to complete opening an item using the Open event on an item. By default, if the median time over 5 successive iterations exceeds the performance threshold, Outlook disables the add-in.
Invoke frequency	1000	Measures the time interval in milliseconds between the add-in making 10,000 successive invoke calls. By default, if the interval between 10,000 successive calls and the next is less than the performance threshold, Outlook disables the add-in. Unlike the other 4 criteria, this criterion does not incur taking a median value.

System Administrator control over add-ins

The user has control over which add-ins run on their computer. For system administrators, Outlook 2013 provides an enhanced level of control over add-ins using group policy. Group policy will always override user settings and users are prevented from changing add-in settings for add-ins that have been configured by the group policy “List of Managed Add-ins”. The policy key is as follows.

Key	HKCU\Software\Policies\Microsoft\Office\15.0\Outlook\Resiliency\AddinList
Name	List of Managed Add-ins
Description	This policy setting allows you to specify which add-ins are always enabled, always disabled (blocked), or configurable by the user. > [!NOTE] > Here, the term “managed” refers to add-ins that are handled by the group policy, and does not relate to add-ins being developed in managed programming languages.

To block add-ins that are not managed by this policy setting, you must also configure the "Block all unmanaged add-ins" policy setting.

To enable this policy setting, provide the following information for each add-in:

• In "Value name," specify the programmatic identifier (ProgID) for COM add-ins.

  To obtain the ProgID for an add-in, use the Registry Editor on the client computer where the add-in is installed to locate key names under

  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Outlook\Addins

  or

  HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\Outlook\Addins

• In "Value," specify the value as follows:

  • To specify that an add-in is always disabled (blocked), specify 0.

  • To specify that an add-in is always enabled, specify 1.

  • To specify that an add-in is configurable by the user and not blocked by the "Block all unmanaged add-ins" policy setting when enabled, specify 2.

If you disable or do not enable this policy setting, the list of managed add-ins is deleted. If the "Block all unmanaged add-ins" policy setting is enabled, then all add-ins are blocked.

Add-ins that are disabled by this policy will never be disabled by the Outlook add-in disabling feature, which disables add-ins for performance, resiliency, or reliability reasons.

User interface for add-in disabling feature

When an add-in exceeds the performance threshold, Outlook displays the notification bar shown in Figure 8 that informs the user that one or more add-ins has been disabled.

Figure 8. Outlook displays a notification bar when an add-in is disabled automatically

If the user clicks the View Disabled Add-ins button on the notification bar, the Disabled Add-ins dialog will be displayed as shown in Figure 9.

Figure 9. Clicking “Always enable this add-in” button enables the add-in and exempts the add-in from the add-in disabling feature

If the user decides that the performance timing required by the add-in is acceptable, the user has the choice of always enabling the add-in. An add-in that is always enabled will not be automatically disabled by Outlook based on performance criteria. If for some reason the user decides later that he or she no longer wants to exempt the add-in from the add-in disabling feature, the user can also disable the add-in from the Disabled Add-ins dialog shown in Figure 10.

Figure 10. Selecting the Disable this add-in button disables the add-in

Preventing an add-in from being disabled

While most add-ins will not be disabled by the add-in disabling feature, you don’t want your add-in to be disabled consistently. Here are suggestions for improving add-in performance:

• Prefer native COM add-ins over managed add-ins since managed add-ins must incur the overhead of loading the .NET Framework during Outlook startup.

• If you have long-running tasks such as making an expensive connection to a database, defer those tasks to occur after startup.

• If possible, cache data locally rather than making expensive network calls during the FolderSwitch and BeforeFolderSwitch events of an explorer, or Open events of an item.

• Polling is an expensive operation, so always prefer an event-driven model over polling.

• Be aware that all calls to the Outlook object model execute on Outlook’s main foreground thread. Avoid making long-running Outlook object model calls if possible. Note that in Outlook 2013, calls to the Outlook object model return E_RPC_WRONG_THREAD when the Outlook object model is called from a background thread.

In particular, if you use Office developer tools in Visual Studio to create managed add-ins, be aware that the first add-in to load the CLR is likely to take a performance hit. Consider the following measures, and see the additional resources at the end of this document for details:

• Load a managed add-in on demand.

• Delay loading the CLR.

• Use an MSI deployment package instead of ClickOnce.

• If applicable, use a Fast Path to bypass schema validation, digital signatures validation in manifests, and automatic update checking. You can find more information about using the Fast Path in the blog post Performance Improvements Coming Soon to a Service Pack Near You (Stephen Peters).

• If your add-in extends the ribbon and links in a large library, override ribbon reflection.

Conclusion

Mail apps provide an exciting opportunity for developers to bring web services and contextual web-driven UI directly into Outlook and Outlook Web App. We have delivered on our vision of “Write once, run anywhere” for Exchange and Outlook developers. We now offer two extensibility pillars, the first built on the Office COM add-in feature introduced in Office 2000 and the second built on the mail apps platform. The COM add-in model supports deep integration with only the Outlook client and requires that you touch every desktop when your solution is installed. If you have an existing add-in solution, you should consider updating the add-in to work with inline response, coexistence, and the add-in disabling feature. If you are looking for new opportunities to reach a very large audience using Outlook and Outlook Web App, create a mail app and enjoy web-simple deployment and integration of your web service directly into the Outlook UI. Whichever path you choose (and you might choose both), happy coding!

Additional resources

Office Add-ins

• Office Add-ins

Weather Bar

• Extending the Weather Bar in Outlook

• Outlook Weather Location XML Schema

• Outlook Weather Information XML Schema

Outlook and Office object models

• Outlook 2013 Developer Reference

• Extending the User Interface in Outlook 2010

Outlook Social Connector

• Getting Started with Developing an Outlook Social Connector Provider

Coexistence and MAPI

• Outlook 2013 MAPI Reference

• Outlook 2010: MAPI Header Files

• Outlook 2010 Messaging API (MAPI) Code Samples

• SGriffin’s MAPI Internals

Performance and Office add-ins development in Visual Studio

• Demand-Loading VSTO Add-ins

• Delay-loading the CLR in Office Add-ins

• VSTO Performance: Delay Loading and You (Stephen Peters)

• Performance Improvements Coming Soon to a Service Pack Near You (Stephen Peters)

• VSTO Performance: Ribbon Reflection (Stephen Peters)

• Publishing Office Solutions by Using Windows Installer

Miscellaneous

• What's new for Office 2013 developers