TypeConverters および XAMLTypeConverters and XAML

このトピックでは、一般的な XAML 言語機能として、文字列からの型変換の目的について説明します。This topic introduces the purpose of type conversion from string as a general XAML language feature. .NET Framework で、TypeConverterクラスは、特定の目的を XAML 属性の使用法のプロパティの値として使用できる管理対象のカスタム クラスの実装の一部として機能します。In the .NET Framework, the TypeConverter class serves a particular purpose as part of the implementation for a managed custom class that can be used as a property value in XAML attribute usage. カスタム クラスを作成する XAML 設定可能な属性の値として使用するのには、クラスのインスタンスが必要な場合は、可能性があります、適用する必要があります、TypeConverterAttributeカスタムを作成し、クラスにTypeConverterクラス、またはその両方です。If you write a custom class, and you want instances of your class to be usable as XAML settable attribute values, you might need to apply a TypeConverterAttribute to your class, write a custom TypeConverter class, or both.

型変換の概念Type Conversion Concepts

XAML と文字列値XAML and String Values

XAML ファイルで属性値を設定するときは、その値の最初の型では、文字列が純粋なテキストです。When you set an attribute value in a XAML file, the initial type of that value is a string in pure text. などの他のプリミティブDouble最初は XAML プロセッサにテキスト文字列です。Even other primitives such as Double are initially text strings to a XAML processor.

XAML プロセッサには、属性値を処理するために 2 つの情報が必要があります。A XAML processor needs two pieces of information in order 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 is an enumeration, the string is used to check for a name match to a named constant in that enumeration. 値がどちらもパーサーで認識されるプリミティブも列挙体は、その問題の型の場合は、型、または変換後の文字列に基づいて、値のインスタンスを提供できる必要があります。If the value is neither a parser-understood primitive nor an enumeration, then the type in question must be able to provide an instance of the type, or a value, based on a converted string. これは、型コンバーターのクラスを示すことにより行います。This is done by indicating a type converter class. 型コンバーターは、事実上、コードが .NET コードの呼び出しに対する XAML シナリオとも可能性がある別のクラスの値を提供するためのヘルパー クラスです。The type converter is effectively a helper class for providing values of another class, both for the XAML scenario and also potentially for code calls in .NET code.

XAML で既存の型変換動作を使用します。Using Existing Type Conversion Behavior in XAML

基になる XAML の概念に関する知識、に応じてする可能性があります既に型変換動作アプリケーションで使用する基本的な XAML 気付かないうちに。Depending on your familiarity with the underlying XAML concepts, you may already be using type conversion behavior in basic application XAML without realizing it. たとえば、WPF は型の値を使用するプロパティの百を定義します。Pointします。For instance, WPF defines literally hundreds of properties that take a value of type Point. A Point 2 次元の座標空間内の座標を記述する値は、2 つの重要なプロパティが実際には:XYします。A Point is a value that describes a coordinate in a two-dimensional coordinate space, and it really just has two important properties: X and Y. XAML の時点を指定するときに指定する区切り記号 (コンマ) を使って文字列としての間、XY指定する値。When you specify a point in XAML, you specify it as a string with a delimiter (typically a comma) between the X and Y values you provide. たとえば、<LinearGradientBrush StartPoint="0,0" EndPoint="1,1"/> のように指定します。For example: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1"/>.

この単純な種類のでもPointXAML における単純な使用法が型コンバーターが含まれるとします。Even this simple type of Point and its simple usage in XAML involve a type converter. この場合、クラスはPointConverterします。In this case that is the class PointConverter.

型コンバーターPointマークアップの使用方法を使用するすべてのプロパティのクラス レベルの効率で定義されているPointします。The type converter for Point defined at the class level streamlines the markup usages of all properties that take Point. せず、型コンバーターは、ここでは次のとおり、前述の同じ例のマークアップをかなり詳細。Without a type converter here, you would need the following much more verbose markup for the same example shown previously:

    <Point X="0" Y="0"/>
    <Point X="1" Y="1"/>

文字列型の変換または同等のより詳細な構文を使用するかどうかは、一般に、コーディング スタイル選択です。Whether to use the type conversion string or a more verbose equivalent syntax is generally a coding style choice. XAML ツールのワークフローが値の設定方法に影響を与える可能性があります。Your XAML tooling workflow might also influence how values are set. 一部の XAML ツールは、デザイナーのビューや、独自のシリアル化メカニズムへのラウンドト リップする使いやすいために、最も詳細な形式のマークアップを出力する傾向があります。Some XAML tools tend to emit the most verbose form of the markup because it is easier to round-trip to designer views or its own serialization mechanism.

既存の型コンバーターは一般に、適用の有無クラス (またはプロパティ) をチェック WPF と .NET Framework の型で検出されたTypeConverterAttributeします。Existing type converters can generally be discovered on WPF and .NET Framework types by checking a class (or property) for the presence of an applied TypeConverterAttribute. この属性は、クラスの XAML の目的だけでなく可能性のある他の目的で、その型の値のサポート型コンバーターの名前を付けます。This attribute will name the class that is the supporting type converter for values of that type, for XAML purposes as well as potentially other purposes.

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

マークアップ拡張機能よぶ型コンバーターは、XAML プロセッサの動作とに適用するシナリオの観点から両方の役割を入力します。Markup extensions and type converters fill orthogonal roles in terms of XAML processor behavior and the scenarios that they are applied to. マークアップ拡張機能の使用時にはコンテキストを利用できますが、マークアップ拡張機能が値を提供するプロパティの型変換動作は一般にマークアップ拡張機能の実装ではチェックされません。Although context is available for markup extension usages, type conversion behavior of properties where a markup extension provides a value is generally is not checked in the markup extension implementations. つまり、マークアップ拡張機能としてテキスト文字列を返した場合であってもそのProvideValue出力するには、特定のプロパティまたはプロパティ値の型に適用されると、その文字列に対する型変換動作は呼び出されません、一般に、マークアップ拡張機能の目的は、プロセスには、文字列と関連する型コンバーターを呼び出さず、オブジェクトを返します。In other words, even if a markup extension returns a text string as its ProvideValue output, type conversion behavior on that string as applied to a specific property or property value type is not invoked, Generally, the purpose of a markup extension is to process a string and return an object without any type converter involved.

マークアップ拡張機能が型コンバーターではなく必要な場合、1 つの一般的な状況は既に存在するオブジェクトへの参照です。One common situation where a markup extension is necessary rather than a type converter is to make a reference to an object that already exists. せいぜい、ステートレスな型コンバーターは、望ましいことができない可能性がありますの新しいインスタンスを生成のみでした。At best, a stateless type converter could only generate a new instance, which might not be desirable. マークアップ拡張機能の詳細については、次を参照してください。マークアップ拡張機能と WPF XAMLします。For more information on markup extensions, see Markup Extensions and WPF XAML.

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

XAML パーサーの WPF と .NET Framework の実装では、ネイティブ型の変換処理、まだがプリミティブとして考えるが従来どおり型ではない特定の種類があります。In the WPF and .NET Framework implementation of the XAML parser, there are certain types that have native type conversion handling, yet are not types that might conventionally be thought of as primitives. このような型の例として、 DateTimeが挙げられます。An example of such a type is DateTime. この理由は、.NET Framework のアーキテクチャの動作方法に基づきは: 種類DateTimemscorlib、.NET で最も基本的なライブラリで定義されます。The reason for this is based on 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) so the usual type converter discovery mechanism by attributing cannot be supported. 代わりに、XAML パーサーでは、このようなネイティブの処理が必要な型のリストがあるし、通常のプリミティブの処理方法と同様にこれらを処理します。Instead, the XAML parser has a list of types that need such native processing and processes these similarly to how the true primitives are processed. (の場合にDateTimeへの呼び出しは、 Parse)。(In the case of DateTime this involves a call to Parse.)

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


