XAML 用の型コンバーターの概要Overview of type converters for XAML

型コンバーターは、XAML マークアップの文字列をオブジェクト グラフの特定のオブジェクトに変換するオブジェクト ライターのロジックを提供します。Type converters supply logic for an object writer that converts from a string in XAML markup into particular objects in an object graph. NET XAML サービスでは、型コンバーターはTypeConverterから派生するクラスである必要があります。In .NET XAML Services, the type converter must be a class that derives from TypeConverter. 一部のコンバーターは XAML 保存パスもサポートしており、オブジェクトをシリアル化マークアップの文字列形式にシリアル化するために使用されます。Some converters also support the XAML save path and can be used to serialize an object into a string form in serialization markup. このトピックでは、XAML の型コンバーターがいつ、どのように起動されるかについて説明し、 TypeConverterのメソッドのオーバーライドの実装についてアドバイスします。This topic describes how and when type converters in XAML are invoked, and provides implementation advice for the method overrides of TypeConverter.

型変換の概念Type Conversion Concepts

次のセクションでは、XAML で文字列を使用する方法と、.NET XAML サービスのオブジェクト ライターが型コンバーターを使用して、XAML ソースで検出される文字列値の一部を処理する方法についての基本的な概念について説明します。The following sections explain basic concepts about how XAML uses strings, and how object writers in .NET XAML Services use type converters to process some of the string values that are encountered in a XAML source.

XAML と文字列値XAML and String Values

XAML ファイルで属性値を設定する場合、その値の最初の型は一般的な意味での文字列であり、XML の意味としては文字列の属性値です。When you set an attribute value in a XAML file, the initial type of that value is a string in a general sense, and a string attribute value in an XML sense. Double など、その他のプリミティブも、XAML プロセッサに対して最初は文字列です。Even other primitives such as Double are initially strings to a XAML processor.

ほとんどの場合、XAML プロセッサは、属性値を処理するために 2 つの情報を必要とします。In most cases, a XAML processor needs two pieces of information to process an attribute value. 第 1 の情報は、設定しようとしているプロパティの値の型です。The first piece of information is the value type of the property that is being set. 属性値を定義するすべての文字列は、XAML で処理され、最終的にはその型の値に変換 (解決) される必要があります。Any string that defines an attribute value and that is processed in XAML must ultimately be converted or resolved to a value of that type. 値が、XAML パーサーで認識できるプリミティブ (数値など) である場合は、文字列の直接的な変換が試みられます。If the value is a primitive that is understood by the XAML parser (such as a numeric value), a direct conversion of the string is attempted. 属性の値が列挙体を参照している場合は、指定された文字列がその列挙体の名前付き定数に一致するかどうか確認されます。If the value for the attribute references an enumeration, the supplied string is checked for a name match to a named constant in that enumeration. 値がパーサーが理解できるプリミティブまたは列挙型の定数名でない場合、該当する型は、変換された文字列に基づく値または参照を提供できる必要があります。If the value is not a parser-understood primitive or a constant name from an enumeration, the applicable type must be able to provide a value or reference that is based on a converted string.

注意

XAML 言語ディレクティブでは、型コンバーターは使用されません。XAML language directives do not use type converters.

型コンバーターとマークアップ拡張機能Type Converters and Markup Extensions

マークアップ拡張機能の使用は、プロパティの型やその他の考慮事項を確認する前に、XAML プロセッサで処理される必要があります。Markup extension usages must be handled by a XAML processor before it checks for property type and other considerations. たとえば、属性として設定されるプロパティが、通常は型変換を行うものの、特定のケースではマークアップ拡張機能を使用して設定するという場合は、マークアップ拡張機能の動作が最初に処理されます。For example, if a property being set as an attribute normally has a type conversion, but in a particular case is set by a markup extension usage, then the markup extension behavior processes first. マークアップ拡張機能が必要になる 1 つの一般的な状況は、既に存在するオブジェクトを参照する場合です。One common situation where a markup extension is necessary is to make a reference to an object that already exists. このシナリオでは、ステートレスな型コンバーターは新しいインスタンスを生成することしかできないため、望ましくありません。For this scenario, a stateless type converter can only generate a new instance, which might not be desirable. マークアップ拡張機能について詳しくは、「 Markup Extensions for XAML Overview」をご覧ください。For more information about markup extensions, see Markup Extensions for XAML Overview.

