Export (0) Print
Expand All

Selecting an API or Technology for Developing Outlook Solutions

Office 2010

Summary: This article describes each API and technology that extends Microsoft Outlook, and evaluates them to help you select the appropriate API or technology for solution development.

Microsoft supports various APIs and technologies that extend Microsoft Outlook—the Outlook object model and the corresponding Outlook Primary Interop Assembly (PIA), Messaging API (MAPI), auxiliary APIs, Outlook Social Connector (OSC) provider extensibility, and Microsoft Office Mobile Service (OMS). The object model, PIA, MAPI, and auxiliary APIs are used by most Outlook solutions. OSC provider extensibility and the OMS serve more specific purposes—respectively, integrating social network data with Outlook, and integrating mobile devices with the mobile capabilities of Outlook and Microsoft SharePoint. Because the majority of existing Outlook solutions use the object model, PIA, and MAPI, this article explains the selection criteria for these APIs. Note that solutions do not necessarily have to use one API exclusively. For example, a COM add-in written in C++ can use the object model, MAPI, and auxiliary APIs in the same solution.

To get the most benefit from this article, you should be familiar with Outlook at the user level and have general software development knowledge. However, you do not need to have a comprehensive understanding of the features that these APIs or technologies support. The article helps answer the following questions:

  • If you have only an idea about the goals of your solution, the target market, and available resources, what other criteria should you consider to select an API?

  • If your solution has to run on earlier versions of Outlook, including Outlook 2003, how does that affect your API choice?

  • If your solution has to iterate through Outlook folders that contain thousands of items, and you need to be able to modify those items, which API would work best?

  • If your solution relies heavily on Outlook business logic and interacts with other Office applications, is the Outlook object model the best choice?

  • What do the object model and MAPI allow you to extend in Outlook?

  • If you can use either the object model or MAPI to achieve your task, how should you decide which API to use?

The article describes selection criteria in the following sections:

This section describes criteria that you can use to compare the object model, PIA, and MAPI to determine which better meets your needs. Different criteria can be more or less important, depending on your projects and available resources.

Objective Evaluation Criteria for the Object Model and PIA

Solutions that run on the client computer can use the Outlook object model or PIA to programmatically access Outlook items, such as contacts, messages, calendar items, meeting requests, and tasks. Unlike MAPI, the Outlook object model and PIA can provide event notifications for Outlook user-interface changes, such as changing the current folder or displaying an Outlook inspector.

Note Note

For a solution to access data that is stored in a Microsoft Exchange mailbox or a personal folders (.pst) file, Outlook must be installed and configured on the client computer on which the application is running.

The Outlook object model and PIA support the same functionality to extend Outlook. The PIA defines managed interfaces that map to the COM-based object model and that a managed solution can interact with. In the remaining discussions in this section, most of the functional, security, and deployment criteria apply to the object model and the PIA in the same way. For more information about how the PIA facilitates interoperability between COM and the .NET Framework, see Introduction to Interoperability Between COM and .NET and Architecture of the Outlook PIA.

The tables in this section define evaluation criteria in the following categories:

  • Functional criteria—Describe the things you can and cannot do with the technology.

  • Development criteria—Describe the development tools or information you need to use the technology

  • Security criteria—Describe the security and permissions issues related to the technology.

  • Deployment criteria—Describe the recommended deployment and distribution methods for the technology.

The following tables show evaluation criteria for the Outlook object model and PIA.

Functional Criteria

Criteria

Outlook object model or PIA

Application domain

Add-ins or standalone applications that use the Outlook object model or PIA typically handle user-specific messages, customize the Outlook user interface, or create custom item types for specialized solutions such as customer relationship management (CRM) solutions that integrate with Outlook. The Outlook object model or PIA is sometimes used for message processing in an informal workflow process, especially where application development on the Microsoft Exchange Server is not permitted. Unlike browser-based clients, cached-mode operation allows Outlook solutions to work when the user is offline or disconnected from the corporate network.

Major objects

