Deploying a Custom Control and Design-time Assemblies
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
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 |
|
|
ToolboxBrowsable = false |
|
|
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.
ControlLibrary.dll (control assembly)
ControlLibrary.Design.<version>.dll
Design\ControlLibrary.Design.<version>.dll
ControlLibrary.[Expression|VisualStudio].Design.<version>.dll
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 loaded according to the <version> specified in its file name. The following rules show how <version> is interpreted by a designer.
If <version> has a different major version number than the designer's framework version, the design assembly is not loaded.
If more than one design-time assembly is compatible with the designer’s framework version, the designer loads the version that is compiled against the highest framework version that is does not exceed the designer’s framework version.
The following table shows an example of a designer that is built with the 4.1.3.0 framework version loading four design-time assemblies with different versions.
Example Design-time Assembly Name |
Designer Loads? |
|---|---|
ControlLibrary.Design.3.0.1.0.dll |
No. Incompatible version. |
ControlLibrary.Design.4.0.1.0.dll |
No. Would load, but a higher version is available. |
ControlLibrary.Design.4.1.1.0.dll |
Yes. Closest to the designer's version. |
ControlLibrary.Design.4.3.dll |
No. Built against a higher framework 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
Concepts
Providing Design-time Metadata