部署自定义控件和设计时程序集

  • 项目

当设计工具打开自定义控件的程序集时，它还查找相关的设计时程序集。 特别是，设计器查找具有 ProvideMetadataAttribute 程序集级特性的程序集。 在找到该特性后，设计器会在程序集内搜索实现 IProvideAttributeTable 接口的类。 设计器会在该类的 AttributeTable 属性中查询用来指定设计时行为的特性集合。

设计时程序集的命名约定

设计工具（如 Visual Studio 和 Expression Blend）通过使用命名约定来发现自定义设计时程序集。 此约定已经针对不同的工具版本进行了演变。 可以按照下表为相应的目标设计器命名程序集。

目标环境

命名约定

示例名称

Expression Blend 3 和 Visual Studio 2010 

<控件库>.Design.<版本>.dll（公用）

<控件库>.Expression.Design.<版本>.dll (Expression Blend)

<控件库>.VisualStudio.Design.<版本>.dll (Visual Studio)

TailspinToysControls.Design.4.0.dll

TailspinToysControls.Expression.Design.4.0.dll

TailspinToysControls.VisualStudio.Design.4.0.dll

Expression Blend 2 和 Visual Studio 2008 

<控件库>.Design.dll（公用）

<控件库>.Expression.Design.dll (Expression Blend)

<控件库>.VisualStudio.Design.dll (Visual Studio)

TailspinToysControls.Design.dll

TailspinToysControls.Expression.Design.dll

TailspinToysControls.VisualStudio.Design.dll

“公用”是指由 Visual Studio 和 Expression Blend 共享的设计时实现。 <版本> 子字符串指定 WPF 设计器 框架的相应版本。 这可以通过检查 Microsoft.Windows.Design.dll 程序集的版本来验证。

特定于工具的设计时程序集会重写公用程序集内的共享实现。 这意味着自定义设计体验可能会因设计工具不同而存在很大的区别。 有关更多信息，请参见提供设计时元数据。

注册设计时程序集

通过使用程序集文件夹的注册过程（又称为 AssemblyFoldersEx 注册）来注册控件及其相关设计时程序集。 若要使用程序集文件夹注册过程来注册控件，只需要满足以下条件：控件程序集存在于磁盘上而且指定了工具箱注册表项。 此注册过程可以在安装 Visual Studio 之前或之后进行。

AssemblyFoldersEx 是每个目标框架版本（如 Silverlight 3 或 .NET Framework 4）下面的注册表项。 AssemblyFoldersEx 包括一组用来指定特定于框架的程序集所在文件夹的项。 例如，若要面向 Silverlight 3，AssemblyFoldersEx 注册表项应位于以下注册表路径中。

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

当在 AssemblyFoldersEx 项下面创建了 Toolbox 子项及其支持项之后，控件将出现在“工具箱”、**“添加引用”对话框和“选择项”**对话框中。

下表列出了可以在 AssemblyFoldersEx 和 Toolbox 项中用于注册程序集文件夹的注册表项。

注册表项

注册表项类型

说明

示例

<assembly>

键

注册表项的名称，通常带有品牌。

[TailspinToys Controls]

<程序集文件夹>

默认字符串值

为自定义控件的程序集指定完整的安装路径。 设计器将在该文件夹和一个名为 Design 的子文件夹中搜索设计时程序集。

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

Toolbox

键

如果要将搜索控件所用的 <程序集文件夹> 中的程序集添加到工具箱，请添加 Toolbox 项。 如果未指定此项，控件将出现在“选择项”对话框中，程序集将出现在“添加引用”对话框，二者都不出现在工具箱中。

[Toolbox]

TabName

字符串值

为 <程序集文件夹> 中的控件指定默认的工具箱组。 如果此组不存在，将创建它。 如果未指定值，则将控件安装到平台的默认组中。

使用此值可以指定品牌（而不是功能类别）。 对于 WPF 和 Silverlight 自定义控件，请勿以“公用”或“所有控件”类别作为目标。 不能对该值进行本地化。

"TabName"="TailspinToys"

Servicing

键

若要强制工具箱刷新缓存，请在 Toolbox 项内部指定一个新项或新值。 建议通过以下方法来执行此操作：创建一个 Updates 子项，在该子项中，每个已安装的更新都有一个注册值。 缓存刷新仅适用于在 Toolbox 项所属的特定文件夹中找到的控件，而并非适用于所有的框架控件。

