Edit

XAML-related CLR attributes for custom types and libraries

  • Article

This topic describes the common language runtime (CLR) attributes that are defined by .NET XAML Services. It also describes other CLR attributes that are defined in .NET that have a XAML-related scenario for application to assemblies or types. Attributing assemblies, types, or members with these CLR attributes provides XAML type system information related to your types. Information is provided to any XAML consumer that uses .NET XAML Services for processing the XAML node stream directly or through the dedicated XAML readers and XAML writers.

Using CLR attributes entails that you are using the overall CLR to define your types, otherwise such attributes are not available. If you use the CLR to define type backing, then the default XAML schema context used by .NET XAML Services XAML writers can read CLR attribution through reflection against backing assemblies.

The following sections describe the XAML-related attributes that you can apply to custom types or custom members. Each CLR attribute communicates information that is relevant to a XAML type system. In the load path, the attributed information either helps the XAML reader form a valid XAML node stream, or it helps the XAML writer produce a valid object graph. In the save path, the attributed information either helps the XAML reader form a valid XAML node stream that reconstitutes XAML type system information; or it declares serialization hints or requirements for the XAML writer or other XAML consumers.

AmbientAttribute

Reference Documentation: AmbientAttribute

Applies to: Class, property, or get accessor members that support attachable properties.

Arguments: None

AmbientAttribute indicates that the property, or all properties that take the attributed type, should be interpreted under the ambient property concept in XAML. The ambient concept relates to how XAML processors determine type owners of members. An ambient property is a property where the value is expected to be available in the parser context when creating an object graph, but where typical type-member lookup is suspended for the immediate XAML node set being created.

The ambient concept can be applied to attachable members, which are not represented as properties in terms of how CLR attribution defines AttributeTargets. The method attribution usage should be applied only for a get accessor that supports attachable usage for XAML.

ConstructorArgumentAttribute

Reference Documentation: ConstructorArgumentAttribute

Applies to: Class

Arguments: A string that specifies the name of the property that matches a single constructor argument.

ConstructorArgumentAttribute specifies that an object can be initialized by using a non-parameterless constructor syntax, and that a property of the specified name supplies construction information. This information is primarily for XAML serialization. For more information, see ConstructorArgumentAttribute.

ContentPropertyAttribute

Reference Documentation: ContentPropertyAttribute

Applies to: Class

Arguments: A string that specifies the name of a member of the attributed type.

ContentPropertyAttribute indicates that the property as named by the argument should serve as the XAML content property for that type. The XAML content property definition inherits to all derived types that are assignable to the defining type. You can override the definition on a specific derived type by applying ContentPropertyAttribute on the specific derived type.

For the property that serves as the XAML content property, property element tagging for the property can be omitted in the XAML usage. Typically, you designate XAML content properties that promote a streamlined XAML markup for your content and containment models. Because only one member can be designated as the XAML content property, you sometimes have design choices to make regarding which of several container properties of a type should be designated as the XAML content property. The other container properties must be used with explicit property elements.

In the XAML node stream, XAML content properties still produce StartMember and EndMember nodes, using the name of the property for the XamlMember. To determine whether a member is the XAML content property, examine the XamlType value from the StartObject position and obtain the value of ContentProperty.

ContentWrapperAttribute

Reference Documentation: ContentWrapperAttribute

Applies to: Class, specifically collection types.

Arguments: A Type that specifies the type to use as the content wrapper type for foreign content.

ContentWrapperAttribute specifies one or more types on the associated collection type that will be used to wrap foreign content. Foreign content refers to cases where the type system constraints on the type of the content property do not capture all of the possible content cases that XAML usage for the owning type would support. For example, XAML support for content of a particular type might support strings in a strongly typed generic Collection<T>. Content wrappers are useful for migrating pre-existing markup conventions into XAML's conception of assignable values for collections, such as migrating text-related content models.

To specify more than one content wrapper type, apply the attribute multiple times.

DependsOnAttribute

Reference Documentation: DependsOnAttribute

Applies to: Property

Arguments: A string that specifies the name of another member of the attributed type.

DependsOnAttribute indicates that the attributed property depends on the value of another property. Applying this attribute to a property definition ensures that the dependent properties are processed first in XAML object writing. Usages of DependsOnAttribute specify the exceptional cases of properties on types where a specific order of parsing must be followed for valid object creation.

You can apply multiple DependsOnAttribute cases to a property definition.

MarkupExtensionReturnTypeAttribute

Reference Documentation: MarkupExtensionReturnTypeAttribute

Applies to: Class, which is expected to be a MarkupExtension derived type.

Arguments: A Type that specifies the most precise type to expect as the ProvideValue result of the attributed MarkupExtension.

For more information, see Markup Extensions for XAML Overview.

NameScopePropertyAttribute

Reference Documentation: NameScopePropertyAttribute

Applies to: Class

