The support guidelines for client-side messaging development

This article describes what is supported and what is not supported when you develop custom solutions that integrate with Microsoft-based messaging products or Microsoft technologies. This article also contains most of the key information to be aware of when you develop with Microsoft products and Microsoft technologies. However, this article does not cover all scenarios. Contact Microsoft Customer Support Services if you have any questions about whether a specific solution is supported.

This article also discusses specific technologies and specific scenarios to provide guidance to developers.

The term "supported" is used to describe whether Microsoft Customer Support Services or Microsoft Services can help you when you try to achieve something in a specific way. Typically, the term is also used in the context of whether a Microsoft product group will potentially fix an issue for a given scenario.

Because of the large matrix of products, technologies, and versions that require testing, we cannot say that all scenarios have been designed or tested. Therefore, we encourage you to use the following best practices when you design custom solutions:

• Only use APIs that are documented by Microsoft. This avoids the increased risk that your solution will not function together with a newer version of a product or together with a service pack for a product. For example, you can use the Microsoft Win32 API to manipulate Microsoft Office Outlook windows. However, the Win32 API is not supported. Some solutions may be supported within the context of the specific API that you use. However, these solutions typically are not supported within the context of an Office application and when you create a custom solution by using that application. An exception would be a scenario that is documented by Microsoft.
• Avoid mixing newer technologies and older technologies if you can do this. Mixing newer technologies and older technologies increases the possibility that the scenario was not tested and that the scenario is not supported.
• When you work with Office applications, develop the solution by using the oldest version of Office that runs the solution.

Integrating with Outlook properties

Outlook, Microsoft Exchange Server, and other Microsoft products store data in MAPI stores, such as personal folders (.pst) files, Exchange mailbox stores, or Exchange public folder stores. Although some of this data is visible, various other data is not visible and is stored for other reasons.

In some cases, there is a one-to-one correspondence between what you see in Outlook and what is stored in the underlying MAPI database. The Subject box of an e-mail message is an example of this because this box corresponds to the PR_SUBJECT MAPI property. In this case, this property predates Outlook because this property was used by previous Microsoft e-mail clients. Other properties also have a one-to-one correspondence but are specific to Outlook. For example, a contact’s Web site address is stored in a specific MAPI named property.

Note For more information about named properties in Outlook, see the "MAPI-specific information for named properties" section.

In some cases, Outlook may use multiple MAPI properties to store information for a specific purpose, or Outlook may store multiple pieces of information in one property. In both of these scenarios, frequently there is no documentation that explains how these properties are implemented or how they function.

Programmatically changing the underlying properties involves some risk. The main areas include the following:

• Outlook may experience unexpected behavior or stop responding when some properties are changed.
• Problems may occur when various APIs are used to dynamically change some Outlook properties while Outlook is running.
• Different versions of Outlook may connect to the same MAPI stores. Therefore, there may be added complexity because different versions of Outlook may interact with related properties in different ways.

Therefore, many MAPI properties that are used by Outlook are not documented at the MAPI level. The MAPI schema that is used is complex and may change with later versions MAPI.

Therefore, we recommend that you avoid accessing this low-level data directly and that you use a high-level API instead, such as the Outlook object library. Because of these factors, Microsoft generally does not support explaining how or why the underlying properties are implemented.

It is also important to differentiate between reading properties and writing properties. Programmatically reading MAPI properties by using APIs such as Extended MAPI, WebDAV, or the PropertyAccessor object in the Microsoft Office Outlook 2007 object model is supported. However, writing to those properties is not supported because of the potential for data corruption issues or for other problems that other MAPI clients may have when they use the modified data.

MAPI-specific information for named properties

MAPI provides a facility for assigning names to certain properties, for mapping these names to unique identifiers, and for making this mapping persistent. Outlook writes many Outlook-specific fields into these named properties that use identifiers in the 8000-FFFE range. Typically, the Microsoft Outlook object model is the only supported method of changing these named properties. Typically, changing these properties by using MAPI or by using Collaboration Data Objects (CDO) is not supported.

Named properties are identified by a name and by a GUID for a property set. The name can be a number or a string. These properties are manipulated by using the IMAPIProp::GetIDsFromNames function and the IMAPIProp::GetNamesFromIDs function. The GUID and the name are passed to the GetIDsFromNames function to obtain a property ID that is valid for the current MAPI session. Because this property ID can vary from computer to computer, the only consistent way to access a named property is to know its property set and its name.

Typically, named properties are used by Outlook clients as a way to add extra information to a message that is only used by that client. Therefore, most of the named properties that are used by Outlook clients are not documented. The only supported way to obtain these properties is through the Outlook object model.

Common named properties that are used by Outlook

The following table describes the common named properties that are used by Outlook. In addition to the properties that are native to MAPI, user-defined fields on customized Outlook forms are supported through MAPI, through CDO, through WebDAV, and through the Outlook object model. These fields use the PS_PUBLIC_STRINGS property as the property set identifier and the name of the field as the property name. For more information about supportability scenarios for WebDAV-based data and for MAPI-based data, click the following article number to view the article in the Microsoft Knowledge Base: The Outlook Integration API provides additional documentation for integrating with Outlook in specific scenarios. To view this documentation, visit the following Microsoft Web site: Additionally, the following information is documented for Outlook 2007 and is scheduled to be included in the Outlook Integration API at a later date. For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base: For more information, visit the following Microsoft Web sites:

