Registering Toolbox Support Features
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 How to: Create a Toolbox Control That Uses WPF.
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 DefaultItems.
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. |
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 Toolbox (Visual Studio SDK).
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. |
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:
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: Wildcard characters are not supported. For more information on the format of full assembly names, see AssemblyQualifiedName. 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:
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 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}
See Also
Reference
ProvideAssemblyFilterAttribute
Concepts
How to: Provide Custom Toolbox Items By Using Interop Assemblies