Registering Custom Options Pages

Article
07/11/2012

For a Tools Options page to be available to users and support automation, it must be properly registered with the Visual Studio integrated development environment (IDE).

Tools Options pages based on the managed package framework are registered by applying an instance of ProvideOptionPageAttribute to the VSPackage providing the page. Automation support is indicated by setting the SupportsAutomation property to true.

Tools Options Page Registration

Integrating a custom Tools Options page with Visual Studio requires the creation of a registry entry in the following location: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\ToolsOptionsPages, where <Version> is the version of Visual Studio, for example 8.0.

The entry has a primary key with the category (<PageCategory>) of the Tools Options page, and a subkey containing the name of the page's subcategory (<PageSubCategory>).

For example, the Tools Options page identified with the string, TextEditor.Basic, has a registry key <PageCategory>=textEditor with a subkey of <PageSubCategory>=Basic.

The structure of the registry entry is below:

HKLM\Software\Microsoft\VisualStudio\<Version>\ToolsOptionsPages\

<PageCategory> = '#12345'

Package = '{XXXXXX XXXX XXXX XXXX XXXXXXXXX}'

ResourcePackage = '{YYYYYY YYYY YYYY YYYY YYYYYYYYY}'

HKLM\Software\Microsoft\VisualStudio\<Version>\ToolsOptionsPages\<PageCategory>

<PageSubCategory>> = '#67890'

Page = '{ZZZZZZ ZZZZ ZZZZ ZZZZ ZZZZZZZZZ}'

Package = '{AAAAAA AAAA AAAA AAAA AAAAAAAAA}'

ResourcePackage = '{BBBBBB BBBB BBBB BBBB BBBBBBBBB}'

NoShowAllView = 0/1

The following table lists the values under HKLM\Software\Microsoft\VisualStudio\<Version>\ToolsOptionsPages\<PageCategory>.

Name	Type	Data	Description
(Default)	REG_SZ	The canonical category name of the custom Tools Options page	The key's name, <PageCategory>, is the canonical non-localized category name of the Tools Options page. Note If automation is supported, the canonical non-localized category and subcategory names are used to obtain a Tools Options page's Properties collection. For more information, see Using Options Pages. For implementations based on the managed package framework, <PageCategory> is obtained from the categoryName argument to the ProvideOptionPageAttribute constructor. The key can be empty, or it can contain the reference ID to the localized string in an implementation's satellite DLL. For implementations based on the managed package framework, this value is obtained from the categoryResourceID argument to the ProvideOptionPageAttribute constructor.
Package	REG_SZ	GUID	The GUID of the VSPackage implementing the custom Tools Options page. Implementations based on the managed package framework using ProvideOptionPageAttribute use reflection to obtain this value.
ResourcePackage	REG_SZ	GUID	Optional. A satellite DLL containing localized strings if the implementing VSPackage does not supply them. The managed package framework uses reflection to obtain the correct resource package, so ProvideOptionPageAttribute does not set this argument.

(Default)

REG_SZ

The canonical category name of the custom Tools Options page

The key's name, <PageCategory>, is the canonical non-localized category name of the Tools Options page.

Note

If automation is supported, the canonical non-localized category and subcategory names are used to obtain a Tools Options page's Properties collection. For more information, see Using Options Pages.

For implementations based on the managed package framework, <PageCategory> is obtained from the categoryName argument to the ProvideOptionPageAttribute constructor.

The key can be empty, or it can contain the reference ID to the localized string in an implementation's satellite DLL.

For implementations based on the managed package framework, this value is obtained from the categoryResourceID argument to the ProvideOptionPageAttribute constructor.

Package

REG_SZ

GUID

The GUID of the VSPackage implementing the custom Tools Options page.

Implementations based on the managed package framework using ProvideOptionPageAttribute use reflection to obtain this value.

ResourcePackage

REG_SZ

GUID

Optional.

A satellite DLL containing localized strings if the implementing VSPackage does not supply them.

The managed package framework uses reflection to obtain the correct resource package, so ProvideOptionPageAttribute does not set this argument.

The following table lists the values under HKLM\Software\Microsoft\VisualStudio\<Version>\ToolsOptionsPages\<PageCategory>\<PageSubCategory>.

