---

Outlook Extension Configuration File Format

While Outlook recognizes, loads, and runs extensions that conform to specifications for Microsoft Exchange Client extensions, you can improve an extension's performance and increase its functionality under Outlook by providing an Extension Configuration File (ECF). Using an ECF, Outlook knows ahead of time the contexts under which the extension needs to be loaded, what commands the extension contributes, the Outlook modules to which the extension applies, and so on. That way, Outlook can delay loading the extension until the extension is needed.

Creating an ECF for Your Extension

Without an ECF, an extension registers itself in the registry only. In the registry entry, the extension can specify a DLL, an entry point, a binary context map, a binary interface map, and a provider if applicable. An ECF, however, allows an extension to register itself with much more complete and detailed information than a registry entry.

Note If an ECF is loaded for an extension, registry entries for the extension are not used. Therefore, the ECF must contain a complete description of the extension.

The ECF provides information in a textual format, using the standard INI file format. There is only one ECF per extension, and only one extension per ECF. The file is laid as shown in the following table:

This section	Contains
[General]	General extension information, such as version, name, and path.
[Exchange Client Compatibility]	Keys specific to the Microsoft Exchange Client.
[Session]	Sub-context information for the session.
[Folder]	Sub-context information for the folder and registrations for command items for the explorer frame.
[Item]	Sub-context information for the item and registrations for command items for the inspector frame.
[Property Sheet]	Sub-context information for the property sheet.
[Advanced Criteria]	Sub-context information for the advanced criteria.
[Command]	Definitions of registrations for command items the extension is contributing.
[Context Name]	Developer-defined context information.

The format of each section of the ECF is described in the following sections.

[General]

This is a required section, and provides general information about the extension. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Display Name	Yes	String name of extension.
Description	No	String description.
GUID	Yes	Unique GUID identifying extension.
Path	Yes	String containing path to DLL hosting extension.
Entry Point	Yes	Integer of main entry point for extension within DLL.
Client Version	Yes	Version number of client the extension was written for, such as 4.0.
Service Provider	No	String containing the PR_SERVICE_NAME, not the display name, of the provider the extension is designed to work with.
Misc Flags	No	List of additional properties of the extension. Valid values are NoOptimizeInterfaceMap, NoInstallDropDown, NoInstallMainMenu, DelayIdleInstall, MoreContexts, RemoteAlso, Mail3, VerbIsReply, InstallCommandsEarly, OutlookChooseFolder, NoFormsRegistry, Disabled, NoUserEdit.

Valid values for the Misc Flags key are as follows:

[Exchange Client Compatibility]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Exchange Registry	No	1 or 0. If the there is also an entry for the extension in the registry, the value is 1.
Exchange Extension Key	No	String containing key under which the extension is registered in the registry.
Exchange Context Map	No	Binary string representing context map (same as registry entry).
Exchange Interface Map	No	Binary string representing interface map (same as registry entry).

[Application]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Events	No	List of events that apply to the extension for this context. Valid values are OnStartup, OnShutdown.

[Session]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Events	No	List of events that apply to the extension for this context. Valid values are OnDelivery, OnLogon, OnLogoff.

[Folder]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Folder Class	No	List of MAPI folder classes this section applies to, such as IPF.Note.
Folder Name	No	List of names of folders this section applies to, such as Calendar.
Views	No	List of views this section applies to. Valid values are Explorer, Remote, Viewer.
Events	No	List of events that apply to the extension for this context. Valid values are OnFolderChange, OnSelectionChange, OnViewChange, OnCommand, OnMenuDropDown, InstallCommands, AddPropSheetPages.
Contexts	No	List of additional sections defining folder context behavior. See "[context name]," later in this document.
Command Bars	No	List of command bars that apply to the extension, such as File, Edit, View, and so on. The extension is loaded when the user clicks one of these command bars.
Menu Drops	No	List of menu drops that apply to the extension, such as File, Edit, View, and so on. This key is for extensions that change the number of commands on the menu.
Outlook Commands	No	List of commands that the extension can intercept when the user clicks them, such as FileSaveAs.
Commands	No	List of commands that the extension is contributing to this context as defined in the [Command] section.

[Item]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Message Class	No	List of message classes this context section applies to, such as IPM.Note.
Item States	No	List of item states this context section applies to. Valid values are Read, Compose, Modal.
Events	No	List of events that apply to the extension for this context. Valid values are OnItemChange, OnCheckNames, OnCheckNamesComplete, OnRead, OnReadComplete, OnWrite, OnWriteComplete, OnSubmit, OnSubmitComplete, OnCommand, OnMenuDropDown, InstallCommands, AddPropSheetPages.
Contexts	No	List of additional sections defining item context behavior. See "[context name]," later in this document.
Command Bars	No	List of command bars that apply to the extension, such as File, Edit, View, and so on. This key is for extensions that may add commands beyond what is listed in the [Command] section. The extension is loaded when the user clicks one of these command bars.
Menu Drops	No	List of menu drops that apply to the extension, such as File, Edit, View, and so on. This key is for extensions that change the number of commands on the menu.
Outlook Commands	No	List of commands that the extension can intercept when the user clicks them, such as FileSaveAs.
Commands	No	List of commands that the extension is contributing to this context as defined in the [Command] section.

[Property Sheet]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Events	No	List of events that apply to the extension for this context. Valid Value is AddPropSheetPages.
Property Sheet Dialogs	No	List of dialog boxes that the extension can contribute to.
Property Sheet Exclusion	No	List of property sheet names to be intercepted by Outlook and prevented from being added.

[Advanced Criteria]

