自定义类型和库的 XAML 相关 CLR 特性

  • 项目

本主题介绍由 .NET XAML 服务定义的公共语言运行时 (CLR) 特性。 它还介绍在 .NET 中定义，并且具有适用于应用程序到程序集或类型的 XAML 相关方案的其他 CLR 特性。 使程序集、类型或成员具有这些 CLR 特性可提供与类型相关的 XAML 类型系统信息。 信息会提供给使用 .NET XAML 服务直接或通过专用 XAML 读取器和 XAML 编写器处理 XAML 节点流的任何 XAML 使用者。

使用 CLR 特性需要使用整体 CLR 来定义类型，否则此类特性会不可用。 如果使用 CLR 定义后备类型，则 .NET XAML 服务 XAML 编写器使用的默认 XAML 架构上下文可以通过针对后备程序集的反射来读取 CLR 特性。

以下部分介绍可应用于自定义类型或自定义成员的 XAML 相关特性。 每个 CLR 特性都传达与 XAML 类型系统相关的信息。 在加载路径中，特性化信息可帮助 XAML 读取器形成有效的 XAML 节点流，或是可帮助 XAML 编写器生成有效的对象图。 在保存路径中，特性化信息可帮助 XAML 读取器形成用于重新构建 XAML 类型系统信息的有效 XAML 节点流；或是为 XAML 编写器或其他 XAML 使用者声明序列化提示或要求。

AmbientAttribute

参考文档：AmbientAttribute

适用范围：支持可附加属性的类、属性或 get 访问器成员。

参数：无

AmbientAttribute 指示属性或采用特性化类型的所有属性应在 XAML 中的环境属性概念下进行解释。 环境概念涉及 XAML 处理器如何确定成员的类型所有者。 环境属性是这样一种属性：创建对象图时，值应在分析器上下文中可用，但对于所创建的即时 XAML 节点集，典型的类型-成员查找会暂停。

环境概念可以应用于可附加成员，按照 CLR 特性定义 AttributeTargets 的方式，这些成员不表示为属性。 方法特性用法应该仅应用于对 XAML 支持可附加用法的 get 访问器。

ConstructorArgumentAttribute

参考文档：ConstructorArgumentAttribute

适用范围：类

参数：一个字符串，指定与单个构造函数参数匹配的属性的名称。

ConstructorArgumentAttribute 指定可以使用非无参数构造函数语法来初始化对象，而且由指定名称的属性提供构造信息。 此信息主要用于 XAML 序列化。 有关详细信息，请参阅 ConstructorArgumentAttribute。

ContentPropertyAttribute

参考文档：ContentPropertyAttribute

适用范围：类

参数：一个字符串，指定特性化类型的成员的名称。

ContentPropertyAttribute 指示由参数命名的属性应用作该类型的 XAML 内容属性。 XAML 内容属性定义会继承到可分配给定义类型的所有派生类型。 可以通过对特定派生类型应用 ContentPropertyAttribute 来重写特定派生类型的定义。

对于用作 XAML 内容属性的属性，可以在 XAML 用法中省略该属性的属性元素标记。 通常会指定为内容和包含模型提升简化 XAML 标记的 XAML 内容属性。 由于只能将一个成员指定为 XAML 内容属性，因此在应将一个类型的多个容器属性中的哪一个指定为 XAML 内容属性方面，有时可进行一些设计考虑。 其他容器属性必须与显式属性元素一起使用。

在 XAML 节点流中，XAML 内容属性仍使用 XamlMember 的属性名称生成 StartMember 和 EndMember 节点。 若要确定成员是否为 XAML 内容属性，请检查来自 StartObject 位置的 XamlType 值并获取 ContentProperty 的值。

ContentWrapperAttribute

参考文档：ContentWrapperAttribute

适用范围：类，特别是集合类型。

参数：一个 Type，指定要用作外部内容的内容包装类型的类型。

