Changes to custom properties in Outlook

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.

Set myProp = myItem.UserProperties.Add("MyPropName", olText)

You can also use the CDO object library ("MAPI.Session") to add custom fields. For more information, visit the following MSDN Web site:

http://msdn2.microsoft.com/en-us/library/ms527518.aspx For C++ developers, Extended MAPI can used to add named properties. For more information, visit the following MSDN Web site:

http://msdn2.microsoft.com/en-us/library/ms529684.aspx

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.
 
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>

<Property Name>

"Kind" (dword)

"ID" (dword)
"Type" (dword) 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:

Name: “MyStringFieldName1”

Type: PT_LONG

[HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Outlook\AllowedNamedProps\{00020329-0000-0000-C000-000000000046}\MyStringFieldName1] "Type"=dword:00000003
The following is an example of how to set a named-by-ID property:

ID: 0x0330

Type: PT_LONG

[HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Outlook\AllowedNamedProps\{00020329-0000-0000-C000-000000000046}\MyMAPIProp1] "Kind"=dword:00000000 "ID"=dword:00000330 "Type"=dword:00000003


For these two examples, the registry appears similar to the following in Registry Editor:


{00020329-0000-0000-C000-000000000046}
 

MyStringFieldName1

Type = 3
MyStringFieldName2

Type = 3
{00020329-0000-0000-C000-000000000046}

MyMAPIProp1

Kind = 0
ID = 330

Type = 3
MyMAPIProp2

Kind = 0
ID = 331
Type = 3

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.