Point以前は、クラスの例PointConverterが説明したようにします。In the Point example given previously, the class PointConverter was mentioned. XAML の目的で使用されるすべての型コンバーターは、基底クラスから派生するクラスを XAML の .NET 実装のTypeConverterします。For .NET implementations of XAML, all type converters that are used for XAML purposes are classes that derive from the base class TypeConverter. TypeConverterクラスは、XAML の存在の前のバージョンの .NET Framework に存在していた; ビジュアル デザイナーでのプロパティ ダイアログ ボックスの文字列変換を提供するその元の使用法の 1 つでした。The TypeConverter class existed in versions of .NET Framework that precede the existence of XAML; one of its original usages was to provide string conversion for property dialogs in visual designers. XAML の役割のTypeConverterを拡張して、文字列の属性値を解析し、可能性がありますの文字列に特定のオブジェクトのプロパティの実行時の値を処理できるようにする文字列に変換して、文字列からの変換の基本クラスには、属性としてシリアル化します。For XAML, the role of TypeConverter is expanded to include being the base class for to-string and from-string conversions that enable parsing a string attribute value, and possibly processing a run-time value of a particular object property back into a string for serialization as an attribute.

TypeConverter XAML 処理の目的の文字列から変換するために関連する 4 つのメンバーを定義します。TypeConverter defines four members that are relevant for converting to and from strings for XAML processing purposes:

最も重要なメソッドは、これらのうち、ConvertFromします。Of these, the most important method is ConvertFrom. このメソッドは、入力文字列を必要なオブジェクト型に変換します。This method converts the input string to the required object type. 厳密に言えば、ConvertFrom幅広い範囲の型をコンバーターの目的の型に変換、そのため、実行時の変換をサポートするなど、XAML の目的で XAML 以外の目的を提供するメソッドを実装する可能性があります処理できるコード パスのみである、String重要な入力します。Strictly speaking, the ConvertFrom method could be implemented to convert a much wider range of types into the converter's intended destination type, and thus serve purposes that extend beyond XAML such as supporting run-time conversions, but for XAML purposes it is only the code path that can process a String input that matters.

[次へ] の最も重要なメソッドはConvertToします。The next most important method is ConvertTo. かどうか、アプリケーションは、マークアップ表現に変換されます (たとえば、ファイルとして XAML に保存されます) 場合、ConvertToはマークアップ表現を生成を担当します。If an application is converted to a markup representation (for instance, if it is saved to XAML as a file), ConvertTo is responsible for producing a markup representation. この場合は、XAML の重要なコード パスは、渡すときに、destinationTypeStringします。In this case, the code path that matters for XAML is when you pass 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 have its own interpretation of what constitutes a valid string for a conversion, and can also use or ignore the type description passed as parameters. カルチャと XAML 型の変換に関して重要な考慮事項があります。There is an important consideration with regard to culture and XAML type conversion. XAML では、ローカライズ可能な文字列を使用して属性値としてはサポートされて完全。Using localizable strings as attribute values is entirely supported by XAML. XAML 属性値の型コンバーターが、必ずしも特定の言語の解析動作が関与するための特定のカルチャ要件型コンバーターの入力がサポートされていないためにそのローカライズ可能な文字列を使用して、使用して、en-USカルチャ。But using that localizable string as type converter input with specific culture requirements is not supported, because type converters for XAML attribute values involve a necessarily fixed-language parsing behavior, using en-US culture. この制限の設計上の理由の詳細については、XAML 言語仕様を参照してください ([MS XAML])。For more information on the design reasons for this restriction, you should consult the XAML language specification ([MS-XAML]).