ContentWrapperAttribute 指定将用于包装外部内容的关联集合类型的一个或多个类型。 外部内容是指以下用例：内容属性类型上的类型系统约束不捕获拥有的类型的 XAML 用法会支持的所有可能内容用例。 例如，对特定类型的内容的 XAML 支持可能支持强类型泛型 Collection<T> 中的字符串。 内容包装器可用于将预先存在的标记约定迁移到 XAML 的集合可分配值概念中，例如迁移与文本相关的内容模型。

若要指定多个内容包装器类型，请多次应用该特性。

DependsOnAttribute

参考文档：DependsOnAttribute

适用范围：属性

参数：一个字符串，指定特性化类型的另一个成员的名称。

DependsOnAttribute 指示特性化属性依赖于另一个属性的值。 将此特性应用于属性定义可确保先在 XAML 对象写入中处理依赖属性。 使用 DependsOnAttribute 可指定指定类型上属性的例外用例，其中必须遵循特定分析顺序才能创建有效对象。

可以将多个 DependsOnAttribute 用例应用于属性定义。

MarkupExtensionReturnTypeAttribute

参考文档：MarkupExtensionReturnTypeAttribute

适用范围：应为 MarkupExtension 派生类型的类。

参数：一个 Type，指定应作为特性化 MarkupExtension 的 ProvideValue 结果的最精确类型。

有关详细信息，请参阅 XAML 的标记扩展概述。

NameScopePropertyAttribute

参考文档：NameScopePropertyAttribute

适用范围：类

参数：支持两种形式的特性：

  • 一个字符串，指定特性化类型的属性的名称。

  • 一个指定属性名称的字符串，以及一个用于定义命名属性的 Type 类型。 此形式用于将可附加成员指定为 XAML 名称范围属性。

NameScopePropertyAttribute 指定为特性化类提供 XAML 名称范围值的属性。 XAML 名称范围属性应引用实现 INameScope 并保存实际 XAML 名称范围、其存储和行为的对象。

RuntimeNamePropertyAttribute

参考文档：RuntimeNamePropertyAttribute

适用范围：类

参数：一个字符串，指定特性化类型的运行时名称属性的名称。

RuntimeNamePropertyAttribute 报告映射到 XAML x:Name 指令的特性化类型的属性。 该属性必须属于类型 String，并且必须可进行读/写。

定义会继承到可分配给定义类型的所有派生类型。 可以通过对特定派生类型应用 RuntimeNamePropertyAttribute 来重写特定派生类型的定义。

TrimSurroundingWhitespaceAttribute

参考文档：TrimSurroundingWhitespaceAttribute

适用范围：类型

参数：无。

TrimSurroundingWhitespaceAttribute 应用于可能在空白重要内容（由具有 WhitespaceSignificantCollectionAttribute 的集合保持的内容）中显示为子元素的特定类型。 TrimSurroundingWhitespaceAttribute 主要与保存路径相关，但可通过检查 XamlType.TrimSurroundingWhitespace 在加载路径的 XAML 类型系统中进行使用。 有关详细信息，请参阅 XAML 中的空白处理。

TypeConverterAttribute

参考文档：TypeConverterAttribute

适用范围：类、属性、方法（唯一的 XAML 有效方法用例是支持可附加成员的 get 访问器）。

参数：TypeConverter 的 Type。

XAML 上下文中的 TypeConverterAttribute 引用自定义 TypeConverter。 此 TypeConverter 为自定义类型或该类型的成员提供类型转换行为。

可将 TypeConverterAttribute 特性应用于类型，从而引用类型转换器实现。 可以在类、结构或接口上为 XAML 定义类型转换器。 无需为枚举提供类型转换，该转换处于本机启用状态。

类型转换器应能够从用于标记中的特性或初始化文本的字符串转换为预期目标类型。 有关详细信息，请参阅 TypeConverters 和 XAML。

还可以在特定属性上建立 XAML 的类型转换器行为，而不是应用于某个类型的所有值。 在这种情况下，将 TypeConverterAttribute 应用于属性定义（外部定义，而不是特定 get 和 set 定义）。

可以通过将 TypeConverterAttribute 应用于支持 XAML 用法的 get 方法访问器，来分配自定义可附加成员的 XAML 用法的类型转换器行为。

