Share via


Deploying a Custom Control and Design-time Assemblies

When a design tool opens your custom control's assembly, it also looks for related design-time assemblies. In particular, designers look for assemblies that have the ProvideMetadataAttribute assembly-level attribute. When this attribute is found, the designer searches the assembly for a class that implements the IProvideAttributeTable interface. The designer queries the AttributeTable property of this class for an attribute collection that specifies the design-time behavior.

Naming Convention for Design-time Assemblies

Design tools, such as Visual Studio and Expression Blend, discover your custom design-time assemblies by using a naming convention. This convention has evolved over different tools versions. Use the following table to name your assemblies for the appropriate target designers.

Target Environment

Naming Convention

Example Names

Expression Blend 3 and Visual Studio 2010 

<ControlLibrary>.Design.<version>.dll (Common)

<ControlLibrary>.Expression.Design.<version>.dll (Expression Blend)

<ControlLibrary>.VisualStudio.Design.<version>.dll (Visual Studio)

TailspinToysControls.Design.4.0.dll

TailspinToysControls.Expression.Design.4.0.dll

TailspinToysControls.VisualStudio.Design.4.0.dll

Expression Blend 2 and Visual Studio 2008 

<ControlLibrary>.Design.dll (Common)

<ControlLibrary>.Expression.Design.dll (Expression Blend)

<ControlLibrary>.VisualStudio.Design.dll (Visual Studio)

TailspinToysControls.Design.dll

TailspinToysControls.Expression.Design.dll

TailspinToysControls.VisualStudio.Design.dll

Common refers to design-time implementations that are shared by Visual Studio and Expression Blend. The <version> substring specifies the corresponding version of the WPF Designer framework. You can verify this by inspecting the version of the Microsoft.Windows.Design.dll assembly. 

Tool-specific design-time assemblies can override the shared implementation in the common assembly. This means that your custom design experience can vary considerably in different design tools. For more information, see Providing Design-time Metadata.

Registering Design-time Assemblies

Register your control and its associated design-time assemblies by using the assembly folder registration procedure, which is also named AssemblyFoldersEx registration. To register controls by using the assembly folder registration procedure requires only that control assemblies exist on disk and that Toolbox registry entries are specified. This registration procedure may occur before or after Visual Studio is installed.

AssemblyFoldersEx is a registry key under each target framework version, such as Silverlight 3 or the .NET Framework 4. AssemblyFoldersEx includes a set of keys that specify folders that contain framework-specific assemblies. For example, to target Silverlight 3, the AssemblyFoldersEx registry key is located in the following registry path.

[HKCU or HKLM]\SOFTWARE\Wow6432Node\Microsoft\Microsoft SDKs\Silverlight\v3.0\AssemblyFoldersEx

When the Toolbox subkey and its supporting entries are created under an AssemblyFoldersEx key, controls appear in the Toolbox, the Add References dialog box, and the Choose Items dialog box.

The following table lists the registry entries that can be used in the AssemblyFoldersEx and Toolbox keys to register an assembly folder.

Registry Entry

Registry Entry Type

Description

Example

<assembly>

Key

The name of the key, usually branded.

[TailspinToys Controls]

<assembly folder>

Default String Value

Specifies the full installation path for your custom control's assembly. Designers will search for design-time assemblies in this folder and in a subfolder named Design.

@="c:\\Program Files\\Reference Assemblies\\TailspinToys Controls\\Bin\\"

Toolbox

Key

Add the Toolbox key if you want the assemblies in <assembly folder> searched for controls to add to the Toolbox. If this key is not specified, controls appear in the Choose Items dialog box and assemblies in the Add Reference dialog box, but not in the Toolbox.

[Toolbox]

TabName

String Value

Specifies the default Toolbox group for controls in <assembly folder>. The group is created if it does not exist. If the value is not specified, controls are installed to the default group for the platform.

Use this value to specify a brand instead of a functional category. Do not target the Common or All Controls categories for WPF and Silverlight custom controls. The value cannot be localized.

"TabName"="TailspinToys"

Servicing

Keys

To force a Toolbox cache refresh, specify a new key or value inside the Toolbox key. The recommended way to do this is to create an Updates subkey that contains a registration value for each installed update. The cache refresh is only for the controls found in the specific folder the Toolbox key belongs to, not all of the framework controls.

The user's Toolbox customizations for an assembly folder’s controls may be lost when the assembly folder is refreshed.

[Updates]

"Update3"="1"

"Update7"="1"

