XAML-bezogene CLR-Attribute für benutzerdefinierte Typen und Bibliotheken

  • Artikel

In diesem Thema werden die CLR-Attribute (Common Language Runtime) beschrieben, die von den .NET XAML-Diensten definiert werden. Darüber hinaus werden weitere CLR-Attribute beschrieben, die in .NET definiert sind, und es wird ein XAML-bezogenes Szenario für die Anwendung auf Assemblys oder Typen vorgestellt. Wenn Sie Assemblys, Typen oder Member mit diesen CLR-Attributen versehen, werden Informationen zum XAML-Typsystem für Ihre Typen bereitgestellt. Die Informationen werden jedem XAML-Consumer zur Verfügung gestellt, der die .NET XAML-Dienste nutzt, um den XAML-Knotenstream direkt oder über die dedizierten XAML-Reader und XAML-Writer zu verarbeiten.

Die Verwendung von CLR-Attributen setzt voraus, dass Sie die Common Language Runtime zur Definition Ihrer Typen insgesamt verwenden, andernfalls sind solche Attribute nicht verfügbar. Wenn Sie die CLR zur Definition der Typunterstützung verwenden, kann der von einem XAML-Writer der .NET XAML-Dienste verwendete Standard-XAML-Schemakontext die CLR-Attributverwendung durch Reflexion der unterstützenden Assemblys lesen.

In den folgenden Abschnitten werden die XAML-bezogenen Attribute beschrieben, die Sie auf benutzerdefinierte Typen oder benutzerdefinierte Member anwenden können. Jedes CLR-Attribut stellt Informationen bereit, die für ein XAML-Typsystem relevant sind. Im Ladepfad helfen die zugewiesenen Informationen entweder dem XAML-Reader, einen gültigen XAML-Knotenstream zu erzeugen, oder sie helfen dem XAML-Writer, einen gültigen Objektgraphen zu erstellen. Im Speicherpfad unterstützen die zugewiesenen Informationen entweder den XAML-Reader beim Erzeugen eines gültigen XAML-Knotenstreams, der die XAML-Typsysteminformationen wiederherstellt, oder sie deklarieren Serialisierungshinweise oder -anforderungen für den XAML-Writer oder andere XAML-Consumer.

AmbientAttribute

Referenzdokumentation:AmbientAttribute

Gilt für: Klasse, Eigenschaft oder get-Accessormember, die angefügte Eigenschaften unterstützen.

Argumente: Keine

AmbientAttribute gibt an, dass die Eigenschaft oder alle Eigenschaften, die den mit Attributen versehenen Typ verwenden, gemäß dem Konzept der Umgebungseigenschaften in XAML interpretiert werden sollen. Das Umgebungskonzept bezieht sich darauf, wie XAML-Prozessoren Typbesitzer von Membern bestimmen. Eine Umgebungseigenschaft ist eine Eigenschaft, deren Wert bei der Erstellung eines Objektgraphen im Parserkontext erwartet wird, bei der aber die typische Typmembersuche für die unmittelbar zu erstellende XAML-Knotengruppe ausgesetzt ist.

Das Umgebungskonzept kann auf anfügbare Member angewendet werden, die nicht als Eigenschaften im Sinne der CLR-Attributdefinition von AttributeTargets dargestellt werden. Die Methodenattributverwendung sollte nur für einen get-Accessor angewendet werden, der die Anfügung für XAML unterstützt.

ConstructorArgumentAttribute

Referenzdokumentation:ConstructorArgumentAttribute

Gilt für: Klasse

Argumente: Eine Zeichenfolge, die den Namen der Eigenschaft angibt, die einem einzelnen Konstruktorargument entspricht.

ConstructorArgumentAttribute gibt an, dass ein Objekt mit der Syntax eines nicht parameterlosen Konstruktors initialisiert werden kann und dass eine Eigenschaft mit dem angegebenen Namen Informationen zur Erstellung bereitstellt. Diese Informationen sind in erster Linie für die XAML-Serialisierung vorgesehen. Weitere Informationen finden Sie unter ConstructorArgumentAttribute.

ContentPropertyAttribute

Referenzdokumentation:ContentPropertyAttribute