The top-level object in the Outlook object model and PIA is the Outlook Application object. Explorers, Conversation, Inspectors, Views, NavigationPane, SolutionsModule, FormRegion, and related objects represent elements of the Outlook user interface. The NameSpace, Stores, Folders, Accounts, AccountSelector, AddressEntries, ExchangeUser, and related objects support extending Outlook sessions, profiles, user accounts, message stores, and folders. At the data level, a number of item-level objects, such as MailItem, AppointmentItem, ContactItem, and TaskItem, represent the built-in Outlook item types. The PropertyAccessor, Table, Search, ItemProperties, UserDefinedProperties, Attachments, Categories, Recipients, RecurrencePattern, Reminders, Rules, and related objects support customizing and manipulating item-level objects.

Data-access model

The Outlook object model and PIA represent all data as a hierarchical set of objects and collections.

Threading models

All calls to the Outlook object model and PIA execute on Outlook’s main foreground thread. The only threading model that the Outlook object model supports is single-threaded apartment (STA). Calling the Outlook object model or PIA from a background thread is not supported and can lead to errors and unexpected results in your solution.

Application architectures

Typically, COM add-ins and other Microsoft Office applications use the Outlook object model to extend Outlook. Managed solutions can use the Outlook PIA and the COM interoperability layer of Microsoft Visual Studio and the .NET Framework to access the Outlook object model. Visual Studio provides templates and additional class libraries and manifests to facilitate Office document and application customizations. For more information about using Visual Studio to develop managed add-ins for Outlook, see Architecture of Application-Level Add-Ins and Outlook Solutions. The Outlook object model also supports Visual Basic for Applications (VBA) macros and Windows Scripting Host (WSH), but does not support Windows Service applications.

Remote usage

The Outlook object model and PIA can be used only on a computer on which Outlook is installed. The Outlook object model can be used to access information stored in Exchange that is available in the Outlook application.

Transactions

The Outlook object model and PIA do not support transactions.

Availability

The Outlook object model is currently available in all versions of Outlook. The PIA is available in versions of Outlook since Outlook 2003. There have been extensions and improvements with each new version of Outlook.

Development Criteria

Criteria

Outlook object model or PIA

Languages and tools

You can implement Outlook object model applications by using any COM or automation-compatible language, such as Visual Basic or C#, as well as non-COM languages, such as native C or C++. Microsoft Office development tools in Microsoft Visual Studio 2010 are the preferred tools for development of managed add-ins for Outlook 2010 and Outlook 2007. Microsoft Visual Studio 2005 Tools for the Microsoft Office System are the preferred tools for Outlook 2003. You can also use Office development tools in Visual Studio 2010 to create solutions for 32-bit and 64-bit versions of Outlook. When you build a solution in Office development tools in Visual Studio 2010 or Microsoft Visual Studio Tools for the Microsoft Office System, specifying the Any CPU option for the target platform results in managed solutions that work for both 32-bit and 64-bit versions of Outlook 2010.

Managed implementation

The Outlook PIA enables the Outlook object model to be used in a managed-code environment, which is supported by a rich set of class libraries and support technologies that address many limitations of VBA and COM add-ins. The PIA is a COM wrapper that acts as a bridge between the managed and COM environments. For more information, see Why Use the Outlook PIA.

Scriptable

The Outlook object model can be used in scripts.

Test and debug tools

No special debugging tools are needed to use the Outlook object model or PIA. On the other hand, you can use Visual Studio to provide an integrated development environment that facilitates application testing and debugging.

Expert availability

Developers who can successfully develop applications by using the Outlook object model or PIA are relatively easy to find. The Outlook object model and PIA are intended for add-ins created by using widely available development tools, such as Visual Studio. These tools provide design-time environments that simplify the development process.

Available information

Information about programming by using the Outlook object model is available in both Microsoft and third-party resources. For more information about the Outlook object model, see the Outlook 2010 Developer Reference. For more information about the Outlook PIA, see the Outlook 2010 Primary Interop Assembly Reference. For examples of managed Outlook solutions developed by using Office development tools in Visual Studio, see Outlook Solutions with Visual Studio.

Developer and deployment licensing

Refer to your Exchange and Microsoft Developer Network (MSDN) subscription licensing agreements to determine whether additional licenses are required for Outlook and Outlook object model use in your applications.

Security Criteria

Criteria

Outlook object model or PIA

Design-time permissions

No special permissions are required to develop applications by using the Outlook object model or PIA.

Setup permissions