This is an optional section. This section can contain the keys shown in the following table:

Key Name	Required?	Description
Events	No	List of events that apply to the extension for this context. Valid Value is AdvancedCriteria.
Property Sheet Dialogs	No	List of dialog boxes that the extension can contribute to.
Property Sheet Exclusion	No	List of property sheet names to be intercepted by Outlook and prevented from being added.

[Command]

This is an optional section. Each line in the [Command] section defines a single command which is used in either a [Folder] section, an [Item] section, or both. Following is an example of a line in the [Command] section:

FileAddPubFolder=50004;Add to Public Folder Favori&tes;FileFolder After FileFolderRenameFolder Separator New Scope;emsuix32.dll;452;;

The syntax for a line in this section is as follows:

keytag = commandID;title;position info;bitmap info

Where:

keytag is the key defined for the command, used in other parts of the ECF.

commandID is the command's ID.

title is the string title for the command. Use an ampersand (&) to denote an accelerator for the command. For example, Add to Public Folder Favori&tes. In this example "t"' is the accelerator.

position infois a sequence of words separated by spaces which tell Outlook where to put the command. It has three parts:

• The first part is the host menu, such as FileFolder.
• The second part indicates where the command is to appear. Valid values are Start, End, After, or Before. If the value is After or Before, the value must be followed by the name of the neighboring command.
• The third part is an optional set of flags, separated by spaces or commas. The following table lists valid values for these flags:

Flag	Effect
Suppress	The extension adds the command, but Outlook suppresses it.
New	Outlook, not the extension, adds the command at this location. There must be a line in the [Command] section with a matching ID indicating where the extension attempts to place the command.
Enabled	The command is never disabled.
Submenu	Makes the command a submenu. The ID specified in the first part of this line may be used as the menu name specified in the first word of the third part of other lines in this section.
Popup	Makes the command a popup menu. The ID specified in the first part of this line may be used as the menu name specified in the first word of the third part of other lines in this section.
Scope	Makes the command apply to selections in the Scope pane. Callbacks to GetSelectionItem or GetSelectionCount will return the currently selected folder instead of the selected items.
Sep, Separator, or SeparatorBefore	Places a separator before the command.

bitmap info is an optional series of values separated by semicolons. The semicolons must be present even if the values for the information are blank. The series of information is listed in the order shown:

DLL;ID;#Bitmaps;Index

[Context Name]

These are developer-defined optional sections. The ECF allows general context information to be specified for [Folder] and [Item] sections, and then more detailed information for specific cases of the [Folder] and [Item] contexts by naming new sections to contain the specific information. You may wish, for example, to have one extension Help topic in all Mail type folders, but another for all other type folders. You could accomplish this with the following ECF sections:

[Folder]
Events="InstallCommands"
Contexts=ExplorerMail; ExplorerOther
[ExplorerMail]
Folder Class=IPF.Note
Commands=MyMailHelpTopic
[ExplorerOther]
Commands=MyGenericHelpTopic

In the [Folder] section above, events handled by all [Folder] sub-contexts are defined as InstallCommands. Then, two new, more specific context sections are referenced: ExplorerMail and ExplorerOther.

The [ExplorerMail] section contains an entry for Folder Class to specify that this section applies only to folders of the class IPF.Note, and then goes on to specify a Help topic command.

The [ExplorerOther] section has no qualifying Folder Class key, so it is applicable to all folder classes (IPF.Note folders excepted, due to the previously defined section). It specifies another Help topic command.

Example ECF

Following is an example of a complete ECF:

[General]
Display Name="CompuServe"
Description="CompuServe"
GUID={9B243160-3745-11cf-8582-00AA00C02BBB}
Path="csmapx32.dll"
Entry Point=1
Client Version=4.0
Service Provider=CISXP
Misc Flags=RemoteAlso
[Exchange Client Compatibility]
Exchange Registry=1
Exchange Extension Key="CISXP"
Exchange Context Map=01110110011010
Exchange Interface Map=1000000
[Folder]
Events="InstallCommands"
Commands=CSHelpTopics
[Item]
Events="InstallCommands"
Commands=CSHelpTopics
[Command]
CSHelpTopics=50000;CompuSer&ve Mail Help Topics;Help After HelpHelp Enabled

How Outlook uses the ECF file

The ECF is supplied by each extension at installation and is either read automatically by Outlook the next time it executes, or is loaded explicitly by the user on the General tab of the Options dialog box (Tools menu). If you create an ECF for an existing extension, the ECF overrides the INI/registry settings for that extension when Outlook reads the ECF.

Localization

Only two sections within an ECF typically need localization: [General] and [Command].

Localizing the [General] Section

The entire contents of the Display Name and Descriptionkeys should be localized. These keys are used in the Add-in Manager dialog box to display the name and description of the add-in.

Localizing the [Command] Section

Localizing this section can be tricky. The string to be localized for each key is the second delimited value of the key. For example, the bold text in the following:

InboxAsst=50020;In&box Assistant...;Tools Before ToolsOOFAsst

This string, however, matches the string in the add-in DLL. If it is changed, it can no longer be identified by the internal command, resulting in two commands in the active session of Outlook: the localized command from the ECF (which is non-operational), and the English command contributed by the add-in (which is not overridden by the ECF).

The possible solutions for localization are:

• Localize the DLL and the ECF together, so that the strings match.
• Suppress the command contributed by the add-in, and add a new key representing the localized command. For example:

InboxAsst=50020;In&box Assistant...;Tools Before ToolsOOFAsst Suppress

LocalizedInboxAsst=50020;In&box Ayudante...;Tools Before ToolsOOFAsst New

---