カルチャが問題になることなどに、一部のカルチャが数値の小数点記号としてコンマを使用します。As an example where culture can be an issue, some cultures use a comma as their decimal point delimiter for numbers. WPF XAML の型コンバーターの多くが、これは、区切り記号としてコンマを使用する動作と競合がこの (一般的な X などの従来の慣習に基づき、Y フォーム、またはコンマ区切りリスト)。This will collide with the behavior that many of the WPF XAML type converters have, which is to use a comma as a delimiter (based on historical precedents such as the common X,Y form, or comma delimited lists). 周囲の XAML でカルチャを渡すことも (設定Languageまたはxml:langsl-SIカルチャ、この方法で小数点のコンマを使用するカルチャの例) で問題が解決しません。Even passing a culture in the surrounding XAML (setting Language or xml:lang to the sl-SI culture, an example of a culture that uses a comma for decimal in this way) 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 was in valid format, and can be converted by the TypeConverter implementation, then the returned object must support a cast to the type expected by the property. それ以外の場合、 ConvertFrom 実装は nullを返す必要があります。Otherwise, the ConvertFrom implementation must return null.

TypeConverter実装ことができます、変換に対して有効な文字列の構成要素の独自の解釈があるとも使用したり、パラメーターとして渡された型の説明やカルチャ コンテキストを無視します。Each TypeConverter implementation can have its own interpretation of what constitutes a valid string for a conversion, and can also use or ignore the type description or culture contexts 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 curly brace characters, particularly {, as a possible element of your string format. これらの文字は、マークアップ拡張シーケンスの開始および終了を示す文字として予約されています。These characters are reserved as the entry and exit for a markup extension sequence.

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.

として使用するのには、 TypeConverter 、XAML をサポートする実装、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) being supported as the value parameter. ときに、destinationTypeパラメーターは、型String、返されるオブジェクトとしてキャストできる必要がありますし、Stringします。When the destinationType parameter is the type String, then 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 you choose should be capable of generating the same value 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 is permitted to throw an exception in this case. 例外をスローする場合は、一部としてその変換を使用できないことを報告する必要がありますが、CanConvertTo実装ようにチェックのベスト プラクティスCanConvertTo例外を回避するためにはサポートされて最初。But 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 destinationType parameter is not of type String, you can choose your own converter handling. 通常、基本の実装、basemost での処理を元に戻すにはConvertTo特定の例外を発生させます。Typically, you would revert to base implementation handling, which in the basemost ConvertTo raises a specific exception.

CanConvertTo の実装Implementing CanConvertTo

CanConvertTo の実装は、 truedestinationType 型の場合は Stringを返し、それ以外の場合は基底の実装に任せる必要があります。Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer to the base implementation.

CanConvertFrom の実装Implementing CanConvertFrom

CanConvertFrom の実装は、 truesourceType 型の場合は Stringを返し、それ以外の場合は基底の実装に任せる必要があります。Your CanConvertFrom implementation should return true for sourceType of type String, and otherwise defer to the base implementation.

TypeConverterAttribute の適用Applying the TypeConverterAttribute

カスタム型コンバーターとして使用するために適用する必要があります、XAML プロセッサによってカスタム クラスの型コンバーター、 .NET Framework 属性.NET Framework attribute TypeConverterAttributeクラス定義にします。In order for your custom type converter to be used as the acting type converter for a custom class by a XAML processor, you must apply the .NET Framework 属性.NET Framework attribute 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 プロセッサは、プロパティの型が、カスタム クラスの型を使用して値を処理する場合、入力文字列と、オブジェクトのインスタンスを返します。With this attribute applied, 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. クラス定義に .NET Framework 属性.NET Framework attribute TypeConverterAttribute を適用する代わりに、プロパティ定義 (メイン定義内の get/set 実装ではなくメイン定義自体) に適用します。Instead of applying a .NET Framework 属性.NET Framework attribute 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 XAMLprocessor handles values of that property, it can process input strings and return object instances. プロパティの型コンバーターの手法は Microsoft .NET Framework とは、クラス定義を制御することはできませんし、適用できません他のいくつかのライブラリからプロパティの型を使用する場合に特に便利です、TypeConverterAttributeがあります。The per-property type converter technique is particularly 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.

関連項目See also