IConfigureToolboxItem Interface

Definition

Namespace:

Microsoft.VisualStudio.Shell

Assembly:

Microsoft.VisualStudio.Shell.15.0.dll

Package:

Microsoft.VisualStudio.Shell.15.0 v17.12.40392

Provides the ability to configure ToolboxItem objects dynamically by adding additional data to the toolbox item's Properties dictionary. This data is then serialized as a permanent part of the toolbox item.

public interface class IConfigureToolboxItem

public interface class IConfigureToolboxItem

__interface IConfigureToolboxItem

public interface IConfigureToolboxItem

type IConfigureToolboxItem = interface

Public Interface IConfigureToolboxItem

Remarks

This interface can be implemented on any creatable object that does not derive from Package. The toolbox service will call the ConfigureToolboxItem method when a new toolbox item is first added to the toolbox.

Implementations of this interface must be registered. The registration consists of the following steps:

1. Registering a particular VSPackage as providing toolbox item configuration.

   Under the Managed Package Framework, this registration is done by ProvideToolboxItemConfigurationAttribute.

   The example below shows how the VSPackage MyPackage registers the ToolboxConfig class as an implementation of IConfigureToolboxItem:

   
                       [ProvideToolboxItemConfigurationAttribute(typeof(ToolboxConfig))]  
       [GuidAttribute("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")]  
       public class MyPackage : MSVSIP.Package {…}  
   
   

2. Registering the dynamic configuration of all the ToolboxItem objects by specified assemblies.

   Under the Managed Package Framework, the assemblies whose ToolboxItem objects are processed by an implementation of IConfigureToolboxItem are specified by applying ProvideAssemblyFilterAttribute to that implementation of IConfigureToolboxItem.

   The example below registers the ToolboxConfig class as providing configuration support for all ToolboxItem objects in all assemblies with the Vsip namespace.

       [ProvideAssemblyFilterAttribute("Vsip.*, Version=*, Culture=*, PublicKeyToken=*")]  
       public sealed class ToolboxConfig : IConfigureToolboxItem {…}  
   

Note

This attribute uses the full assembly identification, including a simple name, a version number, a cryptographic key pair, and a supported culture. For more information on assembly identification, see AssemblyName. The "*" character in a specification is taken as a wildcard.

Registering an implementation of IConfigureToolboxItem as part of a VSPackage modifies registry settings under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\ToolboxItemConfiguration and HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<Version>\CLSID, 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, or with DefaultRegistryRootAttribute. For more information on alternate root paths, see Command-Line Switches and DefaultRegistryRootAttribute.

For more information about the contents of these registry entries, see Registering Toolbox Support Features.

Notes to Implementers

Implement this interface when you need to modify the characteristics of a Toolbox control dynamically, for example to respond to the presence or absence of certain features or objects.

The methods of this interface are invoked only when the Toolbox is initialized.

The Visual Studio environment may need to create a new instance of implementations of IConfigureToolboxItem at any time. Ensure that you:

• Always implement IConfigureToolboxItem as a public class.

• Never implement IConfigureToolboxItem on a class implementing Package or IVsPackage.

Methods

ConfigureToolboxItem(ToolboxItem)

Called by the toolbox service to configure ToolboxItem objects.