TypeConverters ve XAMLTypeConverters and XAML

Bu konu, genel XAML dil özelliği olarak dizeden tür dönüştürme amacı tanıtır.This topic introduces the purpose of type conversion from string as a general XAML language feature. .NET Framework'teki TypeConverter sınıfı XAML öznitelik kullanımı bir özellik değeri olarak kullanılabilecek özel bir yönetilen sınıf uygulamasını bir parçası olarak belirli bir amaca hizmet.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. Özel bir sınıf yazma ve XAML ayarlanabilir öznitelik değeri olarak kullanılabilmesi için bir sınıfın örneklerini istiyorsanız uygulamak ihtiyacınız olabilecek bir TypeConverterAttribute sınıfınıza, özel bir yazma TypeConverter sınıfı veya her ikisini de.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.

Tür dönüştürme kavramlarıType Conversion Concepts

XAML ve dize değerleriXAML and String Values

Bir XAML dosyasında bir öznitelik değeri ayarladığınızda, ilk değeri bir dize içinde salt metin türüdür.When you set an attribute value in a XAML file, the initial type of that value is a string in pure text. Hatta diğer ilkel gibi Double başlangıçta metin dizelerdir XAML işlemci için.Even other primitives such as Double are initially text strings to a XAML processor.

XAML işlemci bir öznitelik değeri işlemek için iki parça bilgi gerekir.A XAML processor needs two pieces of information in order to process an attribute value. Bilgi ilk parçasını ayarlanan özelliğin bir değer türüdür.The first piece of information is the value type of the property that is being set. XAML içinde işlenir ve bir öznitelik değeri tanımlayan herhangi bir dize olmalıdır sonuçta dönüştürülecek veya o türün değerine çözümlendi.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. Değer (örneğin, sayısal bir değer) XAML ayrıştırıcı tarafından anlaşılan basit bir tür ise, dize doğrudan dönüştürme denenir.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. Bir sabit listesi değeri ise, dize, numaralandırma, adlandırılmış bir sabit bir adı eşleşme olup olmadığını denetlemek için kullanılır.If the value is an enumeration, the string is used to check for a name match to a named constant in that enumeration. Değer ne ayrıştırıcı anlaşılan bir temel ya da bir numaralandırma sonra söz konusu türü ise sağlayabilir veya bir dönüştürülmüş dizesine dayalı bir değer türü örneği olmalıdır.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. Bu, bir tür dönüştürücüsü sınıfı belirterek gerçekleştirilir.This is done by indicating a type converter class. Tür dönüştürücüsünü etkili bir şekilde kod içinde .NET kodda çağırır XAML senaryosu için hem de başka bir sınıf değerlerini sağlamak için bir yardımcı sınıftır.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 içinde mevcut türü dönüştürme davranışını kullanarakUsing Existing Type Conversion Behavior in XAML

Temel XAML kavramları, aşinalık bağlı olarak, zaten türü dönüştürme davranışını temel uygulama XAML fark etmeden kullanıyor olabilir.Depending on your familiarity with the underlying XAML concepts, you may already be using type conversion behavior in basic application XAML without realizing it. Örneğin, WPF türünde bir değer alan özellikleri yüzlerce tanımlar Point.For instance, WPF defines literally hundreds of properties that take a value of type Point. A Point iki boyutlu bir koordinat alanında bir koordinat açıklayan bir değerdir ve aslında iki önemli özellikleri vardır: X ve Y.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 içinde bir noktaya belirttiğinizde, (genellikle bir virgül) sınırlayıcı bir dize olarak arasında belirtmeden X ve Y sağladığınız değerler.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. Örneğin: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">.For example: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">.

Bu basit tür bile Point ve basit kullanımını XAML içinde bir tür dönüştürücüsü içerir.Even this simple type of Point and its simple usage in XAML involve a type converter. Bu durumda, sınıf, PointConverter.In this case that is the class PointConverter.

Tür dönüştürücü Point Süren tüm özellikleri biçimlendirme kullanımları sınıf düzeyinde ölçeklendirerek tanımlanan Point.The type converter for Point defined at the class level streamlines the markup usages of all properties that take Point. Bir tür dönüştürücüsü Burada, aşağıdakiler gerekir. daha önce gösterilen aynı örneği için çok daha ayrıntılı biçimlendirmesini:Without a type converter here, you would need the following much more verbose markup for the same example shown previously:

<LinearGradientBrush>

<LinearGradientBrush.StartPoint>

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

</LinearGradientBrush.StartPoint>

<LinearGradientBrush.EndPoint>

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

</LinearGradientBrush.EndPoint>

<LinearGradientBrush>

Tür dönüştürme dize veya daha ayrıntılı bir eşdeğer sözdizimi kullanmak için genellikle bir kodlama stili bir seçimdir.Whether to use the type conversion string or a more verbose equivalent syntax is generally a coding style choice. XAML araçları akışınız, değerlerin nasıl ayarlanacağı da etkileyebilir.Your XAML tooling workflow might also influence how values are set. Bazı XAML araçları gidiş dönüş Tasarımcı görünümleri ya da kendi seri hale getirme mekanizması için daha kolay olduğundan, en ayrıntılı form biçimlendirme yayma eğilimindedir.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.

Var olan tür dönüştürücüleri genellikle bulunması WPF ve .NET Framework türleri üzerinde bir sınıf (ya da özellik) uygulanan bir varlığını denetleyerek 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. Bu öznitelik, XAML amacıyla hem de büyük olasılıkla diğer amaçlar için bu türü değerlerinin destekleyen tür dönüştürücüsünü sınıfı adını vereceğiz.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.

Tür dönüştürücüleri ve İşaretleme uzantılarıType Converters and Markup Extensions

İşaretleme uzantıları ve tür dönüştürücüleri XAML işlemci davranışı ve uygulanacak olan senaryoları açısından dikgen rolleri doldurun.Markup extensions and type converters fill orthogonal roles in terms of XAML processor behavior and the scenarios that they are applied to. Bağlam için işaretleme uzantısı kullanımları kullanılabilir olsa da, burada bir değerdir genellikle bir işaretleme uzantısı sağlar. özellikleri türü dönüştürme davranışını işaretleme uzantısı uygulamalarında işaretlenmemiştir.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. Diğer bir deyişle, bile bir işaretleme uzantısı bir metin dizesi olarak döndürür, ProvideValue çıkışı, belirli özellik ya da özellik değeri türü uygulanan olarak bu dize türü dönüştürme davranışını değil çağrılır, genellikle, bir işaretleme uzantısı amacı işlemidir bir dize ve ilgili herhangi bir tür dönüştürücüsü olmadan bir nesne döndürür.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.

İşaretleme uzantısı yerine bir tür dönüştürücüsü gerekli olduğu bir yaygın durum zaten var. bir nesneye bir başvuru sağlamaktır.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. En iyi durum bilgisi olmayan bir tür dönüştürücüsü yalnızca istenen olmayabilir yeni bir örneği oluşturabilir.At best, a stateless type converter could only generate a new instance, which might not be desirable. Biçimlendirme uzantıları hakkında daha fazla bilgi için bkz. biçimlendirme uzantıları ve WPF XAML.For more information on markup extensions, see Markup Extensions and WPF XAML.

Yerel tür dönüştürücüleriNative Type Converters

WPF ve .NET Framework uygulamasında XAML ayrıştırıcı, henüz genel temel olarak zorlayıcı olabilir türleri değil, yerel bir tür dönüştürme işleme sahip bazı türleri vardır.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. Böyle bir türü örneğidir DateTime.An example of such a type is DateTime. Bunun nedeni, .NET Framework mimarisini nasıl çalıştığını temel alır: türü DateTime mscorlib, .NET en temel kitaplığında tanımlanır.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 bir bağımlılık tanıtan başka bir bütünleştirilmiş koddan gelen bir öznitelik ile öznitelikli izin verilmiyor (TypeConverterAttribute sisteminden alınmıştır) normal türü dönüştürücü bulma mekanizmasından'öznitelik atanıyor tarafından desteklenebilmesi için.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. Bunun yerine, XAML ayrıştırıcı gibi yerel işlenmesi gereken türlerinin bir listesi vardır ve bunlar true temelleri nasıl işlendiği için benzer şekilde işler.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. (Durumunda DateTime bu bir çağrı içerir Parse.)(In the case of DateTime this involves a call to Parse.)

