Definování vlastních typů pro použití se službami .NET XAML Services

Článek
10/18/2023

Při definování vlastních typů, které jsou obchodní objekty nebo typy, které nemají závislost na konkrétních architekturách, existují určité osvědčené postupy pro XAML, které můžete postupovat. Pokud budete postupovat podle těchto postupů, můžou služby .NET XAML a její čtenáře XAML a zapisovače XAML zjistit vlastnosti XAML vašeho typu a poskytnout mu odpovídající reprezentaci ve streamu uzlu XAML pomocí systému typů XAML. Toto téma popisuje osvědčené postupy pro definice typů, definice členů a přiřazení typů nebo členů clR.

Vzory konstruktoru a definice typů pro XAML

Aby bylo možné vytvořit instanci objektu v XAML, musí vlastní třída splňovat následující požadavky:

Vlastní třída musí být veřejná a musí zveřejnit veřejný konstruktor bez parametrů. (Poznámky týkající se struktur najdete v následující části.)
Vlastní třída nesmí být vnořenou třídou. Nadbytečná tečka v cestě s úplným názvem způsobí, že dělení oboru názvů třídy je nejednoznačné a koliduje s dalšími funkcemi XAML, jako jsou připojené vlastnosti. Pokud lze vytvořit instanci objektu jako prvek objektu, vytvořený objekt může vyplnit formulář prvku vlastnosti všech vlastností, které přebírají objekt jako jejich základní typ.

Pokud povolíte převaděč hodnot hodnot, můžete stále zadat hodnoty objektů pro typy, které nesplňují tato kritéria. Další informace naleznete v tématu Převaděče typů a rozšíření značek pro XAML.

Struktury

Struktury se vždy dají vytvořit v XAML pomocí definice CLR. Důvodem je to, že kompilátor CLR implicitně vytvoří konstruktor bez parametrů pro strukturu. Tento konstruktor inicializuje všechny hodnoty vlastností na výchozí hodnoty.

V některýchpřípadechch Důvodem může být to, že struktura je určená k vyplnění hodnot a funkce koncepčně jako sjednocení. Jako sjednocení mohou obsažené hodnoty mít vzájemně vylučující interpretace, a proto žádná z jejích vlastností není nastavena. Příkladem takové struktury ve slovníku WPF je GridLength. Tyto struktury by měly implementovat převaděč typů tak, aby hodnoty lze vyjádřit ve formě atributu pomocí řetězcových konvencí, které vytvářejí různé interpretace nebo režimy hodnot struktury. Struktura by také měla vystavit podobné chování pro vytváření kódu prostřednictvím konstruktoru bez parametrů.

Rozhraní

Rozhraní lze použít jako základní typy členů. Systém typů XAML zkontroluje přiřaditelný seznam a očekává, že objekt, který je zadaný jako hodnota, lze přiřadit rozhraní. Neexistuje žádný koncept toho, jak musí být rozhraní prezentováno jako typ XAML, pokud relevantní přiřaditelný typ podporuje požadavky na výstavbu XAML.

Metody továrny

Metody továrny jsou funkce XAML 2009. Upravují princip XAML, který objekty musí mít konstruktory bez parametrů. Metody továrny nejsou zdokumentované v tomto článku. Viz direktiva x:FactoryMethod.

Výčty

Výčty mají chování převodu nativního typu XAML. Názvy konstant výčtu zadané v jazyce XAML se přeloží na základní typ výčtu a vrátí hodnotu výčtu do zapisovače objektu XAML.

XAML podporuje použití ve stylu příznaků pro výčty s použitým kódem FlagsAttribute . Další informace naleznete v tématu Syntaxe XAML Podrobně. (Syntaxe XAML Podrobně je napsána pro cílovou skupinu WPF, ale většina informací v tomto tématu je relevantní pro XAML, která není specifická pro konkrétní prováděcí architekturu.)

Definice členů

Typy mohou definovat členy pro použití XAML. Typy můžou definovat členy, které jsou použitelné XAML, i když daný typ není použitelný pro XAML. To je možné kvůli dědičnosti CLR. Pokud některý typ, který dědí člena, podporuje použití XAML jako typ a člen podporuje použití XAML pro jeho základní typ nebo má k dispozici nativní syntaxi XAML, je tento člen použitelný XAML.

Vlastnosti