No special permissions are required to install applications that use the Outlook object model or PIA. However, local administrator rights are required to install Office and Outlook.

Run-time permissions

No special permissions are required to run applications that use the Outlook object model or PIA.

Built-in security features

The Outlook object model and PIA communicate with Exchange by using MAPI and with Active Directory by using Active Directory Service Interfaces (ADSI). The current security context of the user who is running the application is used to determine what resources that code can access. By default, add-ins are trusted for full access to all objects, properties, and methods in the Outlook object model or PIA. IT administrators can exercise control over which add-ins and objects can access the Outlook object model or PIA. The Outlook object model and PIA prevent code that is run outside the Outlook process from accessing secure objects and methods.

Security monitoring features

The Outlook object model and PIA provide no additional security monitoring features.

Deployment Criteria

Criteria

Outlook object model or PIA

Server platform requirements

The Outlook object model and PIA are client-side technologies.

Client platform requirements

Applications that use the Outlook object model or PIA to access Exchange data require that Outlook be installed on the local computer.

Deployment methods

Applications that use the Outlook object model or PIA are distributed by using standard application installation software.

Deployment notes

Because Outlook should not be installed on the Exchange Server, applications that use the Outlook object model or PIA cannot be run on the Exchange Server.

Objective Evaluation Criteria for MAPI

You can use MAPI to access items and folders in public and private stores, as well as to access the properties stored with each item. All versions of Outlook use MAPI. You can create clients that use MAPI, and can create MAPI servers and MAPI forms handlers, as well. The information in this section applies only to MAPI client applications.

Note Note

MAPI is a mature mechanism used to access information in Exchange or in a personal folders (.pst) file, and MAPI provides some capabilities that are not available in any other API. However, MAPI does not work well outside an intranet, maintains an open connection for the duration of the MAPI session, and can be difficult to learn. MAPI does not enforce Outlook business logic, so you must take special care to ensure that Outlook business logic is maintained.

The following tables show evaluation criteria for MAPI.

Functional Criteria

Criteria

MAPI

Application domain

Client applications that use MAPI access a user mailbox or public folder information stored in Exchange, and user directory information stored in Active Directory. Client applications that use MAPI are typically email clients, such as Outlook, and applications that require complex email processing.

Major objects

MAPI objects are all obtained through the IMAPISession : IUnknown interface. The session object provides the client access to objects for working with MAPI profiles, status, message service provider administration, message store tables, and address books. The message store table contains objects for the message store, folders, messages, attachments, and recipients. The address book tables contain objects for messaging users and distribution lists.

Data-access model

MAPI represents messages and users as a hierarchical set of objects.

Threading models

There are no specific threading prohibitions. However, applications that use free-threading should avoid sharing MAPI objects among threads due to the high costs of marshaling the object. MAPI and MAPI service providers use free-threading.

Application architectures

MAPI client applications are typically Windows Forms–based client applications. However, you can use MAPI to write N-tier applications.

Remote usage

MAPI uses remote procedure calls (RPCs) to communicate with the Exchange Server. Typically RPCs are intentionally blocked from passing through Internet firewalls.

Transactions

MAPI does not support transactions.

Availability

A MAPI stub currently ships with all versions of Windows. Office installs its own MAPI subsystem when it installs Outlook. No changes to MAPI are anticipated at this time.

Development Criteria

Criteria

MAPI

Languages and tools

You can directly access MAPI by using C or C++. Other languages that can access the C/C++ calling convention may be able to access MAPI. The use of managed languages, such as Visual Basic or C#, is not supported. You must compile separate MAPI solutions for 32-bit and 64-bit versions of Outlook.

Managed implementation

MAPI is an unmanaged component. Use of MAPI is not supported under the COM interoperability layer of Visual Studio and the .NET Framework. For more information about MAPI support for managed components, see Knowledge Base article 266353: The support guidelines for client-side messaging development.

Scriptable

MAPI cannot be directly used in scripts.

Test and debug Tools

No special debugging tools are needed to debug applications that use MAPI. On the other hand, you can use MFCMAPI. MFCMAPI uses MAPI to provide access to MAPI stores through a graphical user interface, and facilitates investigation of issues when you extend Outlook by using MAPI.

Expert availability