ネイティブな型コンバーターNative Type Converters

Windows プレゼンテーション ファンデーション (WPF) および .NET XAML サービスの実装では、ネイティブ型変換処理を持つ特定の CLR 型があります。In the Windows Presentation Foundation (WPF) and .NET XAML services implementations, there are certain CLR types that have native type conversion handling. ただし、これらの CLR 型は、従来はプリミティブとは考え方が異なります。However, those CLR types are not conventionally thought of as primitives. このような型の例として、 DateTimeが挙げられます。An example of such a type is DateTime. この理由の 1 つは、.NET Framework のアーキテクチャがどのように機能するかにあります。 DateTime 型は、.NET の最も基本的なライブラリである mscorlib で定義されています。One reason for this is how the .NET Framework architecture works: the type DateTime is defined in mscorlib, the most basic library in .NET. DateTimeは、依存関係を導入する別のアセンブリから取得された属性を持つ属性を持つ許可TypeConverterAttributeされていません ( System から取得します 。DateTime is not permitted to be attributed with an attribute that comes from another assembly that introduces a dependency (TypeConverterAttribute is from System). したがって、帰属による通常の型コンバーター検出メカニズムはサポートされません。Therefore, the usual type converter discovery mechanism by attributing cannot be supported. 代わりに、XAML パーサーは、ネイティブな処理が必要な型の一覧を保持し、それらの型を通常のプリミティブの処理と類似した方法で処理します。Instead, the XAML parser has a list of types that need native processing, and it processes these types similar to how the true primitives are processed. DateTimeの場合、その処理には Parseの呼び出しが含まれます。In the case of DateTime, this processing involves a call to Parse.

型コンバーターの実装Implementing a Type Converter

以下のセクションで、 TypeConverter クラスの API について説明します。The following sections discuss the API of the TypeConverter class.

TypeConverterTypeConverter

NET XAML サービスでは、XAML 目的で使用されるすべての型コンバーターは、基本クラスから派生するクラスTypeConverterです。Under .NET XAML Services, all type converters that are used for XAML purposes are classes that derive from the base class TypeConverter. TypeConverter クラスは、XAML が登場するより前のバージョンの .NET Framework にも含まれていました。 TypeConverter を使用する元々のシナリオの 1 つは、ビジュアル デザイナーのプロパティ エディターに文字列の変換を提供することでした。The TypeConverter class existed in versions of the .NET Framework before XAML existed; one of the original TypeConverter scenarios was to provide string conversion for property editors in visual designers.

XAML では、 TypeConverter の役割が拡張されました。For XAML, the role of TypeConverter is expanded. XAML の目的では、 TypeConverter は、特定の文字列への変換と特定の文字列からの変換をサポートする基底クラスです。For XAML purposes, TypeConverter is the base class for providing support for certain to-string and from-string conversions. 文字列からの変換は、XAML から文字列属性値への解析に利用されます。From-string enables parsing a string attribute value from XAML. 文字列への変換は、特定のオブジェクト プロパティの実行時の値をシリアル化のために XAML の属性に戻す処理に利用されます。To-string might enable processing a run-time value of a particular object property back into an attribute in XAML for serialization.

TypeConverter には、XAML を処理する目的で、文字列への変換と文字列からの変換に関連する次の 4 つのメンバーが定義されています。TypeConverter defines four members that are relevant for converting to-string and from-string for XAML processing purposes:

これらのメンバーの中で最も重要なメソッドは ConvertFromであり、入力文字列を必要なオブジェクトの型に変換します。Of these members, the most important method is ConvertFrom, which converts the input string to the required object type. ConvertFrom メソッドの実装では、さまざまな型をコンバーターの目的とする型に変換する処理を実現できます。The ConvertFrom method can be implemented to convert a wider range of types into the intended destination type of the converter. したがって、実行時の変換をサポートするなど、XAML 以外の目的でも使用できます。Therefore, it can serve purposes that extend beyond XAML, such as supporting run-time conversions. ただし、XAML の用途では、 String 入力を処理できるコード パスのみが重要です。However, for XAML use, only the code path that can process a String input is important.

2 番目に重要な方法ConvertToは です。The second-most important method is ConvertTo. アプリケーションがマークアップ表現に変換される場合 (たとえば、XAML にファイルとして保存される場合)、ConvertToマークアップ表現を生成する XAML テキスト ライターの大規模なシナリオに関与します。If an application is converted to a markup representation (for example, if it is saved to XAML as a file), ConvertTo is involved in the larger scenario of a XAML text writer to produce a markup representation. この場合、XAML にとって重要なコード パスは、呼び出し元が destinationTypeStringを渡す時です。In this case, the important code path for XAML is when the caller passes a destinationType of String.

CanConvertToCanConvertFrom は、サービスが TypeConverter の実装の機能を照会する時に使用されるサポート メソッドです。CanConvertTo and CanConvertFrom are support methods that are used when a service queries the capabilities of the TypeConverter implementation. これらのメソッドは、その型について、相当する変換メソッドをコンバーターがサポートしている場合に true を返すように実装する必要があります。You must implement these methods to return true for type-specific cases that the equivalent conversion methods of your converter support. XAML の目的では、通常、 String 型であることを意味します。For XAML purposes, this generally means the String type.

カルチャ情報と XAML の型コンバーターCulture Information and Type Converters for XAML

TypeConverter 実装では、変換に対して有効な文字列を独自に解釈できます。また、パラメーターとして渡される型の説明を使用することも無視することもできます。Each TypeConverter implementation can uniquely interpret what is a valid string for a conversion, and it can also use or ignore the type description that is passed as parameters. カルチャと XAML の型変換については、重要な考慮事項があります。ローカライズ可能な文字列を属性値として使用することは XAML でサポートされていますが、それらのローカライズ可能な文字列を、特定のカルチャ要件を指定して型コンバーターの入力として使用することはできません。An important consideration for culture and XAML type conversion is the following: although using localizable strings as attribute values is supported by XAML, you cannot use these localizable strings as type converter input with specific culture requirements. この制限の理由は、XAML 属性値の型コンバーターには、特定の言語に固定して ( en-US カルチャを使用して) 実行しなければならない XAML 処理の動作がどうしても含まれるためです。This limitation is because type converters for XAML attribute values involve a necessarily fixed-language XAML-processing behavior that uses en-US culture. この制限の設計上の理由の詳細については、「XAML 言語仕様 ([MS-XAML]) 」または「 WPF のグローバリゼーションとローカリゼーションの概要」を参照してください。For more information about the design reasons for this restriction, see the XAML language specification ([MS-XAML]) or WPF Globalization and Localization Overview.

カルチャが問題となる例として、一部のカルチャで文字列形式の数値の小数点記号にピリオドではなくコンマが使用されることが挙げられます。As an example where culture can be an issue, some cultures use a comma instead of a period as the decimal point delimiter for numbers in string form. そのように使用した場合、区切り記号としてコンマを使用する多くの既存の型コンバーターで、動作が競合します。This use collides with the behavior that many existing type converters have, which is to use a comma as a delimiter. 周囲の XAML で xml:lang を使用してカルチャを指定しても、この問題は解決しません。Passing a culture through xml:lang in the surrounding XAML does not solve the issue.

ConvertFrom の実装Implementing ConvertFrom

XAML をサポートする TypeConverter の実装としてコンバーターを使用できるようにするためには、そのコンバーターの ConvertFrom メソッドが value パラメーターとして文字列を受け入れる必要があります。To be usable as a TypeConverter implementation that supports XAML, the ConvertFrom method for that converter must accept a string as the value parameter. 文字列が有効な形式であり、 TypeConverter 実装で変換できる場合、実装から返すオブジェクトは、プロパティで想定される型へのキャストをサポートしている必要があります。If the string is in a valid format and can be converted by the TypeConverter implementation, the returned object must support a cast to the type that is expected by the property. それ以外の場合、 ConvertFrom 実装は nullを返す必要があります。Otherwise, the ConvertFrom implementation must return null.

TypeConverter 実装では、変換に対して有効な文字列の構成内容を独自に解釈できます。また、パラメーターとして渡される型の説明やカルチャ コンテキストを使用することも無視することもできます。Each TypeConverter implementation can uniquely interpret what constitutes a valid string for a conversion, and it can also use or ignore the type description or culture contexts that are passed as parameters. ただし、WPF による XAML 処理では、型の説明コンテキストに値を渡さない場合があり、 xml:langに基づくカルチャを渡さない場合もあります。However, the WPF XAML processing might not pass values to the type description context in all cases and also might not pass culture based on xml:lang.

注意

かっこ (){}を使用しない場合は、文字列形式の要素として、特に左中かっこ ({) を使用しないでください。Do not use the braces ({}), specifically the opening brace ({), as an element of your string format. これらの文字は、マークアップ拡張シーケンスの開始および終了を示す文字として予約されています。These characters are reserved as the entry and exit for a markup extension sequence.

型コンバーターが .NET XAML Services オブジェクト ライターから XAML サービスにアクセスする必要があるが、コンテキストにGetService対して行われた呼び出しがそのサービスを返さない場合は、例外をスローするのが適切です。It is appropriate to throw an exception when your type converter must have access to a XAML service from .NET XAML Services object writer, but the GetService call that is made against the context does not return that service.

ConvertTo の実装Implementing ConvertTo

ConvertTo は、シリアル化のサポートで使用される可能性があります。ConvertTo is potentially used for serialization support. カスタム型およびその型コンバーターに対して ConvertTo によるシリアル化をサポートすることは、絶対要件ではありません。Serialization support through ConvertTo for your custom type and its type converter is not an absolute requirement. ただし、コントロールを実装する場合、またはクラスの機能または設計の一部としてシリアル化を使用する場合は、 ConvertToを実装する必要があります。However, if you are implementing a control, or using serialization of as part of the features or design of your class, you should implement ConvertTo.

XAML をサポートする TypeConverter の実装としてコンバーターを使用できるようにするためには、そのコンバーターの ConvertTo メソッドが、サポートされる型のインスタンス (または値) を value パラメーターとして受け入れる必要があります。To be usable as a TypeConverter implementation that supports XAML, the ConvertTo method for that converter must accept an instance of the type (or a value) that is supported as the value parameter. destinationType パラメーターが String型の場合、返されるオブジェクトは Stringにキャストできる必要があります。When the destinationType parameter is of type String, the returned object must be able to be cast as String. 返される文字列は、 valueのシリアル化された値を表している必要があります。The returned string must represent a serialized value of value. 理想としては、採用するシリアル化の形式は、その文字列を同じコンバーターの ConvertFrom の実装に渡した場合と比べて情報の大きな損失が発生することなく、同じ値を生成できる必要があります。Ideally, the serialization format that you choose should be able to generate the same value as if that string were passed to the ConvertFrom implementation of the same converter, without significant loss of information.

値をシリアル化できない場合、またはコンバーターがシリアル化をサポートしていない場合は、 ConvertTo の実装は null を返す必要があり、例外をスローできます。If the value cannot be serialized or the converter does not support serialization, the ConvertTo implementation must return null and can throw an exception. ただし、例外をスローする場合は、 CanConvertTo 実装の一部として、その変換を使用できないことを通知するようにしてください。そうすれば、まず CanConvertTo を確認することによって例外を回避するというベスト プラクティスをサポートできます。However, if you do throw exceptions, you should report the inability to use that conversion as part of your CanConvertTo implementation so that the best practice of checking with CanConvertTo first to avoid exceptions is supported.

destinationType パラメーターが String型でない場合は、独自のコンバーター処理を実装できます。If the destinationType parameter is not of type String, you can choose your own converter handling. 通常は、基底の実装の処理に戻り、基底の ConvertTo で特定の例外を発生させます。Typically, you revert to base implementation handling, which in the base ConvertTo raises a specific exception.

型コンバーターが .NET XAML Services オブジェクト ライターから XAML サービスにアクセスする必要があるが、コンテキストにGetService対して行われた呼び出しがそのサービスを返さない場合は、例外をスローするのが適切です。It is appropriate to throw an exception when your type converter must have access to a XAML service from .NET XAML Services object writer, but the GetService call that is made against the context does not return that service.

CanConvertFrom の実装Implementing CanConvertFrom

CanConvertFrom の実装は、 truesourceType 型の場合は String を返し、それ以外の場合は基底の実装に任せる必要があります。Your CanConvertFrom implementation should return true for sourceType of type String and otherwise, defer to the base implementation. CanConvertFrom から例外をスローしないでください。Do not throw exceptions from CanConvertFrom.

CanConvertTo の実装Implementing CanConvertTo

CanConvertTo の実装は、 truedestinationType 型の場合は Stringを返し、それ以外の場合は基底の実装に任せる必要があります。Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer to the base implementation. CanConvertTo から例外をスローしないでください。Do not throw exceptions from CanConvertTo.

TypeConverterAttribute の適用Applying the TypeConverterAttribute

カスタム型コンバーターを .NET XAML サービスによるカスタム クラスの代理型コンバーターとして使用するには、 をTypeConverterAttributeクラス定義に適用する必要があります。For your custom type converter to be used as the acting type converter for a custom class by .NET XAML Services, you must apply the TypeConverterAttribute to your class definition. 属性を通して指定する ConverterTypeName は、カスタム型コンバーターの型名である必要があります。The ConverterTypeName that you specify through the attribute must be the type name of your custom type converter. この属性を適用すると、プロパティの型としてカスタム クラスの型が使用されている値を XAML プロセッサが処理する際に、入力文字列を処理して、オブジェクトのインスタンスを返すことができます。If you apply this attribute, when a XAML processor handles values where the property type uses your custom class type, it can input strings and return object instances.

また、プロパティごとに型コンバーターを提供することもできます。You can also provide a type converter on a per-property basis. TypeConverterAttributeクラス定義に適用するのではなく、プロパティ定義 (その中のget/set実装ではなく、メイン定義) に適用します。Instead of applying a TypeConverterAttribute to the class definition, apply it to a property definition (the main definition, not the get/set implementations within it). プロパティの型は、カスタム型コンバーターによって処理される型と一致する必要があります。The type of the property must match the type that is processed by your custom type converter. この属性を適用すると、プロパティの値を XAML プロセッサが処理する際に、入力文字列を処理して、オブジェクトのインスタンスを返すことができます。With this attribute applied, when a XAML processor handles values of that property, it can process input strings and return object instances. プロパティごとの型コンバーターの手法は、Microsoft .NET Framework またはクラス定義を制御できず、そのライブラリからプロパティ型を使用する場合に便利ですTypeConverterAttributeThe per-property type converter technique is useful if you choose to use a property type from Microsoft .NET Framework or from some other library where you cannot control the class definition and cannot apply a TypeConverterAttribute there.

アタッチされたカスタム メンバーの型変換動作を割り当てるには、アタッチされたメンバーの実装パターンの TypeConverterAttribute アクセサー メソッドに Get を適用します。To supply a type conversion behavior for a custom attached member, apply TypeConverterAttribute to the Get accessor method of the implementation pattern for the attached member.

マークアップ拡張機能の実装からサービス プロバイダーのコンテキストにアクセスするAccessing Service Provider Context from a Markup Extension Implementation

使用可能なサービスは、すべての値コンバーターの場合と同じです。The available services are the same for any value converter. ただし、それぞれの値コンバーターがサービス コンテキストを受け取る方法が違います。The difference is in how each value converter receives the service context. サービスへのアクセスと、使用できるサービスについては、「 Type Converters and Markup Extensions for XAML」のトピックをご覧ください。Accessing services and the services available are documented in the topic Type Converters and Markup Extensions for XAML.

XAML ノード ストリームでの型コンバーターType Converters in the XAML Node Stream

XAML ノード ストリームを処理している場合、型コンバーターのアクションや最終結果はまだ実行されていません。If you are working with a XAML node stream, the action or end result of a type converter is not yet executed. 読み込みパスでは、読み込むために最終的に型変換する必要がある属性文字列は、開始メンバーおよび終了メンバー内でテキスト値のままです。In a load path, the attribute string that eventually needs to be type-converted in order to load remains as a text value within a start member and end member. この処理のために最終的に必要になる型コンバーターは、 XamlMember.TypeConverter プロパティを使用することで判別できます。The type converter that is eventually needed for this operation can be determined by using the XamlMember.TypeConverter property. ただし、 XamlMember.TypeConverter から有効な値を取得するには、基になるメンバー、またはメンバーが使用するオブジェクト値の型を介してこのような情報にアクセスできる XAML スキーマ コンテキストを持っていることが必要です。However, obtaining a valid value from XamlMember.TypeConverter relies on having a XAML schema context, which can access such information through the underlying member, or the type of the object value that the member uses. 型変換の動作を呼び出すためにも、型マッピングと、コンバーター インスタンスの作成が必要であるため、XAML スキーマ コンテキストが必要になります。Invoking the type conversion behavior also requires the XAML schema context because that requires type-mapping and creating a converter instance.

関連項目See also