XAML için işaretleme uzantılarına genel bakış

Makale
10/18/2023

İşaretleme uzantıları, ilkel veya belirli bir XAML türü olmayan bir değer elde etmek için kullanılan bir XAML tekniğidir. Öznitelik kullanımı için, işaretleme uzantıları işaretleme uzantısı kapsamını girmek için bir açılış küme ayracı { bilinen karakter dizisini ve çıkmak için bir kapanış küme ayracı } kullanır. .NET XAML Hizmetleri'ni kullanırken System.Xaml derlemesinden önceden tanımlanmış XAML dil işaretleme uzantılarından bazılarını kullanabilirsiniz. Ayrıca, System.Xaml içinde tanımlanan sınıfından MarkupExtension alt sınıf oluşturabilir ve kendi işaretleme uzantılarınızı tanımlayabilirsiniz. Ya da zaten bu çerçeveye başvuruyorsanız belirli bir çerçeve tarafından tanımlanan işaretleme uzantılarını kullanabilirsiniz.

Bir işaretleme uzantısı kullanımına erişildiğinde, XAML nesne yazıcısı geçersiz kılmadaki bir hizmet bağlantı noktası aracılığıyla özel MarkupExtension bir sınıfa MarkupExtension.ProvideValue hizmet sağlayabilir. Hizmetler, kullanım hakkında bağlamı, nesne yazıcısının belirli özelliklerini, XAML şema bağlamını vb. elde etmek için kullanılabilir.

XAML tanımlı işaretleme uzantıları

XAML dil desteği için .NET XAML Hizmetleri tarafından çeşitli işaretleme uzantıları uygulanır. Bu işaretleme uzantıları, dil olarak XAML belirtiminin bölümlerine karşılık gelir. Bunlar genellikle yaygın kullanımda görüldüğü gibi söz dizimindeki ön ek tarafından x: tanımlanabilir. Bu XAML dil öğeleri için .NET XAML Hizmetleri uygulamalarının tümü temel sınıftan MarkupExtension türetilir.

Dekont

Ön x: ek, bir XAML üretiminin kök öğesinde XAML dil ad alanının tipik XAML ad alanı eşlemesi için kullanılır. Örneğin, çeşitli çerçeveler için Visual Studio projesi ve sayfa şablonları bu x: eşlemeyi kullanarak bir XAML dosyası başlatır. Kendi XAML ad alanı eşlemenizde farklı bir ön ek belirteci seçebilirsiniz, ancak bu belgelerde, belirli bir çerçevenin varsayılan x: XAML ad alanı veya diğer rastgele CLR veya XML ad alanlarının aksine, XAML dili XAML ad alanının tanımlı bir parçası olan varlıkları tanımlamanın bir aracı olarak varsayılan eşleme varsayılır.

x:Tür

x:TypeType adlandırılmış tür için nesnesini sağlar. Bu işlevsellik en sık, temel CLR türü ve tür türetmesini gruplandırma adı veya tanımlayıcı olarak kullanan erteleme mekanizmalarında kullanılır. WPF stilleri ve şablonları ve bunların özellik kullanımı TargetType belirli bir örnektir. Daha fazla bilgi için bkz . x:Type biçimlendirme uzantısı.

x:Static

x:Static , bir özelliğin değerinin doğrudan türü olmayan ancak bu türe değerlendirilebilen değer türü kod varlıklarından statik değerler üretir. Bu, bir tür tanımında zaten iyi bilinen sabitler olarak mevcut olan değerleri belirtmek için yararlıdır. Daha fazla bilgi için bkz . x:Static Markup Extension.

x:Null

x:Nullnull bir XAML üyesi için değer olarak belirtir. Belirli türlerin tasarımına veya daha büyük çerçeve kavramlarına bağlı olarak, null her zaman bir özellik için varsayılan değer veya boş dize özniteliğinin zımni değeri değildir. Daha fazla bilgi için bkz . x:Null biçimlendirme uzantısı.

x:Dizi

x:Array temel öğeler ve denetim modelleri tarafından sağlanan koleksiyon desteğinin kasıtlı olarak kullanılmadığı durumlarda XAML söz diziminde genel dizilerin oluşturulmasını destekler. Daha fazla bilgi için bkz . x:Dizi İşaretlemeyi Uzantısı. Özellikle XAML 2009'da dizilere uzantı yerine dil temelleri olarak erişilir. Daha fazla bilgi için bkz . XAML 2009 Dil Özellikleri.

x:Başvuru