The following example registry script registers assemblies that target the .NET Framework 4 and are located in the Reference Assemblies path. Any controls that have ToolboxBrowsableAttribute set to true are displayed in the Toolbox under the Tailspin Toys tab.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0\AssemblyFoldersEx\TailspinToys]
@="c:\\\\Program Files\\\\Reference Assemblies\\\\TailspinToys Controls\\\\Bin\\\\"

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0\AssemblyFoldersEx\TailspinToys\Toolbox]
"TabName"="Tailspin Toys"

ToolboxBrowsableAttribute and the Toolbox Registry Key

You specify whether your custom control appears in the Toolbox by adding the ToolboxBrowsableAttribute to the control's design-time metadata. For more information, see Walkthrough: Providing Metadata for Toolbox Icons.

The Choose Items dialog box is used for browsing to new assemblies and adding new controls to the Toolbox. The following table shows how the interaction between the ToolboxBrowsableAttribute and the Toolbox registry key determines when the custom control appears in the Toolbox and the Choose Items dialog box.

Toolbox Registry Key

No Toolbox Registry Key

ToolboxBrowsable = true

  • In Toolbox

  • In Choose Items dialog box

  • Not in Toolbox

  • In Choose Items dialog box

ToolboxBrowsable = false

  • Not in Toolbox

  • Not in Choose Items dialog box

  • Not in Toolbox

  • Not in Choose Items dialog box

Loading Design-time Assemblies

Designers load your custom design-time assemblies in a specific order. This enables designer-specific implementations to replace generic implementations. For a custom control that is deployed in an assembly named ControlLibrary.dll, the following list shows the order in which design-time assemblies are loaded.

  1. ControlLibrary.dll (control assembly)

  2. ControlLibrary.Design.<version>.dll

  3. Design\ControlLibrary.Design.<version>.dll

  4. ControlLibrary.[Expression|VisualStudio].Design.<version>.dll

  5. Design\ControlLibrary.[Expression|VisualStudio].Design.<version>.dll

Designer-specific assemblies replace the implementations that are deployed in generic assemblies. For example, TailspinToysControlLibrary.VisualStudio.Design.dll may replace implementations in TailspinToysControlLibrary.Design.dll.

In addition, a design-time assembly is chosen according to the version of Microsoft.Windows.Design.Extensibility.dll that it references. The following rules show how this version is interpreted by a designer.

  • If the version of Microsoft.Windows.Design.Extensibility.dll referenced by the design-time assembly has a different major version number than the version used by the designer, the design-time assembly is not loaded.

  • If the version of Microsoft.Windows.Design.Extensibility.dll referenced by the design-time assembly is greater than the version used by the designer, the design-time assembly is not loaded.

  • If more than one design-time assembly is available after applying the above rules, the designer loads the version that is compiled against the highest version of Microsoft.Windows.Design.Extensibility.dll.

The following table shows how a designer built with the 4.1.3.0 version of Microsoft.Windows.Design.Extensibility.dll would react when presented with four design-time assemblies referencing different versions of Microsoft.Windows.Design.Extensibility.dll.

Microsoft.Windows.Design.Extensibility.dll version referenced by design-time assembly

Designer Loads?

3.0.1.0

No. Different major version than designer.

4.0.1.0

No. Would load, but a higher version is available.

4.1.1.0

Yes. Closest to the designer's version.

4.3.0.0

No. Built against a higher version than the designer.

Refreshing the Toolbox

When updating assemblies in folders specified by the AssemblyFoldersEx key, you may need to refresh the Visual Studio Toolbox cache. The cache contains the names, categories, and icons for controls that appear in the Toolbox. The cache does not include the control or design-time assemblies. When compiling projects any serviced control or design-time assembly is automatically refreshed.

The Toolbox cache for an assembly folder is updated if an AssemblyFoldersEx key is altered in any way (any of its values or subkeys change). The update occurs on Toolbox initialization, when the Toolbox task pane is first shown (typically on Visual Studio boot or project load).

To force a Toolbox cache refresh, specify a new key or value inside the Toolbox key. The recommended way to do this is to create a Servicing subkey which then contains a registration value for each installed update. The cache refresh is only for the controls found in the specific folder the Toolbox key belongs to, not all of the framework controls. The user's Toolbox customizations for an assembly folder’s controls may be lost when the assembly folder is refreshed.

See Also

Reference

ToolboxBrowsableAttribute

ProvideMetadataAttribute

Concepts

Providing Design-time Metadata

Other Resources

Understanding WPF Designer Extensibility

Basic Extensibility Concepts