Expert MAPI programmers can be difficult to find, and learning the technology can take a significant amount of time. In addition to the Microsoft communities, there are only a small number of high-quality third-party websites that provide helpful MAPI development information.

Available information

Both Microsoft and third-party books that describe MAPI programming are available.

Developer and deployment licensing

No special licensing is required for developing applications that use MAPI.

Security Criteria

Criteria

MAPI

Design-time permissions

The developer must have permissions to access the data in the Exchange store. Exchange stores user and distribution list information in Active Directory, so developers who create MAPI client applications that access that information must have the ability to retrieve and set that information.

Setup permissions

Setting up MAPI-based applications typically requires the user to be a local administrator, or to have rights to install software.

Run-time permissions

Running a MAPI-based application usually requires only that the user has sufficient permissions to access the data on an Exchange store or personal folders (.pst) file.

Built-in security features

MAPI profiles can be password protected on most platforms.

Deployment Criteria

Criteria

MAPI

Server platform requirements

The Exchange Server on which user data is stored for users of the MAPI client application must be properly configured to allow access by MAPI clients.

Client platform requirements

The client application installer should verify that the proper version of MAPI is available on the computer, and that it is properly configured by using the Mapisvc.inf file.

Deployment methods

Applications that use MAPI can be deployed to client computers by using standard software distribution technologies.

Deployment notes

The installer should verify that the correct version of MAPI is available.

In general, use the object model or the PIA if your solution customizes the Outlook user interface or relies on Outlook’s business logic. Figure 1 shows the major baseline scenarios for which Outlook solutions use the object model or the PIA.

Note Note

For more information about the scenarios, click the boxes in the following figures.

Figure 1. Major baseline scenarios supported by the Outlook object model or PIA.

#OLSelectAPI_CustomizeTheOutlookInterface_htm Use Outlook items #OLSelectAPI_ItemPropFieldsForms_htm

#OLSelectAPI_Events_htm #OLSelectAPI_AutomateOutlook_htm



In addition to the baseline scenarios, if your Outlook solution supports any of the scenarios shown in Figure 2, and your solution is intended to run on Outlook 2007 or Outlook 2010 but not earlier versions, you can use the object model or the PIA, as well. Figure 2 specifies the main objects or members you can use in the Outlook object model to extend each scenario (with the exception of the IDTExtensibility2 interface in the Visual Studio automation object model, and the IRibbonExtensibility interface in the Office object model, which you can integrate with the Outlook object model).

Figure 2. Additional scenarios supported by the object model or PIA for Outlook 2007 and Outlook 2010.

#OLSelectAPI_CustomizeTheOutlookInterface_htm #OLSelectAPI_CustomFormRegions_htm #OLSelectAPI_CustomizingProperties_htm

#OLSelectAPI_Enumerating_htm #OLSelectAPI_ItemsFlag_htm #OLSelectAPI_Sharing_htm

#OLSelectAPI_Attachments_htm #OLSelectAPI_Misc_htm #OLSelectAPI_Categories_htm

#OLSelectAPI_PrimaryAccount_htm #OLSelectAPI_AddressBook_htm #OLSelectAPI_StoringData_htm



If your Outlook solution is intended to run on Outlook 2010 and not earlier versions, you can choose to use the object model or the PIA to support the scenarios shown in Figure 3. Figure 3 specifies the main objects or members you can use in the Outlook object model to extend each scenario (with the exception of the IRibbonControl, IRibbonExtensibility, and IRibbonUI interfaces that are in the Office object model, which you can integrate with the Outlook object model).

Figure 3. More scenarios supported by the object model or PIA for Outlook 2010.

#OLSelectAPI_CustomizingUIOutlook2010_htm #OLSelectAPI_Conversations_htm #OLSelectAPI_ItemSelection_htm

#OLSelectAPI_AttachmentSelection_htm #OLSelectAPI_MultipleAccounts_htm Create a contact card for an address entry

#OLSelectAPI_Folders_htm



In general, you use MAPI to access data on a MAPI-based server such as the Microsoft Exchange server, and to do tasks such as the following:

  • Create a custom service provider such as an address book provider, transport provider, or store provider.

  • Create a sink process.

  • Create or manipulate a profile.

  • Run an application as a Windows NT service.

  • Run tasks on a background thread. For example, enumerating numerous items in a folder and modifying the items’ properties in a background thread can optimize performance.