Pokud definujete vlastnosti jako veřejnou vlastnost CLR pomocí typických vzorů CLR get a set přistupujících vzorů a klíčových slov odpovídajících jazykem, může systém typů XAML ohlásit vlastnost jako člen s odpovídajícími informacemi zadanými pro XamlMember vlastnosti, například IsReadPublic a IsWritePublic.

Konkrétní vlastnosti mohou povolit syntaxi textu použitím TypeConverterAttribute. Další informace naleznete v tématu Převaděče typů a rozšíření značek pro XAML.

V případě absence textové syntaxe nebo nativního převodu XAML a v nepřítomnosti dalšího nepřímých výrazů, jako je použití rozšíření značek, musí být typ vlastnosti (TargetType v systému typů XAML) schopen vrátit instanci do zapisovače objektu XAML tím, že s cílovým typem zachází jako s typem CLR.

Pokud používáte XAML 2009, x:Reference Markup Extension lze použít k zadání hodnot v případě, že předchozí aspekty nejsou splněny. To je ale spíše problém s použitím než problém s definicí typu.

Události

Pokud definujete události jako veřejnou událost CLR, systém typů XAML může událost hlásit jako člena IsEvent jako true. Zapojení obslužných rutin událostí není v rámci možností .NET XAML Services; zapojení je ponecháno na konkrétních architekturách a implementacích.

Metody

Vložený kód pro metody není výchozí funkcí XAML. Ve většině případů neodkazujete přímo na členy metody z XAML a role metod v XAML je pouze poskytovat podporu pro konkrétní vzory XAML. x:FactoryMethod – direktiva je výjimkou.

Pole

Pokyny pro návrh CLR neodporují nestatickým polím. U statických polí můžete k hodnotám statických polí přistupovat pouze prostřednictvím rozšíření x:Static Markup Extension. V tomto případě v definici CLR neděláte nic zvláštního, abyste zpřístupnili pole pro x:Statická použití.

Připojitelné členy

Připojitelné členy jsou vystaveny XAML prostřednictvím vzoru metody přistupujícího objektu pro definování typu. Samotný definující typ nemusí být použitelný jako objekt XAML. Ve skutečnosti je běžným vzorem deklarovat třídu služby, jejíž role je vlastníkem připojitelného člena a implementovat související chování, ale obsluhovat žádnou jinou funkci, jako je reprezentace uživatelského rozhraní. V následujících částech představuje zástupný název PropertyName název vašeho připojitelného člena. Tento název musí být platný v jazyce XamlName Grammar.

Buďte opatrní při kolizi názvů mezi těmito vzory a jinými metodami typu. Pokud člen existuje, který odpovídá jednomu ze vzorů, lze jej interpretovat jako cestu použití připojitelného člena procesorem XAML, i když to nebylo vaším záměrem.

The GetPropertyName Accessor

Podpis přístupového objektu GetPropertyName musí být:

public static object GetPropertyName(object target)

Objekt target lze v implementaci zadat jako konkrétnější typ. Můžete ho použít k určení rozsahu využití připojitelného člena; použití mimo zamýšlený obor vyvolá neplatné výjimky přetypování, které se pak zobrazí chybou analýzy XAML. Název target parametru není požadavek, ale je pojmenovaný target konvencí ve většině implementací.
Návratovou hodnotu je možné zadat jako konkrétnější typ v implementaci.

Pokud chcete podporovat povolenou TypeConverter syntaxi textu pro použití atributu připojitelného člena, použijte TypeConverterAttribute u přístupového objektu GetPropertyName . Použití na get místo set může vypadat jako neintuitivnější. Tato konvence však může podporovat koncept připojitelných členů jen pro čtení, které jsou serializovatelné, což je užitečné ve scénářích návrháře.

Objekt SetPropertyName

Podpis přístupového objektu SetPropertyName musí být:

public static void SetPropertyName(object target, object value)

Objekt target lze zadat jako konkrétnější typ v implementaci se stejnou logikou a důsledky, jak je popsáno v předchozí části.
Objekt value lze v implementaci zadat jako konkrétnější typ.

Mějte na paměti, že hodnota pro tuto metodu je vstup pocházející z použití XAML, obvykle ve formě atributu. Ve formuláři atributu musí být podpora převaděče hodnot pro textovou syntaxi a atribut na přístupovém objektu GetPropertyName.

Připojitelné úložiště členů

Metody přistupování obvykle nestačí k tomu, aby poskytovaly prostředky k umístění připojitelných hodnot členů do objektového grafu nebo k načtení hodnot z objektového grafu a jejich správné serializaci. Aby bylo možné tuto funkci poskytnout, target musí být objekty v předchozích podpisech přístupových objektů schopné ukládat hodnoty. Mechanismus úložiště by měl být konzistentní s principem připojitelného člena, který je možné připojit k cílům, kde připojitelný člen není v seznamu členů. Služby .NET XAML services poskytují metodu implementace pro připojitelné členské úložiště prostřednictvím rozhraní API IAttachedPropertyStore a AttachablePropertyServices. IAttachedPropertyStore moduly zapisovače XAML používají ke zjištění implementace úložiště a měly by být implementovány u typu, který je target součástí přístupových objektů. Statická AttachablePropertyServices rozhraní API se používají v těle přístupových objektů a odkazují na připojitelný člen jeho AttachableMemberIdentifier.

Správné přiřazení typů, členů a sestavení je důležité, aby bylo možné hlásit systémové informace o typu XAML službě .NET XAML Services. Pokud platí některý z následujících situací, jsou informace o systému typů XAML pro generování sestav relevantní:

Máte v úmyslu používat typy s systémy XAML, které jsou přímo založené na čtečkách XAML služeb .NET XAML a zapisovačích XAML.
Definujete nebo používáte architekturu využívající XAML, která je založená na těchto čtenářích XAML a zapisovačích XAML.

Seznam jednotlivých atributů souvisejících s XAML, které jsou relevantní pro podporu XAML vašich vlastních typů, najdete v tématu Atributy CLR související s XAML pro vlastní typy a knihovny.

Využití

Použití vlastních typů vyžaduje, aby autor revizí namapovat předponu pro sestavení a obor názvů CLR, který obsahuje vlastní typ. Tento postup není v tomto tématu zdokumentovaný.

Úroveň přístupu

XAML poskytuje prostředky pro načítání a vytváření instancí typů, které mají internal úroveň přístupu. Tato funkce je poskytována tak, aby uživatelský kód mohl definovat vlastní typy a pak vytvořit instanci těchto tříd z revizí, které jsou také součástí stejného oboru uživatelského kódu.

Příkladem z WPF je vždy, když uživatelský kód definuje UserControl , který je určený jako způsob refaktorování chování uživatelského rozhraní, ale ne jako součást jakéhokoli možného mechanismu rozšíření, který by mohl být odvozen deklarací podpůrné třídy s public úrovní přístupu. Takový kód UserControl lze deklarovat s internal přístupem, pokud je backingový kód zkompilován do stejného sestavení, ze kterého se odkazuje jako na typ XAML.

Pro aplikaci, která načte XAML pod úplným vztahem důvěryhodnosti a používá XamlObjectWriter, je načítání tříd s internal úrovní přístupu vždy povoleno.

U aplikace, která načítá XAML v částečném vztahu důvěryhodnosti, můžete řídit charakteristiky úrovně přístupu pomocí XamlAccessLevel rozhraní API. Také odložené mechanismy (například systém šablon WPF) musí být schopné rozšířit všechna oprávnění na úrovni přístupu a zachovat je pro případná vyhodnocení doby běhu; zpracovává se interně předáním XamlAccessLevel informací.

Implementace WPF

WPF XAML používá model přístupu s částečnou důvěryhodností, kde pokud je BAML načten pod částečným vztahem důvěryhodnosti, je přístup omezen na AssemblyAccessTo sestavení, které je zdrojem BAML. Pro odložení používá IXamlObjectWriterFactory.GetParentSettings WPF jako mechanismus pro předávání informací na úrovni přístupu.

V terminologii WPF XAML je interní typ, který je definován stejným sestavením, které obsahuje také odkazování XAML. Takový typ lze mapovat prostřednictvím oboru názvů XAML, který záměrně vynechá sestavení = část mapování, xmlns:local="clr-namespace:WPFApplication1"například . Pokud BAML odkazuje na interní typ a tento typ má internal úroveň přístupu, vygeneruje GeneratedInternalTypeHelper třídu pro sestavení. Pokud se chcete vyhnout GeneratedInternalTypeHelper, musíte buď použít public úroveň přístupu, nebo musíte faktorovat příslušnou třídu do samostatného sestavení a učinit toto sestavení závislé.