Name	Type	Data	Description
(Default)	REG_SZ	The canonical subcategory name of the custom Tools Options page	The key's name, <PageSubCategory>, is the canonical non-localized name of the Tools Options page subcategory. Note If automation is supported, the canonical non-localized category and subcategory names are used to obtain a Tools Options page's Properties collection. For more information, see Using Options Pages. For implementations based on the managed package framework, <PageSubegory> is obtained from the pageName argument to the ProvideOptionPageAttribute constructor. The key can be empty, or it can contain the reference ID to the localized string in a satellite DLL of an implementation. For implementations based on the managed package framework, this value is obtained from the pageNameResourceID argument to the ProvideOptionPageAttribute constructor.
Page	REG_SZ	GUID	The GUID of the object implementing the custom Tools Options page. Implementations based on the managed package framework using ProvideOptionPageAttribute use the constructor's pageType argument containing the VSPackage's Type and reflection to obtain this value.
Package	REG_SZ	GUID	Implementations based on the managed package framework using ProvideOptionPageAttribute use reflection to obtain this value.
ResourcePackage	REG_SZ	GUID	Optional. A satellite DLL containing localized strings if the implementing VSPackage does not supply them. The managed package framework uses reflection to obtain the correct resource DLL, so ProvideOptionPageAttribute does not set this argument.
NoShowAllView	REG_DWORD	0 or 1	Optional. Indicates whether a given Tools Options page should appear in the complex (default) view of Tools Options pages. Supports programming environments, such as Visual Basic, which have special Tools Options pages to aggregate common settings to provide users with specialized simplified views of options. If the REG_DWORD entry is non-zero, the Tools Options page does not appear in a complex view. For more information, see Options Dialog Box (Visual Studio). Implementations based on the managed package framework can set this value by setting the NoShowAllView property to true in the ProvideOptionPageAttribute constructor.

A VSPackage or object based on a single interop assembly may implement more than one Tools Options page. Each implementation requires a new entry in HKLM\Software\Microsoft\VisualStudio\<Version>\ToolsOptionsPages.

As the managed package framework instantiates the object providing a Tools Options page, each page should have its own implementation object, independent from a VSPackage's implementation of Package.

Automation Support

If automation support is used to implement a Tools Options page, it must register itself as an automation provider. To use automation for property management, and use its persistence mechanisms to save the Tools Options page state, it must register itself as an AutomationProperty provider.

Register a VSPackage as an Automation Provider (Only for Tools Options Pages Based on Interop Assemblies)

Tools Options pages based on an interop assembly are implemented as part of a VSPackage's implementation classes.

In this case, if a Tools Options page is to support automation, the interop assembly–based VSPackage must be registered as an automation provider.

Note

Automation support in the managed package framework is provided by an object independent of the implementation of the VSPackage. If that object supports automation, this is registered through the SupportsAutomation property of the ProvideOptionPageAttribute constructor.

The entry for registering a VSPackage as an automation provider is of the form HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\Packages\<PackageGUID>\Automation, where <Version> is the version of Visual Studio (such as 8.0) and <PackageGUID> is the GUID of the VSPackage implementing the automation object.

Note

The root path of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version> can be overridden with an alternate root when the Visual Studio shell is initialized. For more information, see Command-Line Switches (Visual Studio SDK).

The structure of the registry entry is:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\Packages\<PackageGUID>\Automation

Name	Type	Data	Description
Automation	REG_SZ	Not defined	Undefined. The presence of this key indicates that the VSPackage referred to by <PackageGUID> supports automation. The field can be used to store documentation. ProvideAutomationObjectAttribute automatically creates this key for applications based on the managed package framework.
<AutomationObjectName>	REG_SZ	The canonical name of the automation object provided	Only the key name is relevant. It is used in automation operations. The field can be used to store documentation. For implementations based on the managed package framework, the name of this key is determined by the name argument to the ProvideAutomationObjectAttribute constructor. If the ProvideAutomationObjectAttribute constructor has a valid string supplied to its Description property, this value is inserted here.

Automation

REG_SZ

Not defined

Undefined.

The presence of this key indicates that the VSPackage referred to by <PackageGUID> supports automation.

The field can be used to store documentation.

ProvideAutomationObjectAttribute automatically creates this key for applications based on the managed package framework.

REG_SZ

The canonical name of the automation object provided

Only the key name is relevant. It is used in automation operations.

The field can be used to store documentation.

For implementations based on the managed package framework, the name of this key is determined by the name argument to the ProvideAutomationObjectAttribute constructor.

If the ProvideAutomationObjectAttribute constructor has a valid string supplied to its Description property, this value is inserted here.

Register a Tools Options Page as Supporting Automation

