Changes to custom properties in Outlook

This article does the following:

• Provides an overview of custom properties.
• Explains how the behavior of custom properties has been changed in Outlook 2003 SP2 and in later versions of Outlook.
• Discusses some best practices to create new properties and some methods that we do not recommend.

About custom properties

Custom properties are used by e-mail programs, such as Outlook, to add more information to a message. Typically, this additional information is used by an e-mail program for a specific purpose. However, there are other ways that custom properties can be used. For example, custom properties can be added to messages or items if you use Outlook custom forms and those forms contain custom fields. Custom properties are frequently used to add more information for tracking purposes. Custom properties are also used to add data that a user does not have to see. A custom solution can also add custom properties to regular items. A custom solution programmatically adds custom properties to a message or item without requiring a custom form.

Custom properties can be persisted in the .msg file format and the .oft file format in Outlook. Additionally, custom properties can be persisted to e-mail messages that are sent over the Internet if the sender uses the Send using Outlook Rich Text Format option. This option encapsulates the MAPI section of the message in Transport Neutral Encapsulation Format (TNEF), and then the TNEF is decoded when the message is received.

A sender can send an e-mail that has custom properties in the following scenarios:

• A one-off custom form is sent. In one-off forms, the form is embedded in the message. The form is not published elsewhere. For more information about one-off forms, click the following article number to view the article in the Microsoft Knowledge Base:
  290657  (http://support.microsoft.com/kb/290657/ ) Description of form definitions and one-off forms in Outlook 2002
• A published custom form is sent. In this case, the custom form is not sent because the form is not embedded in the message. However, any custom properties that were used on the form are still included in the message.

Note There are many ways to refer to custom properties, depending on the context in which the custom properties are used. In the Outlook user interface, such as in the Field Chooser, custom properties are referred to as user-defined fields or as custom fields. In the Outlook object library, custom properties can be referred to as user properties or as user-defined properties after the UserProperties collection. In MAPI, custom fields are referred to as named properties. MAPI provides a facility to do the following:

• Assign names to properties
• Map the names to unique identifiers
• Make the mapping persistent

For more information about how named properties are implemented in MAPI, visit the following MSDN Web site: Note In an Exchange environment, the term "store" as used in this article refers to a whole mailbox store (database). The term does not refer to an individual user's mailbox store. There may be one or more Exchange mailbox databases in an organization.

Behavior changes in Outlook

The implementation of MAPI in Outlook has been changed to control how custom properties can be created. To guarantee consistent use of custom properties, custom properties must already be used in the organization or on the Outlook client. As soon as custom properties are being used or are registered, the custom properties can be freely transmitted to other Outlook clients or to servers that are running Exchange Server. The custom properties can also be sent over the Internet.

E-mail messages are typically sent in MIME format over the Internet. When Outlook receives an Internet e-mail message, the message is converted into a MAPI representation. The following are examples of Internet e-mail protocols:

• POP
• IMAP
• HTTP (Hotmail)

By default, Outlook no longer enables Internet mail to create new custom properties. Only properties that are already created in the default mail delivery store are preserved for incoming e-mail messages. This change mostly affects messages that are sent in encapsulated TNEF (Winmail.dat), where the sender has used the Send using Outlook Rich Text Format option. However, Internet messages that contain X-message header properties are also affected.

Note Messages that contain custom properties that are sent in an Exchange organization are not affected by these changes.

Custom properties can also be saved in .msg files and in .oft files. If a user opens a .msg file that has custom properties, those custom properties are not saved to the default store when the message is saved, forwarded, and so on. Typically, .oft files are used to back up Outlook custom forms. With .oft files, the new behavior applies to all kinds of items. The custom form will not open. Instead, the message will appear in the default form for that particular item type.

In summary, this change in design can cause two things to occur:

• Outlook ignores non-existing custom properties. If a custom property does not exist in the delivery store, the property will not be created, and its value will be lost. If the custom property already exists in the delivery store, its value is persisted. This change applies to the following:
  • Internet e-mail messages that have TNEF and their embedded messages.
  • S/MIME messages.
  • .msg files when you drop the .msg file into an Outlook item window to add the file to another item. This change also applies to .msg files when you drop the .msg file into the main Outlook window to add the file to a folder or in the Microsoft Word window when you use Word as the e-mail editor.
  • .msg files that a user double-clicks or right-clicks to open.
• Outlook ignores the one-off form definition. If a one-off form specifies a custom property and that custom property does not exist in the delivery store, the one-off form is not rendered. Instead, the user will see the default form for that particular item type. This change applies to Internet e-mail messages that contain a one-off form definition that is encapsulated in TNEF. This change also applies to .oft files that a user double-clicks or right-clicks to open.

Best practices and other ways to create new properties

There are a variety of ways that you can design and develop custom solutions. Some of these approaches are considered best practices. Other approaches may also work, but we do not recommend those approaches for one or more reasons.

Best practice: Add custom fields programmatically

Various APIs can be used to programmatically add custom fields to items. To do this, use the UserProperties.Add method in the Outlook object library ("Outlook.Application"). The following code illustrates this best practice.You can also use the CDO object library ("MAPI.Session") to add custom fields. For more information, visit the following MSDN Web site: For C++ developers, Extended MAPI can used to add named properties. For more information, visit the following MSDN Web site:

Best practice: Use published custom forms that contain custom fields

Outlook largely trusts published custom forms. However, Outlook does not trust unpublished forms or one-off forms. This includes .oft files. Therefore, when you design a custom form solution, we strongly recommend that you publish the custom form. You should design the form so that the form does not become a one-off form. As long as a form is published, the form will not be affected by the change in Outlook.
For more information about one-off forms and how one-off forms can be unintentionally created, click the following article number to view the article in the Microsoft Knowledge Base:
When you publish an .oft file to a different store, the default store lets you create properties in that store. Additionally, when you create a custom form that has custom properties and you publish it to the appropriate forms library or folder, the custom properties are created in the affected stores.

Best practice: Programmatically deploying custom forms

If you are developing an Outlook custom form that will be used by others, there are few approaches you can use. The approach that you use depends on several factors. These factors include the type of form, who will use the form, where the form will be used, and so on. Typically, if a custom form will be used by many people, we recommend that you publish the form in the Organizational Forms Library. However, if that is not possible, you may want to publish the form in a shared folder or in the Personal Forms Library of some users. You can programmatically install a custom form by using the CreateItemFromTemplate method in the Outlook object library. You use the CreateItemFromTemplate method to open an .oft file, and then publish the form by using the PublishForm method. In this case, an .oft file is not affected by the custom properties changes.

Not recommended: Deploy or send .oft files for users to open

You can save Outlook custom forms as .oft files. These forms can contain custom fields, user-interface changes, and custom Microsoft Visual Basic Scripting Edition (VBScript) code to add functionality to the form. Although Outlook already contains features that prevent the VBScript code in .oft files from running, Outlook now also restricts the use of .oft files. If an .oft file contains custom properties and the user has not previously used those custom properties, the custom properties are not in the user's default store. Outlook will not render the custom form when the user double-clicks the file. However, to have Outlook open a custom form that is stored as an .oft file, click File, click New, and then click Choose Form. You can then change the location to User Templates in File System, and then click Browse to open the .oft file. The form will open, and you can save the custom properties to the default store.

Not recommended: Use the AllowNamedProps registry key

Some organizations may have valid reasons to have certain custom properties available throughout the organization. If multiple stores are used, you may want to make sure that a set of custom properties can be added to all stores. Therefore, Outlook 2003 SP2 and later versions support client-side registry keys that specify which custom properties can be created. To specify which custom properties should be enabled, custom properties are defined under the following registry key: HKEY_CURRENT_USER\Software\Microsoft\Office\<version>\Outlook\AllowedNamedProps\

Note In this registry key, <version> is a placeholder for the version of Outlook that you are using. For Outlook 2003, the version number is 11.0. For Outlook 2007, the version number is 12.0. The version number will increase in later versions of Outlook.

The overall registry key structure for an entry in the registry is:

<GUID> The following placeholders are used in the registry key structure:

• <GUID>: Contains the GUID that specifies the property set. Outlook custom fields, or properties, that you use on an Outlook custom form all have the GUID {00020329-0000-0000-C000-000000000046}. In MAPI, the GUID is referred to as PS_PULIC_STRINGS. However, custom MAPI programs may have their own GUIDs for custom properties.
• <Property Name>: Specifies the name of the property. If the property is named by a string, the <Property Name> is the actual string name of the property. If the property is named by an ID, the value of this registry key is ignored. However, you must give the property a unique name so that the property can be stored in the registry. If the Kind key is set to 1 or is <> 0, the registry key name will determine the name of the property. If the Kind key is not equal to 1, this registry key name will be ignored.
• "Kind" (dword): Specifies whether the property is named by an ID or by a string. If the value is 0, the property will be named by an ID. The name is a numeric value that is specified by an ID. If the value is 1, the property will be named by a string. This setting is the default setting when “Kind” is not present.
• "ID" (dword): Contains the ID name of a property that is named by an ID. This information is required if the Kind key is set to 0. If the Kind key is set to 1, this information is ignored.
• "Type" (dword): Specifies the type of property.

This registry key is required, but the registry key is not currently used. The following table lists the possible values of this registry key based on the MAPI type.The following is an example of how to set a named-by-string property:The following is an example of how to set a named-by-ID property:
For these two examples, the registry appears similar to the following in Registry Editor:

{00020329-0000-0000-C000-000000000046}

{00020329-0000-0000-C000-000000000046}

Not recommended: Re-enable the ability to create properties

Three registry keys can be deployed to client computers to disable the blocking of custom properties and revert Outlook to its previous behavior. These registry keys are supported by group policies. The following registry keys can revert Outlook 2003 to its previous behavior:

Note The following registry keys do not revert Outlook 2007 to its previous behavior.

• AllowTNEFtoCreateProps (HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Outlook\Options\Mail] "AllowTNEFtoCreateProps"=dword:00000000): If the value is 0, TNEF/MIME cannot create new non-Outlook custom properties. This value is the default value. If the value is 1, TNEF/MIME can create new non-Outlook custom properties.
• AllowMSGFilestoCreateProps: If the value is 0, .msg files and .oft files cannot create new non-Outlook custom properties. This value is the default value. If the value is 1, .msg files and .oft files can create new non-Outlook custom properties.
• DisallowTNEFPreservation: To ease migration to this new behavior, Outlook preserves the original TNEF when custom properties are not created. The original TNEF is saved in a binary stream on the item that is saved. Outlook uses the following property tag to save the stream:
  PR_TNEF_UNPROCESSED_PROPS PROG_TAG(PT_BINARY, 0x0e9C).
  The HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Outlook\Options\Mail] "DisallowTNEFPreservation "=dword:00000000 registry setting controls whether Outlook creates the PR_TNEF_UNPROCESSED_PROPS property.
  
  Note The PR_TNEF_UNPROCESSED_PROPS property is removed from a message when you embed a message into another message as an attachment. The PR_TNEF_UNPROCESSED_PROPS property is also removed when you forward a message or reply to a message.