Registering Toolbox Support Features

Article
09/20/2016

VSPackages must update the registry if they extend the default set of Toolbox functionality in any of the following ways:

Using automatic toolbox tab selection of a particular toolbox category or tab when a particular designer or editor is active.
Providing any ToolboxItem objects to be loaded by the Visual Studio environment.

These items are loaded by the Visual Studio environment whenever the Toolbox is reset, either by a user through the IDE, or programmatically through the ResetDefaults method. Resetting of the Toolbox generates a ToolboxInitialized event under the Managed Package Framework.

Note

VSPackages developed under the Managed Package Framework use ProvideToolboxItemsAttribute applied to their implementation of the Package object to register this support.
Providing non-standard Clipboard format ToolboxItem objects by implementing the IVsToolboxDataProvider and IVsToolboxDataProvider2 interfaces.

Note

VSPackages developed under the Managed Package Framework use an instance of the ProvideToolboxFormatAttribute object applied to their implementation of Package to register this support.
Supporting dynamic configuration of ToolboxItem object through an implementation of the IConfigureToolboxItem interface.

Note

VSPackages developed with the Managed Package Framework use ProvideToolboxItemConfigurationAttribute applied to their implementation of the Package class, and the ProvideAssemblyFilterAttribute class applied to their implementations of the IConfigureToolboxItem class to register this support.

Unmanaged VSPackages must explicitly update the registry either by manually editing it or by using a Registrar (.rgs) file. For more information, see Creating Registrar Scripts.

Automatic Toolbox Tab Selection

Editors or designers, provided by an instance of an editor factory object, can require a particular toolbox tab or category to be made active when they are themselves active. For example, if a forms designer is activated, you may want the All Windows Forms tab selected.

For automatic toolbox category selection to take place, the designer's or editor's factory object must be properly registered.

An appropriate registry entry is found in the following registry location: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\Editor<Editor Factory GUID>, where <Version> is the version number of the release of Visual Studio, such as 8.0, and <Editor Factory GUID> is the GUID for the editor factory.

The entry should contain:

Name	Type	Range	Description
Default	REG_SZ	GUID	Optional. It can be used to contain a non-localized name of the editor.
DefaultToolboxTab	REG_SZ	"Your tab name here"	The non-localized name of the toolbox tab, which is made the default toolbox tab when this editor is active.

Note

There are no Attribute objects which support these registry entries in the Managed Package Framework.

Registering a Package as Providing Toolbox Items

Note

Controls created with the Toolbox Control templates in the Visual Studio 10 SDK register automatically. For more information, see How to: Create a Toolbox Control That Uses Windows Forms and Creating a WPF Toolbox Control.

Any VSPackage providing ToolboxItem objects must have a subkey, Toolbox, under its own package key, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\Packages\<Package GUID>, where <Version> is the version number of the release of Visual Studio, such as 8.0, and <Package GUID> is the GUID of the package that provides Toolbox items.

This Toolbox subkey must contain at least one entry, a DWORD entry named Default Items.

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, or you can use DefaultRegistryRootAttribute. For more information, see Command-Line Switches (Visual Studio SDK).

For the entry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\Packages\<Package GUID>:

Name	Type	Data	Description
Default Items	REG_DWORD	Can be any DWORD value. Starting with 1. The value is incremented if you update your VSPackage to supply more or different items.	The value of Default Items must be greater than or equal to 1 to add ToolboxItem objects to the Visual Studio Toolbox. Changing the value of Default Items will cause the Visual Studio IDE to load the most recent instance of a VSPackage providing ToolboxItem objects, rather than using any cached values. In the Managed Package Framework, Default Items is set by the value used in the constructor for the ProvideToolboxItemsAttribute instance applied to the VSPackage providing ToolboxItem objects.

Default Items

REG_DWORD

Can be any DWORD value. Starting with 1. The value is incremented if you update your VSPackage to supply more or different items.

The value of Default Items must be greater than or equal to 1 to add ToolboxItem objects to the Visual Studio Toolbox.