Arguments: Supports two forms of attribution:

  • A string that specifies the name of a property on the attributed type.

  • A string that specifies the name of a property, and a Type for the type that defines the named property. This form is for specifying an attachable member as the XAML namescope property.

NameScopePropertyAttribute specifies a property that provides the XAML namescope value for the attributed class. The XAML namescope property is expected to reference an object that implements INameScope and holds the actual XAML namescope, its store, and its behavior.

RuntimeNamePropertyAttribute

Reference Documentation: RuntimeNamePropertyAttribute

Applies to: Class

Arguments: A string that specifies the name of the run-time name property on the attributed type.

RuntimeNamePropertyAttribute reports a property of the attributed type that maps to the XAML x:Name Directive. The property must be of type String and must be read/write.

The definition inherits to all derived types that are assignable to the defining type. You can override the definition on a specific derived type by applying RuntimeNamePropertyAttribute on the specific derived type.

TrimSurroundingWhitespaceAttribute

Reference Documentation: TrimSurroundingWhitespaceAttribute

Applies to: Types

Arguments: None.

TrimSurroundingWhitespaceAttribute is applied to specific types that might appear as child elements within white-space significant content (content held by a collection that has WhitespaceSignificantCollectionAttribute). TrimSurroundingWhitespaceAttribute is mainly relevant to the save path, but is available in the XAML type system in the load path by examining XamlType.TrimSurroundingWhitespace. For more information, see White-space processing in XAML.

TypeConverterAttribute

Reference Documentation: TypeConverterAttribute

Applies to: Class, property, method (the only XAML-valid method case is a get accessor that supports an attachable member).

Arguments: The Type of the TypeConverter.

TypeConverterAttribute in a XAML context references a custom TypeConverter. This TypeConverter provides type conversion behavior for custom types, or members of that type.

Apply the TypeConverterAttribute attribute to your type, referencing your type converter implementation. You can define type converters for XAML on classes, structures, or interfaces. You do not need to provide type conversion for enumerations, that conversion is enabled natively.

Your type converter should be able to convert from a string that is used for attributes or initialization text in markup, into your intended destination type. For more information, see TypeConverters and XAML.

Rather than applying to all values of a type, a type converter behavior for XAML can also be established on a specific property. In this case, you apply TypeConverterAttribute to the property definition (the outer definition, not the specific get and set definitions).

A type converter behavior for XAML usage of a custom attachable member can be assigned by applying TypeConverterAttribute to the get method accessor that supports the XAML usage.

Similar to TypeConverter, TypeConverterAttribute existed in .NET prior to the existence of XAML, and the type converter model served other purposes. In order to reference and use TypeConverterAttribute, you must fully qualify it or provide a using statement for System.ComponentModel. Also include the System assembly in your project.

UidPropertyAttribute

Reference Documentation: UidPropertyAttribute

Applies to: Class

Arguments: A string that references the relevant property by name.

Indicates the CLR property of a class that aliases the x:Uid Directive.

UsableDuringInitializationAttribute

Reference Documentation: UsableDuringInitializationAttribute

Applies to: Class

Arguments: A Boolean. If used for the attribute's intended purpose, the value should be set to true.

Indicates whether the type is built top-down during XAML object graph creation. This is an advanced concept, which is probably closely related to the definition of your programming model. For more information, see UsableDuringInitializationAttribute.

ValueSerializerAttribute

Reference Documentation: ValueSerializerAttribute

Applies to: Class, property, method (the only XAML-valid method case is a get accessor that supports an attachable member).

Arguments: A Type that specifies the value serializer support class to use when serializing all properties of the attributed type, or the specific attributed property.

ValueSerializer specifies a value serialization class that requires more state and context than a TypeConverter does. ValueSerializer can be associated with an attachable member by applying the ValueSerializerAttribute attribute on the static get accessor method for the attachable member. Value serialization is also applicable for enumerations, interfaces, and structures, but not for delegates.

WhitespaceSignificantCollectionAttribute

Reference Documentation: WhitespaceSignificantCollectionAttribute

Applies to: Class, specifically collection types that are expected to host mixed content, where white space around object elements might be significant for UI representation.

Arguments: None.

WhitespaceSignificantCollectionAttribute indicates that a collection type should be processed as white-space significant by a XAML processor, which influences the construction of the XAML node stream's value nodes within the collection. For more information, see White-space processing in XAML.

XamlDeferLoadAttribute

Reference Documentation: XamlDeferLoadAttribute

Applies to: Class, property.

Arguments: Supports two attribution forms types as strings, or types as Type. See XamlDeferLoadAttribute.

Indicates that a class or property has a deferred load usage for XAML (such as a template behavior), and reports the class that enables the deferring behavior and its destination/content type.

XamlSetMarkupExtensionAttribute

Reference Documentation: XamlSetMarkupExtensionAttribute

Applies to: Class

Arguments: Names the callback.