x:Reference , özgün (2006) dil kümesinin uzantısı olan XAML 2009'un bir parçasıdır. x:Reference , nesne grafında var olan başka bir nesneye başvurudur. Bu nesne, tarafından x:Nametanımlanır. Daha fazla bilgi için bkz . x:Başvuru biçimlendirme uzantısı.

Diğer x: Yapılar

XAML dil özelliklerini destekleyen başka x: yapılar da vardır, ancak bunlar işaretleme uzantıları olarak uygulanmaz. Daha fazla bilgi için bkz. XAML Ad Alanı (x:) Dil Özellikleri.

MarkupExtension Temel Sınıfı

System.Xaml'de XAML okuyucularının ve XAML yazıcılarının varsayılan uygulamalarıyla etkileşim kurabilen özel bir işaretleme uzantısı tanımlamak için soyut MarkupExtension sınıftan bir sınıf türetebilirsiniz. Bu sınıfın geçersiz kılmak için tek bir yöntemi vardır: ProvideValue. Ayrıca işaretleme uzantısı kullanımına yönelik bağımsız değişkenleri ve eşleşen ayarlanabilir özellikleri desteklemek için ek oluşturucular tanımlamanız gerekebilir.

aracılığıyla ProvideValue, özel bir işaretleme uzantısının, işaretleme uzantısının bir XAML işlemcisi tarafından çağrıldığı ortamı bildiren bir hizmet bağlamı erişimi vardır. Yükleme yolunda bu genellikle bir XamlObjectWriterşeklindedir. Kaydetme yolunda bu genellikle bir XamlXmlWriterşeklindedir. Her bir hizmet bağlamını bir hizmet sağlayıcısı deseni uygulayan bir iç XAML hizmet sağlayıcısı bağlam sınıfı olarak rapor eder. Kullanılabilir hizmetler ve bunların neyi temsil ettikleri hakkında daha fazla bilgi için bkz . XAML için Tür Dönüştürücüleri ve İşaretlem Uzantıları.

İşaretlemeyi genişletme sınıfınız genel erişim düzeyi kullanmalıdır; XAML işlemcilerinin hizmetlerini kullanabilmesi için her zaman işaretleme uzantısının destek sınıfının örneğini oluşturabilmesi gerekir.

Özel İşaretlemeyi Genişletme için Destek Türünü Tanımlama

.NET XAML Hizmetleri'ni veya .NET XAML Hizmetleri'ni temel alan çerçeveler kullandığınızda, işaretleme uzantısı destek türünü adlandırmak için iki seçeneğiniz vardır. Tür adı, XAML nesne yazıcılarının XAML'de bir işaretleme uzantısı kullanımıyla karşılaştıklarında bir işaretleme uzantısı destek türüne erişmeye ve çağırmaya çalışmalarıyla ilgilidir. Aşağıdaki adlandırma stratejilerinden birini kullanın:

Tür adını XAML işaretleme kullanım belirteciyle tam olarak eşleşecek şekilde adlandırın. Örneğin, uzantı {Collate ...} kullanımını desteklemek için destek türünü Collateolarak adlandırın.
Tür adını kullanım dizesi belirteci ve sonek Extensionolarak adlandırın. Örneğin, uzantı {Collate ...} kullanımını desteklemek için destek türünü CollateExtensionolarak adlandırın.

Arama sırası, Extensionönce -suffixed sınıf adını aramak ve ardından sonek olmadan Extension sınıf adını aramaktır.

İşaretlemeyi kullanım açısından bakıldığında, kullanımın Extension bir parçası olarak soneki de dahil olmak üzere geçerlidir. Ancak bu, sınıf adının gerçekten bir parçası gibi Extension davranır ve destek sınıfının son eki yoksa XAML nesne yazıcıları bu kullanım için bir işaretleme uzantısı destek sınıfını Extension çözümleyemedi.

Parametresiz oluşturucu

Tüm işaretleme uzantısı destek türleri için genel parametresiz oluşturucuyu kullanıma sunmanız gerekir. Bir XAML nesne yazıcısının bir nesne öğesi kullanımından işaretleme uzantısını örneklediği her durumda parametresiz oluşturucu gereklidir. Nesne öğesi kullanımını desteklemek, özellikle serileştirme için bir işaretleme uzantısı için adil bir beklentidir. Ancak, yalnızca işaretleme uzantısının öznitelik kullanımlarını desteklemek istiyorsanız, ortak oluşturucu olmadan bir işaretleme uzantısı uygulayabilirsiniz.

İşaretlemeyi genişletme kullanımınızda bağımsız değişken yoksa, kullanımı desteklemek için parametresiz oluşturucu gereklidir.

Özel İşaretlemesi Uzantısı için Oluşturucu Desenleri ve Konumsal Bağımsız Değişkenler

Hedeflenen bağımsız değişken kullanımına sahip bir işaretleme uzantısı için, ortak oluşturucuların hedeflenen kullanımın modlarına karşılık gelen olması gerekir. Başka bir deyişle, işaretleme uzantınız geçerli bir kullanım olarak tek bir konumsal bağımsız değişken gerektirecek şekilde tasarlanmışsa, konumsal bağımsız değişkeni alan bir giriş parametresine sahip bir ortak oluşturucuyu desteklemeniz gerekir.

Örneğin, işaretleme uzantısının Collate yalnızca numaralandırma sabiti olarak belirtilen modunu temsil eden tek bir konumsal bağımsız değişkenin bulunduğu bir CollationMode modu desteklemeye yönelik olduğunu varsayalım. Bu durumda, aşağıdaki forma sahip bir oluşturucu olmalıdır:

public Collate(CollationMode collationMode) {...}

Temel düzeyde, işaretleme uzantısına geçirilen bağımsız değişkenler, işaretlemenin öznitelik değerlerinden iletildiği için bir dizedir. Tüm bağımsız değişken dizelerinizi oluşturabilir ve bu düzeydeki girişlerle çalışabilirsiniz. Ancak, işaretleme uzantısı bağımsız değişkenleri destek sınıfına geçirilmeden önce gerçekleşen belirli işlemelere erişiminiz vardır.

İşleme kavramsal olarak, işaretleme uzantısı oluşturulacak bir nesne gibi çalışır ve ardından üye değerleri ayarlanır. Ayarlanacak belirtilen her özellik, XAML ayrıştırıldığında belirtilen bir üyenin oluşturulan nesnede nasıl ayarlanabileceğine benzer şekilde değerlendirilir. İki önemli fark vardır:

Daha önce belirtildiği gibi, bir işaretleme uzantısı destek türünün XAML'de örneği oluşturulabilmesi için parametresiz bir oluşturucuya sahip olması gerekmez. Nesne yapısı, metin söz dizimindeki olası bağımsız değişkenleri belirteci haline getirilene ve konumsal veya adlandırılmış bağımsız değişkenler olarak değerlendirilene kadar ertelenmiş olur ve o sırada uygun oluşturucu çağrılır.
İşaretlemeyi genişletme kullanımları iç içe yerleştirilebilir. En içteki işaretleme uzantısı önce değerlendirilir. Bu nedenle, böyle bir kullanımı varsayabilir ve oluşturma parametrelerinden birini üretmek için bir değer dönüştürücüsü (örneğin, bir işaretleme uzantısı) gerektiren bir tür olarak bildirebilirsiniz.

Önceki örnekte bu tür işlemeye bağlılık gösterilmiştir. .NET XAML Hizmetleri XAML nesne yazıcısı, numaralandırma sabit adlarını yerel düzeyde numaralandırılmış değerler halinde işler.

Biçimlendirme uzantısı konumsal parametresinin metin söz dizimini işlemek, yapı bağımsız değişkenindeki türle ilişkili bir tür dönüştürücüsü de kullanabilir.

Kullanımdaki belirteçlerin karşılaşıldığı sıra, atandıkları oluşturucu parametresinin konum sırasına karşılık geldiği için bağımsız değişkenler konumsal bağımsız değişkenler olarak adlandırılır. Örneğin, aşağıdaki oluşturucu imzasını göz önünde bulundurun:

public Collate(CollationMode collationMode, object collateThis) {...}

XAML işlemcisi bu işaretleme uzantısı için iki konumsal bağımsız değişken bekler. bir kullanım {Collate AlphaUp,{x:Reference circularFile}}varsa, AlphaUp belirteç ilk parametreye gönderilir ve sabit adlı bir CollationMode numaralandırma olarak değerlendirilir. İçin x:Reference sonucu ikinci parametreye gönderilir ve nesne olarak değerlendirilir.

İşaretlemeyi genişletme söz dizimi ve işleme için belirtilen XAML kurallarında, virgül bağımsız değişkenler arasındaki sınırlayıcıdır; bu bağımsız değişkenler konumsal bağımsız değişkenler veya adlandırılmış bağımsız değişkenlerdir.

Konumsal bağımsız değişkenlerin yinelenen arity değeri

Bir XAML nesne yazıcısı konumsal bağımsız değişkenlerle bir işaretleme uzantısı kullanımıyla karşılaşırsa ve bu sayıda bağımsız değişkeni (yinelenen arity) alan birden çok oluşturucu bağımsız değişkeni varsa, bu mutlaka bir hata değildir. Davranış, özelleştirilebilir bir XAML şeması bağlam ayarı SupportMarkupExtensionsWithDuplicateArityolan öğesine bağlıdır. ise SupportMarkupExtensionsWithDuplicateAritytrue, bir XAML nesne yazıcısı yalnızca yinelenen arity nedeniyle özel durum oluşturmamalıdır. Bu noktanın ötesindeki davranış kesin olarak tanımlanmamıştır. Temel tasarım varsayımı, şema bağlamının belirli parametreler için kullanılabilir tür bilgilerine sahip olduğu ve hangi imzanın en iyi eşleşme olabileceğini görmek için yinelenen adaylarla eşleşen açık atamaları deneyebileceğidir. Bir XAML nesne yazıcısı üzerinde çalışan belirli bir şema bağlamı tarafından uygulanan testleri hiçbir imza geçiremiyorsa bir özel durum yine de oluşturulabilir.

Varsayılan olarak, SupportMarkupExtensionsWithDuplicateArity .NET XAML Hizmetleri için CLR tabanlıdır falseXamlSchemaContext . Bu nedenle, yedekleme türünün oluşturucularında yinelenen arity olan bir işaretleme uzantısı kullanımıyla karşılaşırsa varsayılan XamlObjectWriter özel durumlar oluşturur.

Özel işaretleme uzantısı için adlandırılmış bağımsız değişkenler

XAML tarafından belirtilen işaretleme uzantıları, kullanım için adlandırılmış bağımsız değişkenler formu da kullanabilir. Belirteç oluşturmanın ilk düzeyinde, metin söz dizimi bağımsız değişkenlere ayrılır. Herhangi bir bağımsız değişken içinde eşittir işareti (=) varlığı, bağımsız değişkeni adlandırılmış bağımsız değişken olarak tanımlar. Böyle bir bağımsız değişken de bir ad/değer çifti olarak belirteçlendirilir. Bu örnekteki ad, işaretleme uzantısının destek türünün genel ayarlanabilir özelliğini adlandırmaktadır. Adlandırılmış bağımsız değişken kullanımını desteklemeyi planlıyorsanız, bu genel ayarlanabilir özellikleri sağlamanız gerekir. Özellikler, genel olarak kaldıkları sürece devralınabilir.

İşaretlemeyi Uzantı Uygulamasından Hizmet Sağlayıcısı Bağlamı'nı Erişme

Kullanılabilir hizmetler tüm değer dönüştürücüleri için aynıdır. Fark, her değer dönüştürücüsunun hizmet bağlamını nasıl aldığıdır. Hizmetlere ve kullanılabilir hizmetlere erişim, XAML için Tür Dönüştürücüleri ve İşaretlemeyi Genişletmeler konusunda belgelenmiştir.

biçimlendirme uzantısının özellik öğesi kullanımı

İşaretlemeyi genişletme kullanımı senaryoları genellikle öznitelik kullanımındaki işaretleme uzantısı kullanılarak tasarlanır. Ancak, özellik öğesi kullanımını desteklemek için yedekleme sınıfını tanımlamak da mümkündür.

İşaretlemeyi uzantınızın özellik öğesi kullanımını desteklemek için genel bir parametresiz oluşturucu tanımlayın. Bu, statik bir oluşturucu değil örnek oluşturucu olmalıdır. Bu gereklidir çünkü bir XAML işlemcisi genellikle işaretlemeden işlediği herhangi bir nesne öğesinde parametresiz oluşturucuyu çağırmalıdır ve bu, işaretleme uzantısı sınıflarını nesne öğeleri olarak içerir. Gelişmiş senaryolar için sınıflar için varsayılan olmayan yapı yolları tanımlayabilirsiniz. (Daha fazla bilgi için bkz . x:FactoryMethod Yönergesi.) Ancak, hem tasarımcılar hem de ham işaretleme kullanıcıları için kullanım desenini bulmayı çok daha zor hale getirdiğinden, bu desenleri işaretleme uzantısı amacıyla kullanmamalısınız.

Özel işaretleme uzantısı için dağıtma

Hem tasarım ortamlarını hem de belirli XAML nesne yazıcı senaryolarını desteklemek için, bir işaretleme uzantısı destek türünü birkaç CLR özniteliğiyle ilişkilendirmelisiniz. Bu öznitelikler hedeflenen işaretleme uzantısı kullanımını bildirir.

MarkupExtensionReturnTypeAttribute , döndüren Type nesne türüne ilişkin ProvideValue bilgileri raporlar. Saf imzası ile döndürür ProvideValue Object. Ancak çeşitli tüketiciler daha kesin dönüş türü bilgileri isteyebilir. Buna aşağıdakiler dahildir:

Tasarım Aracı ve IDE'ler, işaretleme uzantısı kullanımları için tür algılayan destek sağlayabilir.
Hedef sınıflardaki işleyicilerin SetMarkupExtension gelişmiş uygulamaları, belirli bilinen MarkupExtension uygulamalara ada göre dallanma yerine bir işaretleme uzantısının dönüş türünü belirlemek için yansımaya dayanabilir.

İşaretleme uzantısı kullanımlarının seri hale getirilmesi

Bir XAML nesne yazıcısı bir işaretleme uzantısı kullanımını işlediğinde ve çağırdığında ProvideValue, daha önce bir işaretleme uzantısı kullanımına ilişkin bağlam XAML düğüm akışında kalır, ancak nesne grafiğinde devam eder. Nesne grafiğinde yalnızca değer korunur. Özgün işaretleme uzantısı kullanımını serileştirilmiş çıktıda kalıcı hale getirmeniz için tasarım senaryolarınız veya başka nedenleriniz varsa, XAML düğüm akışından işaretleme uzantısı kullanımlarını izlemek için kendi altyapınızı tasarlamanız gerekir. Düğüm akışının öğelerini yük yolundan yeniden oluşturmak ve düğüm akışının uygun konumundaki değeri değiştirerek kaydetme yolunda seri hale getirmek üzere XAML yazıcılarına geri oynatmak için davranış uygulayabilirsiniz.

XAML düğüm akışındaki işaretleme uzantıları

Yük yolunda bir XAML düğüm akışıyla çalışıyorsanız, düğüm akışında nesne olarak bir işaretleme uzantısı kullanımı görünür.

İşaretleme uzantısı kullanımı konumsal bağımsız değişkenler kullanıyorsa, başlatma değeri olan bir başlangıç nesnesi olarak temsil edilir. Kaba metin gösterimi olarak düğüm akışı aşağıdakine benzer:

StartObject (XamlType biçimlendirme uzantısının tanım türüdür, dönüş türü değildir)

StartMember(adı XamlMember )_InitializationText

Value (değer, araya giren sınırlayıcılar da dahil olmak üzere bir dize olarak konumsal bağımsız değişkenlerdir)

EndMember

EndObject

Adlandırılmış bağımsız değişkenler içeren bir işaretleme uzantısı kullanımı, her biri metin dizesi değerleriyle ayarlanmış, ilgili adların üyelerine sahip bir nesne olarak temsil edilir.

Aslında bir işaretleme uzantısının ProvideValue uygulanmasını çağırmak için XAML şema bağlamı gerekir, çünkü bu tür eşlemesi gerektirir ve bir işaretleme uzantısı destek türü örneği oluşturur. Bu, işaretleme uzantısı kullanımlarının varsayılan .NET XAML Hizmetleri düğüm akışlarında bu şekilde korunmasının bir nedenidir. Bir yük yolunun okuyucu bölümünde genellikle gerekli XAML şema bağlamı yoktur.

Kaydetme yolunda bir XAML düğüm akışıyla çalışıyorsanız, genellikle bir nesne grafiği gösteriminde serileştirebileceğiniz nesnenin başlangıçta bir işaretleme uzantısı kullanımı ve bir sonuç tarafından sağlandığını bildiren hiçbir ProvideValue şey yoktur. Nesne grafiğindeki diğer değişiklikleri yakalarken yuvarlama için işaretleme uzantısı kullanımlarını kalıcı hale getirmek için gereken senaryolar, özgün XAML girişinden bir işaretleme uzantısı kullanımı bilgisini korumak için kendi tekniklerini tasarlamalıdır. Örneğin, işaretleme uzantısı kullanımlarını geri yüklemek için, işaretleme uzantısı kullanımlarını geri yüklemek veya özgün XAML ile yuvarlatılmış XAML arasında bir tür birleştirme gerçekleştirmek için kaydetme yolunda düğüm akışıyla çalışmanız gerekebilir. WPF gibi bazı XAML uygulayan çerçeveler, işaretleme uzantısı kullanımlarının değerleri sağladığı durumları temsil etmeye yardımcı olmak için ara türler (ifadeler) kullanır.