Changing the value of Default Items will cause the Visual Studio IDE to load the most recent instance of a VSPackage providing ToolboxItem objects, rather than using any cached values.

In the Managed Package Framework, Default Items is set by the value used in the constructor for the ProvideToolboxItemsAttribute instance applied to the VSPackage providing ToolboxItem objects.

Registering Support for a Non-Standard Format

Registration of supported Clipboard formats that a ToolboxItem provider VSPackage supports is optional.

If a ToolboxItem provider VSPackage does not register any special Clipboard formats, it must support the Visual Studio standard formats. For more information on the standard Toolbox Clipboard formats, see Extending the Toolbox.

If a VSPackage does provide support for non-standard formats, it must register those formats under the VSPackage's Toolbox registration key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\Packages\<Package GUID>\Toolbox, by adding a string entry named Formats.

Note

If a VSPackage registers support for any custom format, it only supports those formats that it explicitly registers. A VSPackage registering custom Clipboard formats is no longer registered as supporting the default Toolbox Clipboard formats, unless it does so explicitly.

Name	Type	Data	Description
Formats	REG_SZ	For custom formats, use a string for this subkey.	Specifies the Clipboard formats supported by a VSPackage providing custom Toolbox Clipboard formats (by implementing IVsToolboxDataProvider and IVsToolboxDataProvider2). The formats should be specified in a comma-separated list. A format can be specified either by a string containing its name, or its ID name. For example, a Formats entry might be '1,13,16,HTML Format'. For more information about Clipboard formats, see DataFormats.Format. In the Managed Package Framework, the value of Formats is obtained from the string used as an argument to the constructor for the instance of the ProvideToolboxFormatAttribute object applied to the VSPackage providing ToolboxItem objects.

Formats

REG_SZ

For custom formats, use a string for this subkey.

Specifies the Clipboard formats supported by a VSPackage providing custom Toolbox Clipboard formats (by implementing IVsToolboxDataProvider and IVsToolboxDataProvider2).

The formats should be specified in a comma-separated list.

A format can be specified either by a string containing its name, or its ID name. For example, a Formats entry might be '1,13,16,HTML Format'.

For more information about Clipboard formats, see DataFormats.Format.

In the Managed Package Framework, the value of Formats is obtained from the string used as an argument to the constructor for the instance of the ProvideToolboxFormatAttribute object applied to the VSPackage providing ToolboxItem objects.

Registering Support for Dynamic Toolbox-Item Configuration

If a VSPackage provides an implementation of IConfigureToolboxItem it must add registry settings under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\CLSID. and HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\ToolboxItemConfiguration.

The registry data under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\CLSID contains the information the Visual Studio environment requires to invoke the implementation of IConfigureToolboxItem.

The HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\ToolboxItemConfiguration data is used to select or filter which ToolboxItem objects the implementation of IConfigureToolboxItem configures on the basis of the assemblies that contain them.

Content of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\CLSID Registry Entry:

Note

Under the Managed Package Framework, these registry entries are created by the instance of ProvideToolboxItemConfigurationAttribute. This instance is attached to the VSPackage that provides ToolboxItem configuration by using reflection. The reflection is performed on the IConfigureToolboxItem item that is provided to the ProvideToolboxItemConfigurationAttribute constructor.

Name	Type	Data	Description
(Default)	REG_SZ	(Optional) Full name of the class implementing IConfigureToolboxItem.	The value here should be the same as that provided by FullName acting on the Type implementing IConfigureToolboxItem.
Assembly	REG_SZ	Full Name of the assembly providing the IConfigureToolboxItem	This value must be the full assembly identification, which, depending on the assembly, may include: - a simple name - a version number - a cryptographic key pair - a supported culture - a custom field The value must be a comma-separated list of property values as would be provided by FullName property acting on the Type implementing IConfigureToolboxItem. For instance: MyPackage.Toolbox, Version=8.0.1200.0, Culture=neutral,PublicKeyToken=abcdef12345ab, Custom=null Wildcard characters are not supported. For more information on the format of full assembly names, see AssemblyQualifiedName. IConfigureToolboxItem. For more information on assembly identification, see AssemblyName.
Class	REG_SZ	Full name of the class implementing the IConfigureToolboxItem interface as provided by FullName.	The value should be the same as that provided by FullName, acting on the type implementing IConfigureToolboxItem.
CodeBase	REG_SZ	Location of the assembly providing the implementation of IConfigureToolboxItem	This value must be the fully qualified path to the assembly file containing the implementation of IConfigureToolboxItem.
InprocServer32	REG_SZ	Must always be set to "C:\WINDOWS\System32\mscoree.dll"	The in-process server
ThreadingModel	REG_SZ	Must always be set to "Both"	Threading model