Gilt für: Klasse

Argumente: Eine Zeichenfolge, die den Namen eines Members des attributierten Typs angibt.

ContentPropertyAttribute gibt an, dass die im Argument genannte Eigenschaft als XAML-Inhaltseigenschaft für diesen Typ dienen soll. Die Definition der XAML-Inhaltseigenschaft wird an alle abgeleiteten Typen vererbt, die dem definierenden Typ zugewiesen werden können. Sie können die Definition für einen bestimmten abgeleiteten Typ außer Kraft setzen, indem Sie ContentPropertyAttribute auf den spezifischen abgeleiteten Typ anwenden.

Bei der Eigenschaft, die als XAML-Inhaltseigenschaft dient, kann das Eigenschaftselement-Tagging für die Eigenschaft in der XAML-Verwendung weggelassen werden. Üblicherweise legen Sie XAML-Inhaltseigenschaften fest, die ein optimiertes XAML-Markup für Ihre Inhalts- und Einschlussmodelle fördern. Da nur ein Member als XAML-Inhaltseigenschaft festgelegt werden kann, müssen Sie gelegentlich eine Auswahl treffen, welche der verschiedenen Containereigenschaften eines Typs als XAML-Inhaltseigenschaft festgelegt werden soll. Die anderen Containereigenschaften müssen mit expliziten Eigenschaftselementen verwendet werden.

Im XAML-Knotenstream erzeugen XAML-Inhaltseigenschaften weiterhin StartMember- und EndMember-Knoten, wobei der Name der Eigenschaft für den XamlMember verwendet wird. Um zu bestimmen, ob es sich bei einem Member um die XAML-Inhaltseigenschaft handelt, untersuchen Sie den Wert XamlType an der StartObject-Position und ermitteln den Wert von ContentProperty.

ContentWrapperAttribute

Referenzdokumentation:ContentWrapperAttribute

Gilt für: Klasse, insbesondere Auflistungstypen.

Argumente: Ein Type, der den Typ angibt, der als Inhaltswrapper für Fremdinhalte verwendet werden soll.

ContentWrapperAttribute gibt mindestens einen Typ für den zugeordneten Auflistungstyp an, der dazu verwendet wird, Fremdinhalte zu umschließen. Fremdinhalte liegen vor, wenn die Typsystemeinschränkungen für den Typ der Inhaltseigenschaft nicht alle möglichen Inhaltsfälle erfassen, die die XAML-Verwendung für den eigenen Typ unterstützen würde. Zum Beispiel könnte die XAML-Unterstützung für Inhalte eines bestimmten Typs Zeichenfolgen in einem stark typisierten generischen Collection<T> unterstützen. Inhaltswrapper sind nützlich, um bereits vorhandene Markupkonventionen in das XAML-Konzept der zuweisbaren Werte für Auflistungen zu migrieren, z. B. eine Migration von textbezogenen Inhaltsmodellen.

Um mehrere Inhaltswrappertypen anzugeben, wenden Sie das Attribut mehrmals an.

DependsOnAttribute

Referenzdokumentation:DependsOnAttribute

Gilt für: Eigenschaft

Argumente: Eine Zeichenfolge, die den Namen eines weiteren Members des attributierten Typs angibt.

DependsOnAttribute gibt an, dass die attributierte Eigenschaft vom Wert einer anderen Eigenschaft abhängig ist. Wenn Sie dieses Attribut auf eine Eigenschaftsdefinition anwenden, wird sichergestellt, dass die abhängigen Eigenschaften beim Schreiben von XAML-Objekten zuerst verarbeitet werden. Mit DependsOnAttribute werden die Ausnahmefälle von Eigenschaften für Typen angegeben, bei denen für eine gültige Objekterstellung eine bestimmte Analysereihenfolge eingehalten werden muss.

Sie können mehrere DependsOnAttribute-Fälle auf eine Eigenschaftsdefinition anwenden.

MarkupExtensionReturnTypeAttribute

Referenzdokumentation:MarkupExtensionReturnTypeAttribute

Gilt für: Klasse, bei der erwartet wird, dass sie ein abgeleiteter MarkupExtension-Typ ist.

Argumente: Ein Type, der den präzisesten Typ angibt, der als ProvideValue-Ergebnis der attributierten MarkupExtension zu erwarten ist.

Weitere Informationen finden Sie unter Übersicht der Markuperweiterungen für XAML.

NameScopePropertyAttribute

Referenzdokumentation:NameScopePropertyAttribute

Gilt für: Klasse

Argumente: Unterstützt zwei Formen der Attributverwendung:

  • Eine Zeichenfolge, die den Namen einer Eigenschaft für den attributierten Typ angibt.

  • Eine Zeichenfolge, die den Namen einer Eigenschaft angibt, und ein Type für den Typ, der die benannte Eigenschaft definiert. Diese Verwendung dient zur Angabe eines anfügbaren Elements als XAML-Namensbereichseigenschaft.

NameScopePropertyAttribute gibt eine Eigenschaft an, die den XAML-Namensbereichswert für die attributierte Klasse bereitstellt. Es wird erwartet, dass die XAML-Namensbereichseigenschaft auf ein Objekt verweist, das INameScope implementiert und den tatsächlichen XAML-Namensbereich, seinen Speicher und sein Verhalten enthält.

RuntimeNamePropertyAttribute

Referenzdokumentation:RuntimeNamePropertyAttribute

Gilt für: Klasse

Argumente: Eine Zeichenfolge, die den Namen der Laufzeitnamenseigenschaft des attributierten Typs angibt.

RuntimeNamePropertyAttribute meldet eine Eigenschaft des attribuierten Typs, die der XAML-x:Name-Anweisung entspricht. Die Eigenschaft muss den Typ String aufweisen und Lese-/Schreibzugriff zulassen.

Die Definition wird an alle abgeleiteten Typen vererbt, die dem definierenden Typ zugewiesen werden können. Sie können die Definition für einen bestimmten abgeleiteten Typ außer Kraft setzen, indem Sie RuntimeNamePropertyAttribute auf den spezifischen abgeleiteten Typ anwenden.

TrimSurroundingWhitespaceAttribute

Referenzdokumentation:TrimSurroundingWhitespaceAttribute

Gilt für: Typen

Argumente: Keine

TrimSurroundingWhitespaceAttribute wird auf bestimmte Typen angewendet, die als untergeordnete Elemente innerhalb von Inhalten erscheinen können, bei denen der Leerraum relevant ist (Inhalte in einer Auflistung, die WhitespaceSignificantCollectionAttribute enthält). TrimSurroundingWhitespaceAttribute ist hauptsächlich für den Speicherpfad relevant, steht aber im XAML-Typsystem im Ladepfad zur Verfügung, wenn Sie XamlType.TrimSurroundingWhitespace untersuchen. Weitere Informationen finden Sie unter Leerraumverarbeitung in XAML.

TypeConverterAttribute

Referenzdokumentation:TypeConverterAttribute

Gilt für: Klasse, Eigenschaft, Methode (der einzige in XAML gültige Methodenfall ist ein get-Accessor, der anfügbare Member unterstützt).

Argumente: Der Type von TypeConverter.

TypeConverterAttribute in einem XAML-Kontext verweist auf einen benutzerdefinierten TypeConverter. Dieser TypeConverter bietet ein Typkonvertierungsverhalten für benutzerdefinierte Typen oder Member dieses Typs.

Wenden Sie das Attribut TypeConverterAttribute auf Ihren Typ an, und verweisen Sie auf Ihre Typkonverterimplementierung. Sie können Typkonverter für XAML für Klassen, Strukturen oder Schnittstellen definieren. Sie müssen keine Typkonvertierung für Enumerationen bereitstellen, diese Konvertierung ist nativ aktiviert.

Ihr Typkonverter sollte in der Lage sein, eine Zeichenfolge, die für Attribute oder Initialisierungstext im Markup verwendet wird, in den von Ihnen gewünschten Zieltyp zu konvertieren. Weitere Informationen finden Sie unter TypeConverter und XAML.

Anstelle der Anwendung auf alle Werte eines Typs kann das Verhalten eines Typkonverters für XAML auch für eine bestimmte Eigenschaft festgelegt werden. In diesem Fall wenden Sie TypeConverterAttribute auf die Eigenschaftsdefinition an (die äußere Definition, nicht die spezifischen get- und set-Definitionen).

Ein Typkonvertierungsverhalten für die XAML-Verwendung eines benutzerdefinierten anfügbaren Members kann zugewiesen werden, indem TypeConverterAttribute auf den Methodenaccessor get angewendet wird, der die XAML-Verwendung unterstützt.

Ähnlich wie TypeConverter gab es TypeConverterAttribute in .NET bereits vor der Einführung von XAML, und das Typkonvertierungsmodell diente anderen Zwecken. Um TypeConverterAttribute zu referenzieren und zu verwenden, müssen Sie es vollständig qualifizieren oder eine using-Anweisung für System.ComponentModel angeben. Nehmen Sie auch die System-Assembly in Ihr Projekt auf.

UidPropertyAttribute

Referenzdokumentation:UidPropertyAttribute

Gilt für: Klasse

Argumente: Eine Zeichenfolge, die die relevante Eigenschaft anhand ihres Namens referenziert.

Gibt die CLR-Eigenschaft einer Klasse an, die als Alias der x:Uid-Anweisung fungiert.

UsableDuringInitializationAttribute

Referenzdokumentation:UsableDuringInitializationAttribute

Gilt für: Klasse

Argumente: Ein boolescher Wert. Bei Verwendung für den vorgesehenen Zweck des Attributs sollte der Wert auf true festgelegt werden.

Gibt an, ob der Typ bei der Erstellung des XAML-Objektgraphen von oben nach unten aufgebaut wird. Dies ist ein weiterführendes Konzept, das wahrscheinlich eng mit der Definition Ihres Programmiermodells verbunden ist. Weitere Informationen finden Sie unter UsableDuringInitializationAttribute.

ValueSerializerAttribute

Referenzdokumentation:ValueSerializerAttribute

Gilt für: Klasse, Eigenschaft, Methode (der einzige in XAML gültige Methodenfall ist ein get-Accessor, der anfügbare Member unterstützt).

Argumente: Ein Type, der die Klasse angibt, die bei der Serialisierung aller Eigenschaften des attributierten Typs oder der spezifischen attributierten Eigenschaft verwendet werden soll.

ValueSerializer gibt eine Klasse zur Serialisierung von Werten an, die mehr Zustands- und Kontextinformationen erfordert als ein TypeConverter. ValueSerializer kann einem anfügbaren Member zugeordnet werden, indem das ValueSerializerAttribute-Attribut auf die statische get-Accessormethode für den anfügbaren Member angewendet wird. Die Serialisierung von Werten ist auch auf Enumerationen, Schnittstellen und Strukturen anwendbar, aber nicht auf Delegaten.

WhitespaceSignificantCollectionAttribute

Referenzdokumentation:WhitespaceSignificantCollectionAttribute

Gilt für: Klasse, insbesondere Auflistungstypen, von denen erwartet wird, dass sie gemischte Inhalte umfassen, bei denen Leerraum um Objektelemente für die Darstellung auf der Benutzeroberfläche relevant sein kann.

Argumente: Keine

WhitespaceSignificantCollectionAttribute gibt an, dass bei der Verarbeitung eines Auflistungstyps durch einen XAML-Prozessor der Leerraum relevant ist, was sich auf die Erstellung der Wertknoten des XAML-Knotenstreams innerhalb der Auflistung auswirkt. Weitere Informationen finden Sie unter Leerraumverarbeitung in XAML.

XamlDeferLoadAttribute

Referenzdokumentation:XamlDeferLoadAttribute

Gilt für: Klasse, Eigenschaft.

Argumente: Unterstützt zwei Formen der Attributverwendung: Typen als Zeichenfolgen, oder Typen als Type. Siehe XamlDeferLoadAttribute.

Gibt an, dass eine Klasse oder eine Eigenschaft über eine verzögerte Auslastungsverwendung für XAML (z. B. ein Vorlagenverhalten) verfügt, und meldet die Klasse, die das verzögernde Verhalten und seinen Ziel-/Inhaltstyp aktiviert.

XamlSetMarkupExtensionAttribute

Referenzdokumentation:XamlSetMarkupExtensionAttribute

Gilt für: Klasse

Argumente: Benennt den Rückruf.

Gibt an, dass eine Klasse eine Markuperweiterung verwenden kann, um einen Wert für eine oder mehrere ihrer Eigenschaften bereitzustellen, und verweist auf einen Handler, den ein XAML-Writer aufrufen sollte, bevor er eine Markuperweiterung für eine Eigenschaft der Klasse festlegt.

XamlSetTypeConverterAttribute

Referenzdokumentation:XamlSetTypeConverterAttribute

Gilt für: Klasse

Argumente: Benennt den Rückruf.

Gibt an, dass eine Klasse einen Typkonverter verwenden kann, um einen Wert für eine oder mehrere ihrer Eigenschaften bereitzustellen, und verweist auf einen Handler, den ein XAML-Writer aufrufen sollte, bevor er einen Typkonverter für eine Eigenschaft der Klasse festlegt.

XmlLangPropertyAttribute

Referenzdokumentation:XmlLangPropertyAttribute

Gilt für: Klasse

Argumente: Eine Zeichenfolge, die den Namen der Eigenschaft angibt, die als Alias von xml:lang für den attributierten Typ verwendet werden soll.

XmlLangPropertyAttribute meldet eine Eigenschaft des attributierten Typs, die der XML-lang-Anweisung entspricht. Die Eigenschaft muss nicht notwendigerweise den Typ String aufweisen, sondern muss über eine Zeichenfolge zugewiesen werden können (die Zuweisung kann durch die Zuordnung eines Typkonverters zum Typ der Eigenschaft oder zur spezifischen Eigenschaft erfolgen). Die Eigenschaft muss Lese-/Schreibzugriff zulassen.

Das Szenario für die Zuordnung von xml:lang beruht darauf, dass ein Laufzeitobjektmodell Zugriff auf XML-spezifische Sprachinformationen hat, ohne dass eine spezielle Verarbeitung mit XMLDOM erforderlich ist.

Die Definition wird an alle abgeleiteten Typen vererbt, die dem definierenden Typ zugewiesen werden können. Sie können die Definition für einen bestimmten abgeleiteten Typ außer Kraft setzen, indem Sie XmlLangPropertyAttribute auf den spezifischen abgeleiteten Typ anwenden, obwohl dies ein unübliches Szenario ist.

In den folgenden Abschnitten werden die XAML-bezogenen Attribute beschrieben, die nicht auf Typen oder Memberdefinitionen, sondern auf Assemblys angewendet werden. Diese Attribute sind relevant für das allgemeine Ziel der Definition einer Bibliothek, die benutzerdefinierte Typen zur Verwendung in XAML enthält. Einige der Attribute beeinflussen den XAML-Knotenstream nicht unbedingt direkt, sondern werden im Knotenstream weitergegeben, damit andere Consumer sie verwenden können. Zu den Consumern dieser Informationen gehören Entwurfsumgebungen oder Serialisierungsprozesse, die XAML-Namespace-Informationen und zugehörige Präfixinformationen benötigen. Ein XAML-Schemakontext (einschließlich des .NET XAML-Dienststandards) verwendet diese Informationen ebenfalls.

XmlnsCompatibleWithAttribute

Referenzdokumentation:XmlnsCompatibleWithAttribute

Argumente:

  • Eine Zeichenfolge, die den Bezeichner des XAML-Namespace angibt, der subsumiert werden soll.

  • Eine Zeichenfolge, die den Bezeichner des XAML-Namespace angibt, der den XAML-Namespace aus dem vorherigen Argument subsumieren kann.

    XmlnsCompatibleWithAttribute gibt an, dass ein XAML-Namespace von einem anderen XAML-Namespace subsumiert werden kann. In der Regel wird der zusammenfassende XAML-Namespace in einem zuvor definierten XmlnsDefinitionAttribute angegeben. Diese Technik kann dazu verwendet werden, ein XAML-Vokabular in einer Bibliothek zu versionieren und anhand des vorab definierten Vokabulars Kompatibilität mit zuvor definierten Markup herzustellen.

XmlnsDefinitionAttribute

Referenzdokumentation:XmlnsDefinitionAttribute