For more information and code samples, see the Outlook 2010 MAPI Reference and MFCMAPI.

In addition, if your solution runs on a version of Outlook earlier than Outlook 2007, and scenarios such as the following apply to your solution, you should use MAPI to extend those scenarios.

  • Set and get built-in item-level properties that are not exposed in the object model.

  • Manage accounts, attachments, Exchange distribution lists, Exchange users, or stores.

  • Store private data for solutions.

  • Manage a message store for an account.

Since Outlook 2007, the object model has supported a range of features that, prior to Outlook 2007, developers had to resort to MAPI or other APIs such as Microsoft Collaboration Data Objects (CDO) 1.2.1 and Microsoft Exchange Client Extensions. So if any of the scenarios in the previous list applies to your solution, but your solution runs on Outlook 2007 or Outlook 2010, you can and should use the Outlook object model or PIA to support these scenarios. For more information about Outlook 2007 enhancements that unify Outlook development technologies, see What's New for Developers in Outlook 2007 (Part 1 of 2).

The Outlook auxiliary APIs can integrate with Outlook business logic or MAPI in some scenarios where the object model or MAPI does not provide a solution. Use the Outlook auxiliary APIs in the following scenarios:

  • Account management: Manage account information, manipulate accounts, provide notification on account changes, and protect accounts from spam.

  • Data degradation: Wrap an object in a preferred character format rather than exposing the object in its native format.

  • Rebasing calendars and time zone support: Rebase Outlook calendars to support daylight saving time.

  • Free/busy status: Provide free/busy information on calendars.

  • Contact pictures: Determine the display of a contact’s picture in Outlook.

  • Item currency: Determine whether an Outlook item has unsaved changes.

  • Categorizing an item: Categorize an Outlook item after sending the item.

For more information about the auxiliary APIs, see the Additional Resources—Auxiliary APIs section.

Outlook supports automation by using add-ins that run in the same foreground process as the Outlook process, and by standalone solutions that run in their own separate process outside of the Outlook process. Generally, use an add-in to interact with Outlook through the object model, MAPI, or an auxiliary API such as HrProcessConvActionForSentItem. Use an out-of-process solution only when it’s necessary (for example, when you are writing a MAPI client application that uses the Tzmovelib.dll file to rebase Outlook calendars for customers, or enumerating numerous items in a folder and modifying the items’ properties in a background thread to optimize performance).

Add-ins are the preferred solution to extend Outlook, because Outlook trusts only the Application object passed to the add-in during the OnConnection(Object, ext_ConnectMode, Object, Array) event of the add-in. You can avoid the display of security warnings of the Object Model Guard by deriving all objects, properties, and methods from this Application object. If the add-in creates a new instance of the Application object, Outlook does not trust that object, even if the add-in is on the list of trusted add-ins. Any objects, properties, and methods derived from such an Application object will not be trusted and the blocked properties and methods will invoke security warnings. For more information about the Outlook Object Model Guard, see Security Behavior of the Outlook Object Model.

Outlook supports automation by add-ins and standalone applications, written in managed or unmanaged languages. The more commonly used managed languages are C# and Visual Basic. C++ and Delphi tools are more common in unmanaged development. Available expertise is one consideration when choosing between managed and unmanaged development.

If your solution uses only the object model, you can consider developing a managed solution by using the PIA, Microsoft Office development tools in Microsoft Visual Studio 2010, or Microsoft Visual Studio Tools for Office. The Office development tools in Visual Studio provide project templates and visual designers that simplify creating custom user interfaces and developing Office solutions.

On the other hand, because MAPI was developed years before the Microsoft .NET Framework, and Microsoft does not provide managed wrappers for MAPI, Microsoft does not support using MAPI in managed code. If you are using MAPI, you must develop an unmanaged solution. For more information, see The support guidelines for client-side messaging development.

The Outlook Social Connector (OSC) provider extensibility and Office Mobile Service (OMS) support extending very specific scenarios in Outlook. The OSC provider extensibility supports developing a provider for a social network to allow users to view, in Outlook, friends and activities updates on that social network. OMS supports developing an OMS web service that integrates with the mobile capabilities of Outlook and SharePoint, and mobile devices.