Indicates that a class can use a markup extension to provide a value for one or more of its properties, and references a handler that a XAML writer should call before performing a markup extension set operation on any property of the class.

XamlSetTypeConverterAttribute

Reference Documentation: XamlSetTypeConverterAttribute

Applies to: Class

Arguments: Names the callback.

Indicates that a class can use a type converter to provide a value for one or more of its properties, and references a handler that a XAML writer should call before performing a type converter set operation on any property of the class.

XmlLangPropertyAttribute

Reference Documentation: XmlLangPropertyAttribute

Applies to: Class

Arguments: A string that specifies the name of the property to alias to xml:lang on the attributed type.

XmlLangPropertyAttribute reports a property of the attributed type that maps to the XML lang directive. The property is not necessarily of type String but must be assignable from a string (assignment could be accomplished by associating a type converter with the property's type or with the specific property). The property must be read/write.

The scenario for mapping xml:lang is so that a runtime object model has access to XML-specified language information without specifically processing with an XMLDOM.

The definition inherits to all derived types that are assignable to the defining type. You can override the definition on a specific derived type by applying XmlLangPropertyAttribute on the specific derived type, although that is an uncommon scenario.

The following sections describe the XAML-related attributes that are not applied to types or member definitions, but are instead applied to assemblies. These attributes are pertinent to the overall goal of defining a library that contains custom types to use in XAML. Some of the attributes do not necessarily influence the XAML node stream directly, but are passed on in the node stream for other consumers to use. Consumers for the information include design environments or serialization processes that need XAML namespace information and associated prefix information. A XAML schema context (including the .NET XAML Services default) also uses this information.

XmlnsCompatibleWithAttribute

Reference Documentation: XmlnsCompatibleWithAttribute

Arguments:

  • A string that specifies the identifier of the XAML namespace to subsume.

  • A string that specifies the identifier of the XAML namespace that can subsume the XAML namespace from the previous argument.

    XmlnsCompatibleWithAttribute specifies that a XAML namespace can be subsumed by another XAML namespace. Typically, the subsuming XAML namespace is indicated in a previously defined XmlnsDefinitionAttribute. This technique can be used for versioning a XAML vocabulary in a library and to make it compatible with previously defined markup against the earlier versioned vocabulary.

XmlnsDefinitionAttribute

Reference Documentation: XmlnsDefinitionAttribute

Arguments:

  • A string that specifies the identifier of the XAML namespace to define.

  • A string that names a CLR namespace. The CLR namespace should define public types in your assembly, and at least one of the CLR namespace types should be intended for XAML usage.

    XmlnsDefinitionAttribute specifies a mapping on a per-assembly basis between a XAML namespace and a CLR namespace, which is then used for type resolution by a XAML object writer or XAML schema context.

    More than one XmlnsDefinitionAttribute can be applied to an assembly. This might be done for any combination of the following reasons:

  • The library design contains multiple CLR namespaces for logical organization of run-time API access; however, you want all types in those namespaces to be XAML-usable by referencing the same XAML namespace. In this case, you apply several XmlnsDefinitionAttribute attributes using the same XmlNamespace value but different ClrNamespace values. This is especially useful if you are defining mappings for the XAML namespace that your framework or application intends to be the default XAML namespace in common usage.

  • The library design contains multiple CLR namespaces, and you want a deliberate XAML namespace separation between the usages of types in those CLR namespaces.

  • You define a CLR namespace in the assembly, and you want it to be accessible through more than one XAML namespace. This scenario occurs when you are supporting multiple vocabularies with the same codebase.

  • You define XAML language support in one or more CLR namespaces. In this case, the XmlNamespace value should be http://schemas.microsoft.com/winfx/2006/xaml.

XmlnsPrefixAttribute

Reference Documentation: XmlnsPrefixAttribute

Arguments:

  • A string that specifies the identifier of a XAML namespace.

  • A string that specifies a recommended prefix.

    XmlnsDefinitionAttribute specifies a recommended prefix to use for a XAML namespace. The prefix is useful when writing elements and attributes in a XAML file that is serialized by .NET XAML Services XamlXmlWriter, or when a XAML-implementing library interacts with a design environment that has XAML editing features.

    More than one XmlnsPrefixAttribute can be applied to an assembly. This might be done for any combination of the following reasons:

  • Your assembly defines types for more than one XAML namespace. In this case, define different prefix values for each XAML namespace.

  • You are supporting multiple vocabularies, and you use different prefixes for each vocabulary and XAML namespace.

  • You define XAML language support in the assembly and have a XmlnsDefinitionAttribute for http://schemas.microsoft.com/winfx/2006/xaml. In this case, you typically should promote the prefix x.

Note

.NET XAML Services also defines the XAML-related attribute RootNamespaceAttribute. This attribute is an assembly-level attribute for project system support, and it is not relevant for XAML custom types.

See also