Microsoft Office Outlook 2003 Service Pack 1 (SP1) or later versions

For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base: For more information, visit the following Microsoft Web sites:

APIs that are supported in managed code

MAPI was originally designed and originally developed in the late 1980s. Therefore, MAPI predates managed code in the Microsoft .NET Framework. We do not provide managed wrappers for MAPI, and we discourage you from using third-party wrappers. This is because solutions may seem to work in a test environment, but issues that are related to memory management may occur when an application is deployed in a production environment and is exposed to real-world scalability scenarios.

The following table summarizes the support policy for Outlook APIs in the .NET Framework environment. For more information about the support policies for other messaging APIs in managed code, click the following article number to view the article in the Microsoft Knowledge Base:

The .NET Framework user controls

The .NET Framework user controls are not supported in Outlook 2003, in earlier versions of Outlook, or in Outlook 2007 custom form regions. For more information about support for these controls, click the following article number to view the article in the Microsoft Knowledge Base:

Custom forms and HTTP scenarios for Outlook 2003 and for earlier versions of Outlook

In Outlook, custom Outlook forms are not supported for use with HTTP-based mail services such as Microsoft Hotmail. Outlook does not prevent you from using custom form features if you are using an HTTP-based mail service. However, some features do not work correctly. The features do not work correctly because HTTP-based mail messages are stored in a read-only state on the server. Therefore, we recommend that you do not use custom Outlook forms if you are using an HTTP-based mail service.

Microsoft Visual Basic 6.0 MAPI controls

Visual Basic 6.0 MAPI controls are based on Simple MAPI and are no longer tested or supported starting in Outlook 2007. We encourage you to use a newer API for e-mail solutions.

Note The standard support for Visual Basic 6.0 has expired.

Common Messaging Calls

Common Messaging Calls (CMC) is not supported after the release of the Outlook e-mail security update in June 2000.

Dynamic Data Exchange (DDE)

Unlike other Office applications, Outlook does not support Dynamic Data Exchange (DDE) as a way to programmatically communicate with Outlook.

Microsoft Outlook Express (Microsoft Windows XP)

For a long time, the only supported API for Outlook Express was Simple MAPI. Simple MAPI is a set of functions and the related data structures that you can use to add messaging functionality to custom applications. The Simple MAPI functions are available in versions for C, for C++, and for Visual Basic.

The documentation for Simple MAPI is provided in the Microsoft Exchange SDK. To view this documentation, visit the following Microsoft Web site: Outlook Express uses Windows Address Book (WAB). For more information about Windows Address Book, visit the following Microsoft Web site:

Windows Mail in Windows Vista

In Windows Vista, Windows Mail is the replacement for Outlook Express. For developer documentation, visit the following Microsoft Web site: APIs that are available for Outlook Express 6.0 are also included in this documentation.

Windows Live APIs and SDKs

For more information about the APIs that are related to e-mail and about the support options for Windows Live, visit the following Microsoft Web site:Microsoft Customer Support currently does not provide support for these APIs.

Support for creating "Adjacent Windows" in Outlook

Microsoft provides a code sample and corresponding documentation for using Windows APIs to add user interface panes into Outlook 2003 and later versions of Outlook. This documentation is located at the following Microsoft web site:

http://code.msdn.microsoft.com/OlAdjacentWindows

Microsoft understands that customers are already using the Windows API approach to integrate with Outlook, and the Outlook Social Connector also takes advantage of this kind of integration. Documentation for Outlook adjacent windows provides "best practice" guidelines to help avoid conflicts with other programs by using this approach, including the Outlook Social Connector.

This sample code and the corresponding documentation are not supported by Microsoft. The Outlook product group does not consider this overall approach to be part of Outlook’s supported architecture in terms of developing custom solutions with Outlook. Instead, we recommend and support using other approaches that are more fully designed, tested, and documented to work with Outlook. Depending on the version of Outlook, these other approaches include Outlook custom forms, form regions, folder home pages, custom task panes, and the Outlook Social Connector (OSC) extensibility architecture. One key advantage of using these supported approaches is that developers will have a much better chance that they will not encounter compatibility issues when a newer version or service pack of Outlook is released.

If you encounter issues when you use the information that is provided in the sample, you can post comments on the MSDN Code Gallery page for this download. However, Microsoft cannot guarantee that support will be provided for your issue.

Support for Drag and Drop Integration

As a developer, you may wish to develop a custom solution that allows Outlook items to be dragged and dropped onto a Visual Studio form or other container that supports a drop operation. However, from a custom solution perspective, Outlook was not designed to support these types of scenarios and no Microsoft testing was done in this area. Therefore, Microsoft does not recommend or support developing a custom solution in this manner. Instead, Microsoft recommends that you use the Selection object available beginning in the Outlook 2000 object model. You can then implement a custom CommandBar button (Outlook 2000-2007) or custom Ribbon button (Outlook 2010) to handle the processing of those selected items.

While unsupported, there is additional information located on the following blog:

http://blogs.msdn.com/b/webdav_101/archive/2008/04/01/drag-and-drop-with-outlook.aspx

For more information about named properties, visit the following Microsoft Web site: