.NET XAML Hizmetleri ile kullanılmak üzere özel türler tanımlama

Makale
10/18/2023

İş nesneleri olan veya belirli çerçevelere bağımlılığı olmayan türler olan özel türler tanımladığınızda, XAML için izleyebileceğiniz bazı en iyi yöntemler vardır. Bu uygulamaları izlerseniz, .NET XAML Hizmetleri ve onun XAML okuyucuları ve XAML yazıcıları türünüzün XAML özelliklerini bulabilir ve XAML türü sistemini kullanarak bir XAML düğüm akışında uygun gösterim sağlayabilir. Bu konu, tür tanımları, üye tanımları ve clr türleri veya üyelerin attributing için en iyi yöntemleri açıklar.

XAML için Oluşturucu Desenleri ve Tür Tanımları

XAML'de nesne öğesi olarak örnek oluşturulabilmesi için özel bir sınıfın aşağıdaki gereksinimleri karşılaması gerekir:

Özel sınıfın genel olması ve parametresiz bir ortak oluşturucuyu kullanıma sunması gerekir. (Yapılara ilişkin notlar için aşağıdaki bölüme bakın.)
Özel sınıf iç içe geçmiş bir sınıf olmamalıdır. Tam ad yolundaki ek "nokta", sınıf-ad alanı bölümünü belirsiz hale getirir ve ekli özellikler gibi diğer XAML özellikleriyle çakışır. Bir nesnenin örneği bir nesne öğesi olarak oluşturulabiliyorsa, oluşturulan nesne, nesneyi temel türü olarak alan özelliklerin özellik öğesi formunu doldurabilir.

Değer dönüştürücüsünü etkinleştirirseniz, yine de bu ölçütleri karşılamayan türler için nesne değerleri sağlayabilirsiniz. Daha fazla bilgi için bkz . XAML için Tür Dönüştürücüleri ve İşaretlemeyi Genişletmeler.

Yapılar

Yapılar her zaman CLR tanımına göre XAML'de oluşturulabilir. Bunun nedeni, BIR CLR derleyicisi örtük olarak bir yapı için parametresiz oluşturucu oluşturmasıdır. Bu oluşturucu tüm özellik değerlerini varsayılan değerlerine başlatır.

Bazı durumlarda, bir yapı için varsayılan yapı davranışı arzu edilmez. Bunun nedeni, yapının değerleri doldurması ve kavramsal olarak birleşim olarak çalışması olabilir. Birleşim olarak, kapsanan değerlerin birbirini dışlayan yorumları olabilir ve bu nedenle özelliklerinin hiçbiri ayarlanamaz. WPF kelime dağarcığında böyle bir yapıya örnek olarak verilmiştir GridLength. Bu tür yapılar, değerlerin yapı değerlerinin farklı yorumlarını veya modlarını oluşturan dize kuralları kullanılarak öznitelik biçiminde ifade edilebilmesi için bir tür dönüştürücü uygulamalıdır. Yapı, parametresiz bir oluşturucu aracılığıyla kod oluşturma için benzer davranışlar da ortaya çıkarmalıdır.

Arabirimler

Arabirimler, temel alınan üye türleri olarak kullanılabilir. XAML türü sistemi atanabilir listeyi denetler ve değer olarak sağlanan nesnenin arabirime atanabilmesini bekler. İlgili atanabilir bir tür XAML oluşturma gereksinimlerini desteklediği sürece arabirimin XAML türü olarak nasıl sunulması gerektiği kavramı yoktur.

Fabrika Yöntemleri

Fabrika yöntemleri bir XAML 2009 özelliğidir. Nesnelerin parametresiz oluşturuculara sahip olması gerektiği XAML ilkesini değiştirir. Fabrika yöntemleri bu makalede belgelenmemiştir. Bkz . x:FactoryMethod Yönergesi.

Listelemeler

Numaralandırmaların XAML yerel tür dönüştürme davranışı vardır. XAML'de belirtilen numaralandırma sabit adları, temel alınan numaralandırma türüne göre çözümlenir ve numaralandırma değerini bir XAML nesne yazıcısına döndürür.

XAML, uygulanmış numaralandırmalar FlagsAttribute için bayrak stili kullanımını destekler. Daha fazla bilgi için bkz . Ayrıntılı XAML Söz Dizimi. (Ayrıntılı XAML Sözdizimi WPF hedef kitlesi için yazılır, ancak bu konudaki bilgilerin çoğu belirli bir uygulama çerçevesine özgü olmayan XAML ile ilgilidir.)

Üye Tanımları

Türler, XAML kullanımı için üyeleri tanımlayabilir. Bu tür XAML kullanılabilir olmasa bile türlerin XAML kullanılabilir üyeleri tanımlaması mümkündür. ClR devralma nedeniyle bu mümkündür. Üyeyi devralan bir tür tür olarak XAML kullanımını desteklediği ve üyenin temel türü için XAML kullanımını desteklediği veya yerel bir XAML söz dizimi kullanılabildiği sürece bu üye XAML tarafından kullanılabilir.

Özellikler

Tipik CLR ve erişimci desenlerini ve set dile uygun anahtar sözcükleri kullanarak özellikleri genel bir CLR get özelliği olarak tanımlarsanız, XAML türü sistemi özelliği ve IsWritePublicgibi özellikler için XamlMember sağlanan uygun bilgilerle bir üye olarak IsReadPublic bildirebilir.

Belirli özellikler uygulayarak metin söz dizimlerini TypeConverterAttributeetkinleştirebilir. Daha fazla bilgi için bkz . XAML için Tür Dönüştürücüleri ve İşaretlemeyi Genişletmeler.

Metin söz dizimi veya yerel XAML dönüştürmesi olmadığında ve işaretleme uzantısı kullanımı gibi daha fazla dolaylılık olmadığında, bir özelliğin türü (TargetType XAML türü sisteminde) hedef türü CLR türü olarak ele alarak bir örneği XAML nesne yazıcısına döndürebilmelidir.

XAML 2009 kullanılıyorsa, x:Başvuru İşaretlemesi Uzantısı , önceki önemli noktalar karşılanmadıysa değerleri sağlamak için kullanılabilir; ancak bu, tür tanımı sorunundan daha fazla bir kullanım sorunudur.

Ekinlikler

Olayları bir genel CLR olayı olarak tanımlarsanız, XAML türü sistemi ile olayı bir üye IsEvent olarak truebildirebilir. Olay işleyicilerini bağlamak .NET XAML Hizmetleri özellikleri kapsamında değildir; kablolar belirli çerçevelere ve uygulamalara bırakılır.

Yöntemler

Yöntemler için satır içi kod, varsayılan bir XAML özelliği değildir. Çoğu durumda, XAML'deki yöntem üyelerine doğrudan başvurmazsınız ve XAML'deki yöntemlerin rolü yalnızca belirli XAML desenleri için destek sağlamaktır. x:FactoryMethod Yönergesi bir özel durumdur.

Alanlar

CLR tasarım yönergeleri statik olmayan alanları önerilmez. Statik alanlar için, statik alan değerlerine yalnızca x:Static Markup Extension aracılığıyla erişebilirsiniz; bu durumda, bir alanı x:Statik kullanımlar için kullanıma sunma amacıyla CLR tanımında özel bir şey yapmıyorsunuz.

Eklenebilir Üyeler

Eklenebilir üyeler, tanımlama türündeki bir erişimci yöntemi deseni aracılığıyla XAML'ye sunulur. Tanımlama türünün kendisinin nesne olarak XAML kullanılabilir olması gerekmez. Aslında yaygın bir desen, rolü eklenebilir üyeye sahip olmak ve ilgili davranışları uygulamak olan ancak kullanıcı arabirimi gösterimi gibi başka bir işleve hizmet etmeyen bir hizmet sınıfını bildirmektir. Aşağıdaki bölümlerde PropertyName yer tutucusu eklenebilir üyenizin adını temsil eder. Bu ad XamlName Dilbilgisinde geçerli olmalıdır.

Bu desenler ve bir türün diğer yöntemleri arasındaki ad çakışmalarına dikkat edin. Desenlerden biriyle eşleşen bir üye varsa, amacınız bu olmasa bile XAML işlemcisi tarafından eklenebilir üye kullanım yolu olarak yorumlanabilir.

GetPropertyName Erişimcisi

Erişimcinin GetPropertyName imzası şu şekilde olmalıdır:

public static object GetPropertyName(object target)

target Nesnesi, uygulamanızda daha belirli bir tür olarak belirtilebilir. Bunu, eklenebilir üyenizin kullanımını kapsamak için kullanabilirsiniz; hedeflenen kapsamınızın dışındaki kullanımlar, daha sonra bir XAML ayrıştırma hatası tarafından ortaya çıkarılmış geçersiz atama özel durumları oluşturur. Parametre adı target bir gereksinim değildir, ancak çoğu uygulamada kural tarafından adlandırılır target .
Dönüş değeri, uygulamanızda daha belirli bir tür olarak belirtilebilir.

Eklenebilir üyenin öznitelik kullanımı için etkinleştirilmiş metin TypeConverter söz dizimini desteklemek için erişimciye GetPropertyName uygulayınTypeConverterAttribute. yerine set uygulaması get sezgisel olmayabilir; ancak bu kural, tasarımcı senaryolarında yararlı olan, serileştirilebilir salt okunur eklenebilir üyeler kavramını destekleyebilir.

SetPropertyName Erişimcisi

Erişimcinin SetPropertyName imzası şu şekilde olmalıdır:

public static void SetPropertyName(object target, object value)

target Nesnesi, önceki bölümde açıklanan mantık ve sonuçlarla uygulamanızda daha belirli bir tür olarak belirtilebilir.
value Nesnesi, uygulamanızda daha belirli bir tür olarak belirtilebilir.

Bu yöntemin değerinin genellikle öznitelik biçimindeki XAML kullanımından gelen giriş olduğunu unutmayın. Öznitelik formundan bir metin söz dizimi için değer dönüştürücü desteği olmalıdır ve s erişimcisinde GetPropertyNameözniteliğiniz olmalıdır.