与 TypeConverter 类似，TypeConverterAttribute 在 XAML 存在之前便存在于 .NET 中，并且类型转换器模型可提供其他用途。 若要引用和使用 TypeConverterAttribute，必须完全限定它或是提供用于 System.ComponentModel 的 using 语句。 还会在项目中包含系统程序集。

UidPropertyAttribute

参考文档：UidPropertyAttribute

适用范围：类

参数：一个按名称引用相关属性的字符串。

指示为 x:Uid 指令提供别名的类的 CLR 属性。

UsableDuringInitializationAttribute

参考文档：UsableDuringInitializationAttribute

适用范围：类

参数：一个布尔值。 如果用于特性的预期用途，则值应设置为 true。

指示在 XAML 对象图创建期间是否自上而下生成类型。 这是一个高级概念，可能与编程模型的定义密切相关。 有关详细信息，请参阅 UsableDuringInitializationAttribute。

ValueSerializerAttribute

参考文档：ValueSerializerAttribute

适用范围：类、属性、方法（唯一的 XAML 有效方法用例是支持可附加成员的 get 访问器）。

参数：一个 Type，指定在序列化特性化类型的所有属性或特定特性化属性时要使用的值序列化程序支持类。

ValueSerializer 指定一个值序列化类，该类需要的状态和上下文比 TypeConverter 更多。 ValueSerializer 可以通过对可附加成员的静态 get 访问器方法应用 ValueSerializerAttribute 特性来与可附加成员关联。 值序列化也适用于枚举、接口和结构，但不适用于委托。

WhitespaceSignificantCollectionAttribute

参考文档：WhitespaceSignificantCollectionAttribute

适用范围：类，特别是应托管混合内容的集合类型，其中对象元素周围的空白对于 UI 表示形式可能十分重要。

参数：无。

WhitespaceSignificantCollectionAttribute 指示集合类型应由 XAML 处理器作为重要空白进行处理，这会影响集合中 XAML 节点流的值节点的构造。 有关详细信息，请参阅 XAML 中的空白处理。

XamlDeferLoadAttribute

参考文档：XamlDeferLoadAttribute

适用范围：类、属性。

参数：支持两种特性形式，即作为字符串的类型，或作为 Type 的类型。 请参阅 XamlDeferLoadAttribute。

指示类或属性具有 XAML 的延迟加载用法（例如模板行为），并报告启用延迟行为的类及其目标/内容类型。

XamlSetMarkupExtensionAttribute

参考文档：XamlSetMarkupExtensionAttribute

适用范围：类

参数：为回调命名。

指示类可以使用标记扩展为一个或多个属性提供值，并引用 XAML 编写器在对类的任何属性执行标记扩展设置操作之前应调用的处理程序。

XamlSetTypeConverterAttribute

参考文档：XamlSetTypeConverterAttribute

适用范围：类

参数：为回调命名。

指示类可以使用类型转换器为一个或多个属性提供值，并引用 XAML 编写器在对类的任何属性执行类型转换器设置操作之前应调用的处理程序。

XmlLangPropertyAttribute

参考文档：XmlLangPropertyAttribute

适用范围：类

参数：一个字符串，指定要向特性化类型的 xml:lang 提供别名的属性名称。

XmlLangPropertyAttribute 报告映射到 XML lang 指令的特性化类型的属性。 该属性不一定属于类型 String，但必须可通过字符串进行赋值（可以通过将类型转换器与属性的类型或特定属性关联来实现赋值）。 该属性必须可进行读/写。

映射 xml:lang 的方案是使运行时对象模型可以访问 XML 指定的语言信息，而无需专门使用 XMLDOM 进行处理。

定义会继承到可分配给定义类型的所有派生类型。 可以通过对特定派生类型应用 XmlLangPropertyAttribute 来重写特定派生类型的定义，不过这是不常见的方案。