Both Managed Package Framework– and interop assembly–based implementations of Tools Options pages must register to allow automation access to a Tools Options page. This includes the automation property persistence mechanisms and access to the page through EnvDTE. This is independent of the registration of the VSPackage itself as an automation service provider.

As with the Tools Options page registration mentioned above, the entry has a primary key with the category (<PageCategory>) of the Tools Options page, and a subkey containing the name of the page's subcategory (<PageSubcategory>).

If you use the managed package framework, use ProvideOptionPageAttribute to register a class as providing a Tools Options page and set the SupportsAutomation property to true to indicate that the page supports automation.

The registry entry is found in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\AutomationProperties, where <Version> is the version of Visual Studio, for example 8.0.

Note

The root path of HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version> can be overridden with an alternate root when the Visual Studio shell is initialized, for more information see, Command-Line Switches (Visual Studio SDK).

The structure of the registry entry is below:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\AutomationProperties

<PageCategory> = ‘#456’

ResourcePackage = '{XXXXXX XXXX XXXX XXXX XXXXXXXXX}'

<PageSubCategory> = ‘#789’

Package = '{YYYYYY YYYY YYYY YYYY YYYYYYYYY}'

Name = '<PageCategory> .<PageSubcategory>'

'ProfileSave' = 1/0

The following table lists the values under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\AutomationProperties\<PageCategory>.

Name	Type	Data	Description
(Default)	REG_SZ	The canonical category name of the custom Tools Options page	The key's name, <PageCategory>, is the canonical non-localized name of the Tools Options page category. Note If automation is supported, the canonical non-localized category and subcategory names are used to obtain a Tools Options page's Properties collection. For more information, see Using Options Pages. The key can be empty, or it can contain the reference ID to the localized string in an implementation's satellite DLL. For implementations based on the managed package framework, <PageCategory> is obtained from the categoryName argument to the ProvideOptionPageAttribute constructor.
ResourcePackage	REG_SZ	GUID	Optional. A satellite DLL containing localized strings if the implementing VSPackage does not supply them. The managed package framework uses reflection to obtain the correct resource VSPackage, so ProvideOptionPageAttribute does not set this argument.

(Default)

REG_SZ

The canonical category name of the custom Tools Options page

The key's name, <PageCategory>, is the canonical non-localized name of the Tools Options page category.

Note

The key can be empty, or it can contain the reference ID to the localized string in an implementation's satellite DLL.

For implementations based on the managed package framework, <PageCategory> is obtained from the categoryName argument to the ProvideOptionPageAttribute constructor.

ResourcePackage

REG_SZ

GUID

Optional.

A satellite DLL containing localized strings if the implementing VSPackage does not supply them.

The managed package framework uses reflection to obtain the correct resource VSPackage, so ProvideOptionPageAttribute does not set this argument.

The following table lists the values under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\AutomationProperties\<PageCategory>\<PageSubCategory>.

Name	Type	Data	Description
(Default)	REG_SZ	The subcategory name of the custom Tools Options page	The key's name, <PageSubCategory>, is the canonical non-localized name of the Tools Options page subcategory. Note If automation is supported, the canonical non-localized category and subcategory names are used to obtain a Tools Options page's Properties collection. For more information, see Using Options Pages. The key can be empty, or it can contain the reference ID to the localized string in an implementation's satellite DLL. For implementations based on the managed package framework, <PageSubCategory> is obtained from the pageName argument to the ProvideOptionPageAttribute constructor.
Package	REG_SZ	GUID	The GUID of the VSPackage implementing the custom Tools Options page. Implementations based on the managed package framework using ProvideOptionPageAttribute use reflection to obtain this value.
Name	REG_SZ	Name of the Tools Options page properties collection	The <PageCategory>.<PageSubCategory> string used to refer to the Tools Options page. For more information, see Using Options Pages. For implementations based on the managed package framework, the name is obtained from arguments to the ProvideOptionPageAttribute constructor and is of the form categoryName.pageName.
ProfileSave	DWORD	1/0	Optional. This value indicates whether the Tools Options page settings are saved by the Visual Studio settings mechanism when a user clicks the Import/Export Settings command on the Tools menu. If the key is present and its value is 1, then the Tools Options page is requesting settings support. Implementations based on the managed package framework set this value if the ProvideOptionPageAttribute constructor is supplied with the SupportsProfiles property set to true.

Registering Custom Options Pages

Tools Options Page Registration

Automation Support

Register a VSPackage as an Automation Provider (Only for Tools Options Pages Based on Interop Assemblies)

Register a Tools Options Page as Supporting Automation

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources