Übersicht über Typkonverter für XAML
Typkonverter liefern Logik für einen Objektschreiber, der aus einer Zeichenfolge im XAML-Markup in bestimmte Objekte in einem Objektdiagramm konvertiert. In .NET XAML Services muss der Typkonverter eine Klasse sein, die von TypeConverterabgeleitet wird. Einige Konverter unterstützen auch den XAML-Speicherpfad und können verwendet werden, um ein Objekt im Serialisierungsmarkup in eine Zeichenfolge zu serialisieren. In diesem Thema wird beschrieben, wie und wann Typkonverter in XAML aufgerufen werden, und bietet Implementierungstipps für die Methodenüberschreibungen von TypeConverter.
Typkonvertierungskonzepte
In den folgenden Abschnitten werden grundlegende Konzepte erläutert, wie XAML Zeichenfolgen verwendet, und wie Objektautoren in .NET XAML Services Typkonverter verwenden, um einige der Zeichenfolgenwerte zu verarbeiten, die in einer XAML-Quelle auftreten.
XAML- und Zeichenfolgenwerte
Wenn Sie einen Attributwert in einer XAML-Datei festlegen, ist der anfängliche Typ dieses Werts eine Zeichenfolge im allgemeinen und ein Zeichenfolgen-Attributwert in einem XML-Sinne. Auch andere Grundtypen wie Double sind anfänglich Zeichenfolgen für einen XAML-Prozessor.
In den meisten Fällen benötigt ein XAML-Prozessor zwei Informationen, um einen Attributwert zu verarbeiten. Der erste Informationsteil ist der Werttyp der eigenschaft, die festgelegt wird. Jede Zeichenfolge, die einen Attributwert definiert und in XAML verarbeitet wird, muss letztendlich in einen Wert dieses Typs konvertiert oder aufgelöst werden. Wenn der Wert ein Grundtyp ist, der vom XAML-Parser verstanden wird (wie numerische Werte), wird eine direkte Konvertierung der Zeichenfolge versucht. Wenn der Wert für das Attribut auf eine Enumeration verweist, wird die angegebene Zeichenfolge auf einen Namen überprüft, der mit einer benannten Konstante in dieser Enumeration übereinstimmt. Wenn es sich bei dem Wert nicht um einen parserverstandenen Grundtyp oder einen Konstantennamen aus einer Enumeration handelt, muss der entsprechende Typ in der Lage sein, einen Wert oder einen Verweis bereitzustellen, der auf einer konvertierten Zeichenfolge basiert.
Anmerkung
XAML-Sprachdirektiven verwenden keine Typkonverter.
Typkonverter und Markuperweiterungen
Die Verwendung von Markuperweiterungen muss von einem XAML-Prozessor verarbeitet werden, bevor er den Eigenschaftstyp und andere Überlegungen überprüft. Wenn beispielsweise eine Eigenschaft als Attribut festgelegt wird, die normalerweise eine Typkonvertierung erfordert, aber in einem bestimmten Fall durch die Verwendung der Markuperweiterung festgelegt wird, wird zuerst das Verhalten der Markuperweiterung verarbeitet. Eine häufige Situation, in der eine Markuperweiterung erforderlich ist, besteht darin, einen Verweis auf ein bereits vorhandenes Objekt zu erstellen. In diesem Szenario kann ein zustandsloser Typkonverter nur eine neue Instanz generieren, die möglicherweise nicht wünschenswert ist. Weitere Informationen zu Markuperweiterungen finden Sie unter Markuperweiterungen für XAML Overview.
Systemeigene Typkonverter
In den Implementierungen von Windows Presentation Foundation (WPF) und .NET XAML-Diensten gibt es bestimmte CLR-Typen mit systemeigener Typkonvertierungsverarbeitung. Diese CLR-Typen werden jedoch nicht konventionell als Grundtypen betrachtet. Ein Beispiel für einen solchen Typ ist DateTime. Ein Grund dafür ist die Funktionsweise der .NET Framework-Architektur: Der Typ DateTime ist in mscorlib, der einfachsten Bibliothek in .NET definiert. DateTime darf nicht einem Attribut zugeordnet werden, das von einer anderen Assembly stammt, die eine Abhängigkeit einführt (TypeConverterAttribute stammt aus System). Daher kann der übliche Mechanismus zur Ermittlung von Typkonvertern durch Attribuierung nicht unterstützt werden. Stattdessen verfügt der XAML-Parser über eine Liste von Typen, die systemeigene Verarbeitung erfordern, und verarbeitet diese ähnlich wie die tatsächlichen Grundtypen. Im Falle von DateTimeumfasst diese Verarbeitung einen Aufruf von Parse.
Implementierung eines Typen-Konverters
In den folgenden Abschnitten wird die API der TypeConverter Klasse erläutert.
Typenwandler
Unter .NET XAML Services sind alle Typkonverter, die für XAML-Zwecke verwendet werden, Klassen, die von der Basisklasse TypeConverterabgeleitet werden. Die TypeConverter-Klasse war in Versionen von .NET Framework vorhanden, bevor XAML vorhanden war; Eines der ursprünglichen TypeConverter Szenarien bestand darin, Zeichenfolgenkonvertierung für Eigenschaften-Editoren in visuellen Designern bereitzustellen.
Für XAML wird die Rolle von TypeConverter erweitert. Für XAML-Zwecke ist TypeConverter die Basisklasse, die die Unterstützung für bestimmte Umwandlungen in und von Zeichenfolgen bietet. From-string ermöglicht die Analyse eines Zeichenfolgenattributewerts aus XAML. ToString kann es ermöglichen, einen Laufzeitwert einer bestimmten Objekteigenschaft wieder in ein Attribut in XAML zu transformieren, um diesen für die Serialisierung zu nutzen.
TypeConverter definiert vier Elemente, die für die Konvertierung in eine Zeichenfolge und aus der Zeichenfolge für XAML-Verarbeitungszwecke relevant sind:
Von diesen Membern ist die Methode ConvertFromdie wichtigste, die die Eingabezeichenfolge in den erforderlichen Objekttyp konvertiert. Die ConvertFrom-Methode kann implementiert werden, um einen breiteren Bereich von Typen in den beabsichtigten Zieltyp des Konverters zu konvertieren. Daher kann es Zwecken dienen, die über XAML hinausgehen, z. B. die Unterstützung von Laufzeitkonvertierungen. Für die XAML-Verwendung ist jedoch nur der Codepfad wichtig, der eine String Eingabe verarbeiten kann.
Die zweitwichtigste Methode ist ConvertTo. Wenn eine Anwendung in eine Markupdarstellung konvertiert wird (z. B. wenn sie in XAML als Datei gespeichert wird), ist ConvertTo an dem größeren Szenario eines XAML-Textschreibers beteiligt, um eine Markupdarstellung zu erzeugen. In diesem Fall ist der wichtige Codepfad für XAML, wenn der Aufrufer eine destinationType von Stringübergibt.
CanConvertTo und CanConvertFrom sind Supportmethoden, die verwendet werden, wenn ein Dienst die Funktionen der TypeConverter Implementierung abfragt. Sie müssen diese Methoden implementieren, um true für typspezifische Fälle zurückzugeben, die von den entsprechenden Konvertierungsmethoden Ihres Konverters unterstützt werden. Für XAML-Zwecke bedeutet dies im Allgemeinen den String Typ.
Kulturbezogene Informationen und Typkonverter für XAML
Jede TypeConverter Implementierung kann eindeutig interpretieren, was eine gültige Zeichenfolge für eine Konvertierung ist, und sie kann auch die Typbeschreibung verwenden oder ignorieren, die als Parameter übergeben wird. Eine wichtige Überlegung für die Kultur- und XAML-Typkonvertierung ist folgendes: Obwohl die Verwendung lokalisierbarer Zeichenfolgen als Attributwerte von XAML unterstützt wird, können Sie diese lokalisierbaren Zeichenfolgen nicht als Typkonvertereingabe mit bestimmten Kulturanforderungen verwenden. Diese Einschränkung ist darauf zurückzuführen, dass Typkonverter für XAML-Attributwerte ein strikt festgelegtes XAML-Verarbeitungsverhalten erfordern, das die en-US-Kultur verwendet. Weitere Informationen zu den Entwurfsgründen für diese Einschränkung finden Sie in der XAML-Sprachspezifikation ([MS-XAML]) oder WPF Globalization and Localization Overview.
Ein Beispiel, bei dem Kultur ein Problem sein kann, ist die Verwendung eines Kommas anstelle eines Punktes als Dezimalseparator für Zahlen in Textform durch einige Kulturen. Diese Verwendung kollidiert mit dem Verhalten, das viele vorhandene Typkonverter aufweisen, die ein Komma als Trennzeichen verwenden. Das Übergeben einer Kultur durch xml:lang im umgebenden XAML-Code löst das Problem nicht.
Implementieren von ConvertFrom
Damit sie als TypeConverter Implementierung verwendet werden kann, die XAML unterstützt, muss die ConvertFrom-Methode für diesen Konverter eine Zeichenfolge als value-Parameter akzeptieren. Wenn sich die Zeichenfolge in einem gültigen Format befindet und von der TypeConverter-Implementierung konvertiert werden kann, muss das zurückgegebene Objekt eine Umwandlung in den von der Eigenschaft erwarteten Typ unterstützen. Andernfalls muss die ConvertFrom-Implementierung nullzurückgeben.
Jede TypeConverter Implementierung kann eindeutig interpretieren, was eine gültige Zeichenfolge für eine Konvertierung darstellt, und sie kann auch die Typbeschreibung oder Kulturkontexte verwenden oder ignorieren, die als Parameter übergeben werden. Die WPF-XAML-Verarbeitung übergibt jedoch möglicherweise in allen Fällen keine Werte an den Typbeschreibungskontext und übergibt auch keine Kultur basierend auf xml:lang.
Anmerkung
Verwenden Sie nicht die Klammern ({}), insbesondere die öffnende Klammer ({), als Element Ihres Zeichenfolgenformats. Diese Zeichen sind als Eingang und Ausgang für eine Markup-Erweiterungssequenz reserviert.
Es ist angemessen, eine Ausnahme auszuwerfen, wenn Ihr Typkonverter Zugriff auf einen XAML-Dienst von einem .NET XAML Services-Objektschreiber haben muss, aber der GetService-Aufruf, der auf den Kontext ausgeführt wird, diesen Dienst nicht zurückgibt.
Umsetzung von ConvertTo
ConvertTo wird potenziell zur Serialisierungsunterstützung verwendet. Serialisierungsunterstützung durch ConvertTo für Ihren benutzerdefinierten Typ und dessen Typkonverter ist keine absolute Anforderung. Wenn Sie jedoch ein Steuerelement implementieren oder die Serialisierung als Teil der Features oder des Entwurfs Ihrer Klasse verwenden, sollten Sie ConvertToimplementieren.
Damit sie als TypeConverter Implementierung verwendet werden kann, die XAML unterstützt, muss die ConvertTo Methode für diesen Konverter eine Instanz des Typs (oder einen Wert) akzeptieren, der als value-Parameter unterstützt wird. Wenn der destinationType Parameter vom Typ Stringist, muss das zurückgegebene Objekt als Stringumgewandelt werden können. Die zurückgegebene Zeichenfolge muss einen serialisierten Wert von valuedarstellen. Im Idealfall sollte das von Ihnen ausgewählte Serialisierungsformat in der Lage sein, denselben Wert zu generieren, als ob diese Zeichenfolge an die ConvertFrom Implementierung desselben Konverters übergeben wurde, ohne dass erhebliche Informationen verloren gehen.
Wenn der Wert nicht serialisiert werden kann oder der Konverter die Serialisierung nicht unterstützt, muss die ConvertTo-Implementierung null zurückgeben und eine Ausnahme auslösen. Wenn Sie jedoch Ausnahmen auslösen, sollten Sie die Unfähigkeit melden, diese Konvertierung als Teil Ihrer CanConvertTo Implementierung zu verwenden, damit die bewährte Methode der Überprüfung mit CanConvertTo zuerst unterstützt wird, um Ausnahmen zu vermeiden.
Wenn der destinationType Parameter nicht vom Typ Stringist, können Sie eine eigene Konverterbehandlung auswählen. Normalerweise kehren Sie zur Verarbeitung der Basisimplementierung zurück, die in der Basis ConvertTo eine bestimmte Ausnahme auslöst.
Es ist angemessen, eine Ausnahme auszuwerfen, wenn der Typkonverter Zugriff auf einen XAML-Dienst des .NET XAML Services-Objektschreibers haben muss, aber der GetService-Aufruf, der für den Kontext ausgeführt wird, stellt diesen Dienst nicht bereit.
Implementieren von CanConvertFrom
Ihre CanConvertFrom-Implementierung sollte true für sourceType vom Typ String zurückgeben und andernfalls auf die Basisimplementierung zurückgreifen. Werfen Sie keine Ausnahmen von CanConvertFrom.
Implementierung von CanConvertTo
Ihre CanConvertTo-Implementierung sollte true für destinationType vom Typ Stringzurückgeben und andernfalls auf die Basisimplementierung zurückstellen. Werfen Sie keine Ausnahmen von CanConvertTo.
Das Anwenden des TypeConverterAttribute
Damit Ihr benutzerdefinierter Typkonverter als wirksamer Typkonverter für eine benutzerdefinierte Klasse von .NET XAML Services fungieren kann, müssen Sie das Attribut TypeConverterAttribute auf Ihre Klassendefinition anwenden. Die ConverterTypeName, die Sie über das Attribut angeben, muss der Typname des benutzerdefinierten Typkonverters sein. Wenn Sie dieses Attribut anwenden, kann ein XAML-Prozessor, wenn er Werte verarbeitet, bei denen der Eigenschaftstyp Ihren benutzerdefinierten Klassentyp verwendet, Zeichenfolgen eingeben und Objektinstanzen zurückgeben.
Sie können auch einen Typkonverter pro Eigenschaft bereitstellen. Anstatt eine TypeConverterAttribute auf die Klassendefinition anzuwenden, wenden Sie sie auf eine Eigenschaftsdefinition an (die Hauptdefinition, nicht die get/set Implementierungen darin). Der Typ der Eigenschaft muss mit dem Typ übereinstimmen, der vom benutzerdefinierten Typumwandler verarbeitet wird. Wenn dieses Attribut angewendet wird, kann ein XAML-Prozessor Eingabestrings verarbeiten sowie Werte dieser Eigenschaft behandeln und Objektinstanzen zurückgeben. Die Konvertertechnik pro Eigenschaft ist nützlich, wenn Sie einen Eigenschaftstyp aus Microsoft .NET Framework oder einer anderen Bibliothek wählen, bei der Sie die Klassendefinition nicht steuern können und dort keine TypeConverterAttribute anwenden können.
Um ein Typkonvertierungsverhalten für ein benutzerdefiniertes angefügtes Element bereitzustellen, wenden Sie TypeConverterAttribute auf die Get Accessormethode des Implementierungsmusters für das angefügte Element an.
Zugriff auf den Kontext des Dienstanbieters aus einer Markup-Erweiterungsimplementierung
Die verfügbaren Dienste sind für jeden Wertkonverter identisch. Der Unterschied besteht darin, wie jeder Wertkonverter den Dienstkontext empfängt. Der Zugriff auf Dienste und die verfügbaren Dienste sind im Thema Typkonverter und Markuperweiterungen für XAML-dokumentiert.
Typkonverter im XAML-Knotenstream
Wenn Sie mit einem XAML-Knotendatenstrom arbeiten, wird die Aktion oder das Endergebnis eines Typkonverters noch nicht ausgeführt. In einem Ladepfad bleibt die Attributzeichenfolge, die schließlich typkonvertiert werden muss, um geladen werden zu können, als Textwert innerhalb eines Startelements und eines Endelements. Der Typkonverter, der für diesen Vorgang schließlich benötigt wird, kann mithilfe der XamlMember.TypeConverter-Eigenschaft bestimmt werden. Das Abrufen eines gültigen Werts aus XamlMember.TypeConverter basiert jedoch auf einem XAML-Schemakontext, der über das zugrunde liegende Element auf solche Informationen zugreifen kann, oder den Typ des Objektwerts, den das Element verwendet. Das Aufrufen des Typkonvertierungsverhaltens erfordert auch den XAML-Schemakontext, da dies die Typzuordnung und das Erstellen einer Konverterinstanz erfordert.
Siehe auch
.NET Desktop feedback