Tür dönüştürücü uygulamaImplementing a Type Converter

TypeConverterTypeConverter

İçinde Point sınıfı daha önce verilen örnek PointConverter bahsedilen.In the Point example given previously, the class PointConverter was mentioned. XAML .NET uygulamaları için XAML amaçlarıyla kullanılan tüm tür dönüştürücüleri temel sınıfından türetilir sınıflardır 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 Sınıfı XAML varlığını önünde .NET Framework sürümleri içinde vardı; kendi özgün kullanımlarından dize dönüştürme için görsel tasarımcılar özelliği iletişim kutularında sağlamak için.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, rolü için TypeConverter öznitelik dize ayrıştırma ve büyük olasılıkla bir dize halinde geri belirli nesne özelliği çalışma zamanı değerini işleme-dize ve dize öğesinden dönüştürme için temel sınıfı olan içerecek şekilde genişletilmiş özniteliği olarak seri hale getirme.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 ve dizeleri XAML işleme amacıyla bu nesnelerden dönüştürme için uygun olan dört üyeleri tanımlar:TypeConverter defines four members that are relevant for converting to and from strings for XAML processing purposes:

Bu en önemli yöntemdir ConvertFrom.Of these, the most important method is ConvertFrom. Bu yöntem, Giriş dizesinin gerekli nesne türüne dönüştürür.This method converts the input string to the required object type. NET olarak söylemek gerekirse, ConvertFrom yönteminin çok geniş bir tür Dönüştürücüsü'nın hedeflenen hedef türüne dönüştürün ve bu nedenle çalışma zamanı dönüştürmeleri destekleyen gibi ancak XAML amacıyla XAML genişletmek amacıyla hizmet uygulanmasını işleyebilen kod yolu olan bir String önemli giriş.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.

Sonraki en önemli yöntemdir ConvertTo.The next most important method is ConvertTo. (Örneğin, XAML dosyası olarak kaydedilir) bir uygulama için bir biçimlendirme gösterimi dönüştürülür varsa, ConvertTo biçimlendirme gösterimi üretmek için sorumludur.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 için önemli kod yolu geçirdiğinizde bu durumda olduğu bir destinationType , String .In this case, the code path that matters for XAML is when you pass a destinationType of String .

CanConvertTo ve CanConvertFrom yeteneklerini hizmet sorgu oluştururken kullanılan destek yöntemleri TypeConverter uygulaması.CanConvertTo and CanConvertFrom are support methods that are used when a service queries the capabilities of the TypeConverter implementation. Döndürmek için bu yöntemleri uygulamalıdır true , türe özgü durumda, dönüştürücü eşdeğer dönüştürme yöntemleri destekler.You must implement these methods to return true for type-specific cases that the equivalent conversion methods of your converter support. XAML amacıyla, bu genellikle anlamına gelir String türü.For XAML purposes, this generally means the String type.

Kültür bilgilerini ve XAML için tür dönüştürücüleriCulture Information and Type Converters for XAML

Her TypeConverter uygulama bir dönüştürme için geçerli bir dize nelerden kendi yorumlama sahip ve ayrıca kullanın veya parametre olarak geçirilen türü açıklaması yoksay.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. Kültür ve XAML tür dönüştürme ile ilgili önemli bir husus vardır.There is an important consideration with regard to culture and XAML type conversion. Yerelleştirilebilir Dize öznitelik değerleri kullanılarak, tamamen XAML tarafından desteklenir.Using localizable strings as attribute values is entirely supported by XAML. Ancak, belirli bir kültürün gereksinimleri ile dönüştürücü giriş türü desteklenmediğinden bu yerelleştirilebilir dize kullanarak XAML öznitelik değerleri için tür dönüştürücüleri mutlaka sabit dil ayrıştırma davranışı hatalarıyla ilgili olduğundan, kullanarak en-US kültür.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. Bu kısıtlama tasarım nedenleri hakkında daha fazla bilgi için XAML dil belirtimi danışmalıdır ([MS-XAML]).For more information on the design reasons for this restriction, you should consult the XAML language specification ([MS-XAML]).

Burada kültür bir sorun olabilir örneğin, bazı kültürlerde sayılar için ondalık ayırıcı olarak virgül kullanın.As an example where culture can be an issue, some cultures use a comma as their decimal point delimiter for numbers. Bu, ayırıcı olarak virgül WPF XAML tür dönüştürücüleri çoğunu içeren davranış birbiriyle çakışır (Geçmiş Etkileyenler gibi ortak X bağlı olarak, Y form veya virgülle ayrılmış listeleri).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). Bir kültür çevreleyen XAML içinde bile geçirme (ayar Language veya xml:lang için sl-SI kültür, virgül, ondalık bu şekilde kullanımları bir kültür örneği) sorunu çözmez.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 uygulamaImplementing ConvertFrom

Olarak kullanılabilir bir TypeConverter XAML, destekleyen bir uygulama ConvertFrom yöntemi Bu dönüştürücü için bir dize olarak kabul etmelisiniz value parametresi.To be usable as a TypeConverter implementation that supports XAML, the ConvertFrom method for that converter must accept a string as the value parameter. Dize geçerli biçimlendirmek ve tarafından dönüştürülebilir olup olmadığını TypeConverter uygulama sonra döndürülen nesne bir özellik tarafından beklenen türe dönüştürme desteklemesi gerekir.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. Aksi takdirde, ConvertFrom uygulama döndürmelidir null.Otherwise, the ConvertFrom implementation must return null.

Her TypeConverter uygulama bir dönüştürme için geçerli bir dize nelerden kendi yorumlama sahip ve ayrıca kullanın veya parametre olarak geçirilen tür açıklaması veya kültür bağlamı yoksay.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. Ancak, işleme WPF XAML değerleri türü açıklaması içeriği tüm durumlarda geçebilir değil ve kültüre göre de geçirmemesi 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.

Not