Argumente:

  • Eine Zeichenfolge, die den Bezeichner des zu definierenden XAML-Namespace angibt.

  • Eine Zeichenfolge, die einen CLR-Namespace benennt. Der CLR-Namespace sollte öffentliche Typen in Ihrer Assembly definieren, und mindestens einer der CLR-Namespacetypen sollte für die Verwendung in XAML vorgesehen sein.

    XmlnsDefinitionAttribute gibt eine Zuordnung pro Assembly zwischen einem XAML-Namespace und einem CLR-Namespace an, die dann für die Typauflösung durch einen XAML-Objektwriter oder XAML-Schemakontext verwendet wird.

    Auf eine Assembly kann mehr als ein XmlnsDefinitionAttribute angewendet werden. Dies kann aus einer beliebigen Kombination der folgenden Gründe geschehen:

  • Der Bibliotheksentwurf enthält mehrere CLR-Namespaces für die logische Organisation des API-Zugriffs zur Laufzeit. Sie möchten jedoch, dass alle Typen in diesen Namespaces in XAML verwendet werden können, indem Sie auf denselben XAML-Namespace verweisen. In diesem Fall wenden Sie mehrere XmlnsDefinitionAttribute-Attribute an, die denselben XmlNamespace-Wert, aber unterschiedliche ClrNamespace-Werte aufweisen. Dies ist besonders nützlich, wenn Sie Zuordnungen für den XAML-Namespace definieren, den Ihr Framework oder Ihre Anwendung als Standard-XAML-Namespace für den allgemeinen Gebrauch vorsieht.

  • Der Bibliotheksentwurf enthält mehrere CLR-Namespaces, und Sie möchten für eine bewusste XAML-Namespacetrennung zwischen der Verwendung von Typen in diesen CLR-Namespaces sorgen.

  • Sie definieren einen CLR-Namespace in der Assembly und möchten, dass dieser über mehr als einen XAML-Namespace zugänglich ist. Dieses Szenario tritt auf, wenn Sie mehr als ein Vokabular mit derselben Codebasis unterstützen.

  • Sie definieren die XAML-Sprachunterstützung in einem oder mehreren CLR-Namespaces. In diesem Fall sollte der XmlNamespace-Wert http://schemas.microsoft.com/winfx/2006/xaml lauten.

XmlnsPrefixAttribute

Referenzdokumentation:XmlnsPrefixAttribute

Argumente:

  • Eine Zeichenfolge, die den Bezeichner eines XAML-Namespace angibt.

  • Eine Zeichenfolge, die ein empfohlenes Präfix angibt.

    XmlnsDefinitionAttribute gibt ein empfohlenes Präfix für einen XAML-Namespace an. Das Präfix ist nützlich, wenn Sie Elemente und Attribute in eine XAML-Datei schreiben, die durch den XamlXmlWriter der .NET XAML-Dienste serialisiert wird, oder wenn eine Bibliothek, die XAML implementiert, mit einer Entwurfsumgebung interagiert, die über XAML-Bearbeitungsfunktionen verfügt.

    Auf eine Assembly kann mehr als ein XmlnsPrefixAttribute angewendet werden. Dies kann aus einer beliebigen Kombination der folgenden Gründe geschehen:

  • Ihre Assembly definiert Typen für mehr als einen XAML-Namespace. Definieren Sie in diesem Fall verschiedene Präfixwerte für jeden XAML-Namespace.

  • Sie unterstützen mehr als ein Vokabular und verwenden für jedes Vokabular und jeden XAML-Namespace unterschiedliche Präfixe.

  • Sie definieren die XAML-Sprachunterstützung in der Assembly und verfügen über ein XmlnsDefinitionAttribute für http://schemas.microsoft.com/winfx/2006/xaml. In diesem Fall sollten Sie üblicherweise das Präfix x vorziehen.

Hinweis

Die .NET XAML-Dienste definieren außerdem das XAML-bezogene Attribut RootNamespaceAttribute. Dieses Attribut ist ein Attribut auf Assemblyebene zur Unterstützung des Projektsystems. Es ist für benutzerdefinierte XAML-Typen nicht relevant.

Weitere Informationen