以下部分介绍不应用于类型或成员定义，而是应用于程序集的 XAML 相关特性。 这些特性与定义包含要在 XAML 中使用的自定义类型的库的总体目标相关。 某些特性不一定会直接影响 XAML 节点流，而是在节点流中传递以供其他使用者使用。 信息的使用者包括需要 XAML 命名空间信息和关联前缀信息的设计环境或序列化过程。 XAML 架构上下文（包括 .NET XAML 服务默认设置）也使用此信息。

XmlnsCompatibleWithAttribute

参考文档：XmlnsCompatibleWithAttribute

参数：

  • 一个字符串，指定要归入的 XAML 命名空间的标识符。

  • 一个字符串，指定来自上一个参数的 XAML 命名空间可以归入的 XAML 命名空间的标识符。

    XmlnsCompatibleWithAttribute 指定 XAML 命令空间可归入其他 XAML 命令空间。 通常，先前定义的 XmlnsDefinitionAttribute 中指示了包含 XAML 命令空间。 此方法可用于对库中的 XAML 词汇进行版本控制，并使它与以前针对早期进行版本控制的词汇定义的标记兼容。

XmlnsDefinitionAttribute

参考文档：XmlnsDefinitionAttribute

参数：

  • 一个字符串，指定要定义的 XAML 命名空间的标识符。

  • 一个命名 CLR 命名空间的字符串。 CLR 命名空间应在你的程序集中定义公共类型，并且至少应有一种 CLR 命名空间类型应该用于 XAML。

    XmlnsDefinitionAttribute 指定 XAML 命名空间与 CLR 命名空间之间按程序集进行的映射，然后 XAML 对象编写器或 XAML 架构上下文将其用于类型解析。

    可以向程序集应用多个 XmlnsDefinitionAttribute。 这样做的原因可能是以下原因的任何组合：

  • 库设计包含多个用于对运行时 API 访问进行逻辑组织的 CLR 命名空间；但是，你希望这些命名空间中的所有类型都可通过引用相同 XAML 命名空间来使用 XAML。 在这种情况下，可以使用相同的 XmlNamespace 值但不同的 ClrNamespace 值来应用多个 XmlnsDefinitionAttribute 特性。 如果要为 XAML 命名空间定义映射，而你的框架或应用程序打算在常见用法中将其作为默认 XAML 命名空间，这特别有用。

  • 库设计包含多个 CLR 命名空间，并且你希望在这些 CLR 命名空间中的类型用法之间进行有意的 XAML 命名空间分隔。

  • 你在程序集中定义了一个 CLR 命名空间，并希望可通过多个 XAML 命名空间访问它。 当你通过相同代码库支持多个词汇时，会出现这种情况。

  • 你在一个或多个 CLR 命名空间中定义 XAML 语言支持。 在这种情况下，XmlNamespace 值应为 http://schemas.microsoft.com/winfx/2006/xaml。

XmlnsPrefixAttribute

参考文档：XmlnsPrefixAttribute

参数：

  • 一个指定 XAML 命名空间的标识符的字符串。

  • 一个指定建议前缀的字符串。

    XmlnsDefinitionAttribute 指定要用于 XAML 命名空间的建议前缀。 当在由 .NET XAML 服务 XamlXmlWriter 序列化的 XAML 文件中编写元素和属性时，或者当 XAML 实现库与具有 XAML 编辑功能的设计环境交互时，前缀非常有用。

    可以向程序集应用多个 XmlnsPrefixAttribute。 这样做的原因可能是以下原因的任何组合：

  • 程序集为多个 XAML 命名空间定义类型。 在这种情况下，为每个 XAML 命名空间定义不同的前缀值。

  • 支持多个词汇，并且对每个词汇和 XAML 命名空间使用不同的前缀。

  • 在程序集中定义 XAML 语言支持，并具有一个用于 http://schemas.microsoft.com/winfx/2006/xaml 的 XmlnsDefinitionAttribute。 在这种情况下，通常应提升前缀 x。

注意

.NET XAML 服务还定义 XAML 相关特性 RootNamespaceAttribute。 此特性是用于项目系统支持的程序集级别特性，它与 XAML 自定义类型无关。

另请参阅