Küme ayracı karakterleri özellikle kullanmayın {, dize biçiminiz olası öğesi olarak.Do not use the curly brace characters, particularly {, as a possible element of your string format. Bu karakterler, giriş ve çıkış bir işaretleme uzantısı sırası olarak ayrılmıştır.These characters are reserved as the entry and exit for a markup extension sequence.

ConvertTo uygulamaImplementing ConvertTo

ConvertTo Potansiyel olarak seri hale getirme desteği için kullanılır.ConvertTo is potentially used for serialization support. Serileştirme desteğini ConvertTo özel türünüzü ve kendi türü için dönüştürücü mutlak bir gereksinim değildir.Serialization support through ConvertTo for your custom type and its type converter is not an absolute requirement. Ancak, bir denetimi uygulamak veya tasarım sınıfınızın veya özellikleri bir parçası serileştirilmesi kullanarak, uygulamalıdır 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.

Olarak kullanılabilir bir TypeConverter XAML, destekleyen bir uygulama ConvertTo yöntemi Bu dönüştürücü için kabul etmelisiniz desteklenmekte türü (veya bir değer) örneği olarak value parametresi.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. Zaman destinationType parametre türüdür String, döndürülen nesne olarak yayınlanması gereken sonra String.When the destinationType parameter is the type String, then the returned object must be able to be cast as String. Döndürülen dize bir seri hale getirilmiş değerini temsil etmelidir value.The returned string must represent a serialized value of value. İdeal olarak, seçtiğiniz serileştirme biçimi bu dize geçirilmiş aynı değeri oluşturma yeteneği olmalıdır ConvertFrom önemli bilgi kaybı olmadan aynı dönüştürücü uygulamasıdır.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.

Değeri serileştirilemez veya seri hale getirme, dönüştürücü desteklemiyor ConvertTo uygulama döndürmelidir nullve bu durumda bir özel durum oluşturmasına izin verilir.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. Ancak özel durumlar ise bir parçası olarak bu dönüştürme kullanılacak yükleyememesine raporlamalıdır, CanConvertTo uygulama böylece ile denetimi en iyi CanConvertTo ilk özel durumları engellemek için desteklenir.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.

Varsa destinationType parametresi türü değil String, kendi dönüştürücü işleme seçebilirsiniz.If destinationType parameter is not of type String, you can choose your own converter handling. Genellikle, işleme, hangi basemost temel uygulamaya geri ConvertTo belirli bir özel durum oluşturur.Typically, you would revert to base implementation handling, which in the basemost ConvertTo raises a specific exception.

CanConvertTo uygulamaImplementing CanConvertTo

CanConvertTo Uygulamasına dönmesi gerektiğini true için destinationType türü Stringve aksi için temel uygulama erteleyin.Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer to the base implementation.

CanConvertFrom uygulamaImplementing CanConvertFrom

CanConvertFrom Uygulamasına dönmesi gerektiğini true için sourceType türü Stringve aksi için temel uygulama erteleyin.Your CanConvertFrom implementation should return true for sourceType of type String, and otherwise defer to the base implementation.

TypeConverterAttribute uygulanıyorApplying the TypeConverterAttribute

Sırayla olarak görev yapan kullanılmak üzere kendi özel tür dönüştürücü için tür dönüştürücüsünü bir XAML işlemcisi tarafından özel bir sınıf için uygulamalısınız .NET Framework özniteliği.NET Framework attribute TypeConverterAttribute sınıf tanımı.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 özniteliği.NET Framework attribute TypeConverterAttribute to your class definition. ConverterTypeName Özniteliğiyle belirtin, özel bir tür dönüştürücüsü türü adı olması gerekir.The ConverterTypeName that you specify through the attribute must be the type name of your custom type converter. Bu özniteliği uygulandı, ile XAML işlemci değerleri nerede özellik türü, özel bir sınıf türünü kullanan işlediğinde, bu giriş dizeleri ve nesne örneği döndürür.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.

Özellik başına temelinde bir tür dönüştürücüsü de sağlayabilirsiniz.You can also provide a type converter on a per-property basis. Uygulama yerine bir .NET Framework özniteliği.NET Framework attribute TypeConverterAttribute isteğe bağlı olarak sınıf tanımının bir özellik tanımı için geçerlidir (ana tanım değil get / set içindeki uygulamaları).Instead of applying a .NET Framework özniteliği.NET Framework attribute TypeConverterAttribute to the class definition, apply it to a property definition (the main definition, not the get/set implementations within it). Özelliğin türü, özel bir tür dönüştürücüsü tarafından işlenen türüyle eşleşmelidir.The type of the property must match the type that is processed by your custom type converter. Bu özniteliği uygulandı, ile bir XAMLprocessor bu özellik değerlerini işlediğinde, bu işlem giriş dizesi ve nesne örneği döndürür.With this attribute applied, when a XAMLprocessor handles values of that property, it can process input strings and return object instances. Özellik başına türü dönüştürücü özellik türü Microsoft .NET Framework veya sınıf tanımı kontrol ve uygulanamıyor burada bazı diğer kitaplığı kullanmayı tercih ederseniz özellikle kullanışlı bir tekniktir bir TypeConverterAttribute vardır.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.

Ayrıca Bkz.See Also

TypeConverter
XAML'ye Genel Bakış (WPF)XAML Overview (WPF)
İşaretleme Uzantıları ve WPF XAMLMarkup Extensions and WPF XAML
Ayrıntılı XAML SözdizimiXAML Syntax In Detail