Content of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\ToolboxItemConfiguration Registry Entry:

Note

Under the Managed Package Framework, these registry entries are created by the instance of ProvideAssemblyFilterAttribute attached to the Type providing an implementation of IConfigureToolboxItem.

Name	Type	Data	Description
<AssemblyName>	REG_SZ	Specification of the assemblies to select or filter.	The key's name, <AssemblyName>, must be specified in the format of full assembly identification, which, depending on the assemblies to be filtered, may include: - a simple name - a version number - a cryptographic key pair - a supported culture - a custom field The key's name must be a comma-separated list of property value pairs. For more information on the format of full assembly names, see the Type.FullName property. A wildcard character of "" is supported in this value, and any field not provided is treated as a wildcard. For instance, a key name of System.Windows., Version=8.0., Culture=,PublicKeyToken=* selects all assemblies with namespaces under System.Windows (though not System.Windows itself), for all minor versions of the 8.0 release, and for all cultures, cryptographic key values, and custom strings. In the Managed Package Framework, the <Assembly Name> key's name is determined by the string used as the argument to the constructor for the ProvideAssemblyFilterAttribute instance applied to the class implementing the IConfigureToolboxItem interface.
<ImplementationObject>	REG_SZ	GUID	The name of this subkey of AssemblyName is the fully qualified name of the Type implementing the IConfigureToolboxItem interface. The value of this subkey is the GUID of this Type. In the Managed Package Framework this information is obtained through reflection from the class implementing the IConfigureToolboxItem interface with a ProvideAssemblyFilterAttribute object applied to it.

<AssemblyName>

REG_SZ

Specification of the assemblies to select or filter.

The key's name, <AssemblyName>, must be specified in the format of full assembly identification, which, depending on the assemblies to be filtered, may include:

- a simple name

- a version number

- a cryptographic key pair

- a supported culture

- a custom field

The key's name must be a comma-separated list of property value pairs. For more information on the format of full assembly names, see the Type.FullName property.

A wildcard character of "*" is supported in this value, and any field not provided is treated as a wildcard.

For instance, a key name of

System.Windows.*, Version=8.0.*, Culture=*,PublicKeyToken=*

selects all assemblies with namespaces under System.Windows (though not System.Windows itself), for all minor versions of the 8.0 release, and for all cultures, cryptographic key values, and custom strings.

In the Managed Package Framework, the <Assembly Name> key's name is determined by the string used as the argument to the constructor for the ProvideAssemblyFilterAttribute instance applied to the class implementing the IConfigureToolboxItem interface.

<ImplementationObject>

REG_SZ

GUID

The name of this subkey of AssemblyName is the fully qualified name of the Type implementing the IConfigureToolboxItem interface.

The value of this subkey is the GUID of this Type.

In the Managed Package Framework this information is obtained through reflection from the class implementing the IConfigureToolboxItem interface with a ProvideAssemblyFilterAttribute object applied to it.

An example of an entry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\ToolboxItemConfiguration would be:

Vsip.*, Version=2.0.3500

Vsip.ToolboxConfiguration = {YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY}

Registering Toolbox Support Features

Automatic Toolbox Tab Selection

Registering a Package as Providing Toolbox Items

Registering Support for a Non-Standard Format

Registering Support for Dynamic Toolbox-Item Configuration

See Also

Additional resources