The OSC in Outlook allows users to view, in the People Pane, an aggregation of emails, attachments, and meeting requests from a person in Outlook. In an organizational environment, users who collaborate on a Microsoft SharePoint site can see document updates and other site activities of this person on the SharePoint site. Outlook Social Connector provider extensibility supports developing a provider for the OSC to synchronize and surface social network updates in Outlook. Depending on the OSC providers that an Outlook user has installed, the user can see, in the People Pane, updates such as photos, status, and activities on the corresponding social networks. The OSC provider for Facebook is an example that uses the OSC provider extensibility. For more information about existing OSC providers such as LinkedIn, Myspace, and Windows Live Messenger, see Connect to your favorite social network using Outlook.

OMS supports the OMS clients in Outlook and SharePoint and development of OMS web services. Typically, mobile phone carriers or mobile message content service providers create and host OMS web services. Using Outlook as an OMS client, a user can compose and send a text or multimedia message. The OMS client sends the message to the appropriate OMS web service, which delivers the message to the text or multimedia message center of the mobile carrier. Using the OMS client in SharePoint, a user can receive alerts in the form of text messages. SharePoint alerts can notify users of any changes in a SharePoint document library or list.

In addition, within Outlook, users can manage mobile messaging accounts in parallel with email accounts, and store and manage text or multimedia message items very much like email message items. Outlook treats mobile phone numbers as a type of address, and users can add recipients to a mobile message by using AutoComplete, or by selecting names directly from the Outlook Address Book. Users can also send email messages, appointments, and meeting requests to mobile devices and other email addresses alike.

See the Additional Resources—Primary References, Resources, and Code Samples section for more information about using OSC provider extensibility or OMS.

To determine the best API or technology for your solution, you must first define the goals of your solution:

  • The versions of Outlook you intend your solution to support.

  • The high-priority scenarios of your solution and, in particular, whether these scenarios involve enumerating, filtering, or modifying folders that contain many Outlook items.

Try to match your scenarios with those outlined in the section Decision Factors for the Object Model or PIA. If the object model (or PIA) of your target Outlook versions supports your scenarios, and your solution does not manipulate folders with many items, you should implement your solution as an add-in, in either a managed or unmanaged language.

If the object model (or PIA) of a target Outlook version does not support some of your scenarios, verify whether the scenarios in the Decision Factors for MAPI or Decision Factors for the Auxiliary APIs section meet your needs. If MAPI meets your needs, you should implement your solution in unmanaged code. If an auxiliary API solves one of your scenarios, you can use managed or unmanaged code.

If your scenarios include showing social network information or updates in Outlook, you should use the OSC provider extensibility to create a COM-visible DLL. You can do this in either a managed or unmanaged language.

If your solution uses MAPI, you must implement it in unmanaged code, such as C++. Otherwise, the decision to use managed or unmanaged code to create the solution generally depends on your available resources and their expertise. As for deciding whether to implement the solution as an add-in or standalone application, choose an add-in to avoid the user constantly invoking the Outlook Object Model Guard, unless your scenario requires manipulation of folders that contain numerous items. In the latter scenario, implementing the solution to run as a background thread can optimize Outlook performance.

Once you have decided on the APIs or technology to use in your solution, you can refer to additional documentation and code samples in the Additional Resources—Primary References, Resources, and Code Samples section for more information.

The following resources provide more information about using the object model and PIA.

Accounts—Primary Exchange Account in Profile

Accounts—Multiple Accounts in Profile

Address Book and Exchange Users

Attachments

Attachments: Selection in Inspector

Automating Outlook

Categories

Conversations

Events

Items: Basic Properties, Fields, and Forms

Items: Customizing Properties

Items: Enumerating, Filtering, and Sorting

Items: Flag as Tasks

See the following task-related properties in some item objects such as the MailItem object:

Items: Selection in Explorer

Miscellaneous: Business Cards, Rules, and Views

Security

Sharing

Solutions: Solution-Specific Folders

Solutions: Storing Data

User Interface: Customizing Form Regions

User Interface: Customizing Since Outlook 2007

User Interface: Customizing in Outlook 2010

User Interface: Solutions-Specific Folders

Show:
© 2014 Microsoft