在程序集文件夹刷新之后，用户针对该程序集文件夹的控件的工具箱自定义项可能会丢失。

[Updates]

"Update3"="1"

"Update7"="1"

下面的示例注册表脚本注册面向 .NET Framework 4 而且位于“引用程序集”路径中的程序集。 将 ToolboxBrowsableAttribute 设置为 true 的任何控件都将显示在“工具箱”中的**“Tailspin Toys”**选项卡下面。

[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 和 Toolbox 注册表项

通过向控件的设计时元数据中添加 ToolboxBrowsableAttribute 来指定自定义控件是否出现在工具箱中。 有关更多信息，请参见演练：为工具箱图标提供元数据。

**“选择项”对话框用于浏览新程序集并向工具箱中添加新控件。 下表演示了 ToolboxBrowsableAttribute 和 Toolbox 注册表项之间的交互如何确定自定义控件何时出现在“工具箱”和“选择项”**对话框中。

Toolbox 注册表项

无 Toolbox 注册表项

ToolboxBrowsable = true

  • 在“工具箱”中

  • 在“选择项”对话框中

  • 不在工具箱中

  • 在“选择项”对话框中

ToolboxBrowsable = false

  • 不在工具箱中

  • 不在“选择项”对话框中

  • 不在工具箱中

  • 不在“选择项”对话框中

加载设计时程序集

设计器按特定的顺序加载自定义设计时程序集。 这允许用特定于设计器的实现替换泛型实现。 对于在名为 ControlLibrary.dll 的程序集内部署的自定义控件，以下列表显示了设计时程序集的加载顺序。

  1. ControlLibrary.dll（控件程序集）

  2. ControlLibrary.Design.<版本>.dll

  3. Design\ControlLibrary.Design.<版本>.dll

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

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

特定于设计器的程序集替换在泛型程序集内部署的实现。 例如，TailspinToysControlLibrary.VisualStudio.Design.dll 可以替换 TailspinToysControlLibrary.Design.dll 中的实现。

另外，设计时程序集可按照在其文件名中指定的 <版本> 进行加载。 下列规则演示了设计器如何解释 <版本>。

  • 如果 <版本> 的主版本号不同于设计器的框架版本，则不会加载设计程序集。

  • 如果有多个设计时程序集与设计器的框架版本兼容，则设计器将加载未超过设计器框架版本且针对最高框架版本编译的版本。

下表举例说明了一个用 4.1.3.0 框架版本生成的设计器，该设计器加载四个具有不同版本的设计时程序集。

示例设计时程序集的名称

是否加载设计器？

ControlLibrary.Design.3.0.1.0.dll

不能。 不兼容的版本。

ControlLibrary.Design.4.0.1.0.dll

不能。 将加载，但较高的版本可用。

ControlLibrary.Design.4.1.1.0.dll

是。 与设计器版本最接近的版本。

ControlLibrary.Design.4.3.dll

不能。 针对版本高于设计器的框架版本生成。

刷新工具箱

在更新 AssemblyFoldersEx 项所指定的文件夹中的程序集时，可能需要刷新 Visual Studio 工具箱缓存。 缓存中包含工具箱中所显示控件的名称、类别和图标。 缓存中不包括控件或设计时程序集。在编译项目时，任何接受服务的控件或设计时程序集都将自动刷新。

如果以任何方式更改了 AssemblyFoldersEx 项（它的任何值或子项发生了变化），则程序集文件夹的工具箱缓存将进行更新。 在工具箱初始化首次显示工具箱任务窗格时（通常是在启动 Visual Studio 或加载项目时），会发生更新。

若要强制工具箱刷新缓存，请在 Toolbox 项内部指定一个新项或新值。 建议通过以下方法来执行此操作：创建一个 Servicing 子项，在该子项中，每个已安装的更新都有一个注册值。 缓存刷新仅适用于在 Toolbox 项所属的特定文件夹中找到的控件，而并非适用于所有的框架控件。 在程序集文件夹刷新之后，用户针对该程序集文件夹的控件的工具箱自定义项可能会丢失。

请参见

参考

ToolboxBrowsableAttribute

ProvideMetadataAttribute

其他资源

了解 WPF 设计器扩展性

基本扩展性概念

提供设计时元数据