Eklenebilir Üye Mağazaları

Erişimci yöntemleri genellikle eklenebilir üye değerlerini bir nesne grafiğine yerleştirmek veya nesne grafı dışından değer alıp bunları düzgün bir şekilde serileştirmek için bir araç sağlamak için yeterli değildir. Bu işlevselliği sağlamak için, target önceki erişimci imzalarındaki nesnelerin değerleri depolayabilmesi gerekir. Depolama mekanizması, üyenin, eklenebilir üyenin üye listesinde olmadığı hedeflere eklenebilir olduğu eklenebilir üye ilkesiyle tutarlı olmalıdır. .NET XAML Hizmetleri, API'ler IAttachedPropertyStore ve AttachablePropertyServicesaracılığıyla eklenebilir üye depoları için bir uygulama tekniği sağlar. IAttachedPropertyStore XAML yazıcıları tarafından mağaza uygulamasını bulmak için kullanılır ve erişimcilerin türüne target uygulanmalıdır. Statik AttachablePropertyServices API'ler, erişimcilerin gövdesinde kullanılır ve eklenebilir üyeye tarafından başvurur AttachableMemberIdentifier.

XAML türü sistem bilgilerini .NET XAML Hizmetlerine raporlamak için türlerinizin, üyelerinizin ve derlemelerinizin doğru şekilde dağıtılması önemlidir. Aşağıdaki durumlardan biri geçerliyse raporlama XAML türü sistem bilgileri uygundur:

Türlerinizi doğrudan .NET XAML Hizmetleri XAML okuyucularını ve XAML yazıcılarını temel alan XAML sistemleriyle kullanmak istiyorsunuz.
Bu XAML okuyucularını ve XAML yazıcılarını temel alan bir XAML kullanan çerçeve tanımlar veya kullanırsınız.

Özel türlerinizin XAML desteğiyle ilgili XAML ile ilgili her bir özniteliğin listesi için bkz . Özel Türler ve Kitaplıklar için XAML ile İlgili CLR Öznitelikleri.

Kullanım

Özel türlerin kullanımı, işaretleme yazarının özel türü içeren derleme ve CLR ad alanı için bir ön ek eşlemesi gerekir. Bu yordam bu konuda belgelenmemiştir.

Erişim Düzeyi

XAML, erişim düzeyine sahip türleri yüklemek ve örneklemek için bir internal araç sağlar. Bu özellik, kullanıcı kodunun kendi türlerini tanımlayabilmesi ve aynı kullanıcı kodu kapsamının parçası olan işaretlemeden bu sınıfların örneğini oluşturabilmesi için sağlanır.

Kullanıcı kodu, kullanıcı arabirimi davranışını yeniden düzenlemenin bir yolu olarak amaçlanan ancak destek sınıfı erişim düzeyiyle public bildirilerek ima edilebilecek herhangi bir olası uzantı mekanizmasının parçası olarak değil her tanımlandığında UserControl WPF'den bir örnektir. Bu tür bir UserControl , yedekleme kodu XAML türü olarak başvurulan aynı derlemede derlenmişse erişim ile internal bildirilebilir.

Tam güven altında XAML yükleyen ve kullanan XamlObjectWriterbir uygulama için, erişim düzeyine sahip internal sınıfların yüklenmesi her zaman etkindir.

Kısmi güven altında XAML yükleyen bir uygulama için, API'yi kullanarak XamlAccessLevel erişim düzeyi özelliklerini denetleyebilirsiniz. Ayrıca, erteleme mekanizmalarının (WPF şablon sistemi gibi) tüm erişim düzeyi izinlerini yayabilmesi ve bunları son çalışma zamanı değerlendirmeleri için koruyabilmesi gerekir; bu, bilgiler geçirilerek XamlAccessLevel dahili olarak işlenir.

WPF Uygulaması

WPF XAML, BAML kısmi güven altında yüklenirse, BAML kaynağı olan derleme için erişimin kısıtlandığı AssemblyAccessTo kısmi güven erişim modeli kullanır. Erteleme için WPF, erişim düzeyi bilgilerini geçirmek için bir mekanizma olarak kullanır IXamlObjectWriterFactory.GetParentSettings .

WPF XAML terminolojisinde iç tür, başvuran XAML'yi de içeren aynı derleme tarafından tanımlanan bir türdür. Böyle bir tür, eşlemenin assembly= bölümünü kasıtlı olarak atlayan bir XAML ad alanıyla eşlenebilir. Örneğin, xmlns:local="clr-namespace:WPFApplication1". BAML bir iç türe başvurursa ve bu tür erişim düzeyine sahipse internal , bu derleme için bir GeneratedInternalTypeHelper sınıf oluşturur. kullanmaktan kaçınmak GeneratedInternalTypeHelperistiyorsanız, erişim düzeyini kullanmanız public veya ilgili sınıfı ayrı bir derlemeye ayırmanız ve bu derlemeyi bağımlı hale getirmeniz gerekir.