System.Runtime.Versioning.ComponentGuaranteesAttribute – třída
Tento článek obsahuje doplňující poznámky k referenční dokumentaci pro toto rozhraní API.
Vývojáři ComponentGuaranteesAttribute komponent a knihoven tříd ji používají k označení úrovně kompatibility, kterou uživatelé knihoven mohou očekávat v různých verzích. Určuje úroveň záruky, že budoucí verze knihovny nebo komponenty neporuší existujícího klienta. Klienti pak můžou jako pomoc při navrhování vlastních rozhraní použít ComponentGuaranteesAttribute k zajištění stability napříč verzemi.
Poznámka:
Modul CLR (Common Language Runtime) tento atribut nepoužívá žádným způsobem. Jeho hodnota spočívá v formální dokumentaci záměru autora komponenty. Nástroje pro kompilaci mohou tyto deklarace použít také k detekci chyb v době kompilace, které by jinak přerušily deklarovanou záruku.
Úrovně kompatibility
Podporuje ComponentGuaranteesAttribute následující úrovně kompatibility, které jsou reprezentovány členy výčtu ComponentGuaranteesOptions :
Žádná kompatibilita verzí na verzi (ComponentGuaranteesOptions.None). Klient může očekávat, že budoucí verze přeruší existujícího klienta. Další informace najdete v části Bez kompatibility dále v tomto článku.
Souběžná kompatibilita verzí na verzi (ComponentGuaranteesOptions.SideBySide). Komponenta byla testována tak, aby fungovala, když je načtena více než jedna verze sestavení ve stejné doméně aplikace. Obecně platí, že budoucí verze můžou narušit kompatibilitu. Pokud však dojde k zásadním změnám, stará verze se nezmění, ale existuje společně s novou verzí. Souběžné spouštění je očekávaný způsob, jak stávající klienty pracovat při provádění zásadních změn. Další informace najdete v části Souběžná kompatibilita dále v tomto článku.
Stabilní kompatibilita verzí na verzi (ComponentGuaranteesOptions.Stable). Budoucí verze by neměly přerušit klienta a souběžné spouštění by nemělo být potřeba. Pokud je však klient neúmyslně poškozený, může být možné problém vyřešit pomocí souběžného spuštění. Další informace najdete v části Stabilní kompatibilita .
Kompatibilita mezi verzemi Exchange (ComponentGuaranteesOptions.Exchange). Je třeba věnovat mimořádnou péči, aby se zajistilo, že budoucí verze klienta neporuší. Klient by měl používat pouze tyto typy v podpisu rozhraní, která se používají pro komunikaci s jinými sestaveními, která jsou nasazena nezávisle na sobě. Očekává se, že v dané doméně aplikace bude pouze jedna verze těchto typů, což znamená, že pokud se klient přeruší, souběžné spuštění nemůže problém s kompatibilitou vyřešit. Další informace najdete v části Kompatibilita typu Exchange.
V následujících částech najdete podrobnější informace o jednotlivých úrovních záruky.
Žádná kompatibilita
Označení komponenty jako ComponentGuaranteesOptions.None indikuje, že poskytovatel neposkytuje žádné záruky kompatibility. Klienti by se měli vyhnout závislosti na vystavených rozhraních. Tato úroveň kompatibility je užitečná pro typy, které jsou experimentální nebo veřejně zveřejněné, ale jsou určeny pouze pro komponenty, které jsou vždy aktualizovány najednou. None explicitně označuje, že tato komponenta by neměla být používána externími komponentami.
Souběžná kompatibilita
Označení komponenty jako ComponentGuaranteesOptions.SideBySide značí, že komponenta byla testována tak, aby fungovala, když je načtena více než jedna verze sestavení do stejné domény aplikace. Zásadní změny jsou povoleny, pokud jsou provedeny v sestavení, které má větší číslo verze. Očekává se, že komponenty vázané na starou verzi sestavení budou pokračovat v vazbě na starou verzi a další komponenty mohou svázat s novou verzí. Je také možné aktualizovat komponentu, která je deklarována tak, že SideBySide destruktivně upraví starou verzi.
Stabilní kompatibilita
Označení typu jako ComponentGuaranteesOptions.Stable indikuje, že typ by měl zůstat stabilní v různých verzích. Může však být také možné, že ve stejné doméně aplikace existují souběžné verze stabilního typu.
Stabilní typy udržují panel s vysokou kompatibilitou binárních souborů. Z tohoto důvodu by se poskytovatelé měli vyhnout zásadním změnám stabilních typů. Jsou přijatelné následující druhy změn:
- Přidání polí privátní instance do nebo odebrání polí z typu, pokud tím nedojde k přerušení formátu serializace.
- Změna ne serializovatelného typu na serializovatelný typ. (Serializovatelný typ však nelze změnit na typ, který nelze serializovat.)
- Vyvolání nových, odvozených výjimek z metody.
- Zlepšení výkonu metody.
- Změna rozsahu vrácených hodnot, pokud změna nemá nepříznivý vliv na většinu klientů.
- Oprava závažných chyb, pokud je obchodní odůvodnění vysoké a počet nepříznivě ovlivněných klientů je nízký.
Vzhledem k tomu, že se neočekává, že by nové verze stabilních komponent neměly narušit stávající klienty, v doméně aplikace se obvykle vyžaduje pouze jedna verze stabilní komponenty. To však není požadavek, protože stabilní typy se nepoužívají jako známé typy výměny, které všechny komponenty souhlasí. Proto pokud nová verze stabilní komponenty neúmyslně přeruší některé komponenty a pokud jiné komponenty potřebují novou verzi, může být možné problém vyřešit načtením staré i nové komponenty.
Stable poskytuje silnější záruku kompatibility verzí než None. Je to běžné výchozí nastavení pro komponenty s více verzemi.
Stable lze kombinovat s SideBySidetím, který uvádí, že komponenta nebude narušit kompatibilitu, ale testuje se, aby fungovala, když je v dané doméně aplikace načteno více než jedna verze.
Jakmile je typ nebo metoda označena jako Stable, lze jej upgradovat na Exchange. Nelze však downgradovat na None.
Kompatibilita typu Exchange
Označení typu jako ComponentGuaranteesOptions.Exchange zajištění silnější záruky kompatibility verzí než Stablea mělo by být použito na nejstabilnější ze všech typů. Tyto typy jsou určeny k výměně mezi nezávisle sestavené komponenty napříč všemi hranicemi komponent v obou časech (libovolná verze CLR nebo jakékoli verze komponenty nebo aplikace) a prostor (křížový proces, cross-CLR v jednom procesu, doména napříč aplikacemi v jednom CLR). Pokud dojde k zásadní změně typu výměny, není možné problém vyřešit načtením více verzí tohoto typu.
Typy výměny by se měly změnit pouze v případě, že je problém velmi závažný (například závažný problém se zabezpečením) nebo je pravděpodobnost přerušení velmi nízká (to znamená, že pokud chování bylo již přerušeno náhodným způsobem, že kód nemohl mít pravděpodobně závislost na). U typu výměny můžete provést následující druhy změn:
Přidání dědičnosti nových definic rozhraní
Přidejte nové privátní metody, které implementují metody nově zděděných definic rozhraní.
Přidejte nová statická pole.
Přidejte nové statické metody.
Přidejte nové metody ne virtuální instance.
Následující změny jsou považovány za zásadní změny a nejsou povoleny pro primitivní typy:
Změna formátů serializace Vyžaduje se serializace odolné proti verzím.
Přidání nebo odebrání polí privátní instance To znamená, že se změní formát serializace typu a způsobující kód klienta, který používá reflexi.
Změna serializovatelnosti typu Typ, který nelze serializovat, nemusí být serializovatelný a naopak.
Vyvolání různých výjimek z metody
Změna rozsahu návratových hodnot metody, pokud definice člena nezvýší tuto možnost a jasně indikuje, jak mají klienti zpracovávat neznámé hodnoty.
Oprava většiny chyb Příjemci typu budou spoléhat na stávající chování.
Jakmile je součást, typ nebo člen označena zárukou Exchange , nelze ji změnit na ani StableNone.
Typy výměny jsou obvykle základní typy (například Int32 a String v rozhraních .NET) a rozhraní (například IList<T>, IEnumerable<T>a IComparable<T>) běžně používané ve veřejných rozhraních.
Typy Exchange mohou veřejně vystavit pouze jiné typy, které jsou také označeny kompatibilitou Exchange . Kromě toho typy výměny nemohou záviset na chování rozhraní API systému Windows, která jsou náchylná ke změně.
Záruky komponent
Následující tabulka uvádí, jak vlastnosti a využití komponenty ovlivňují záruku kompatibility.
| Vlastnosti komponent | Exchange | Stable | Vedle sebe | Nic |
|---|---|---|---|---|
| Lze použít v rozhraních mezi komponentami, které jsou verze nezávislé. | Y | N | N | N |
| Lze použít (soukromě) sestavením, které nezávisle verze. | Y | Y | Y | N |
| Může mít více verzí v jedné doméně aplikace. | N | Y | Y | Y |
| Může provádět zásadní změny | N | N | Y | Y |
| Otestováno, aby bylo možné načíst několik verzí sestavení dohromady. | N | N | Y | N |
| Může provádět zásadní změny na místě. | N | N | N | Y |
| Může provádět velmi bezpečné nerušované servisní změny. | Y | Y | Y | Y |
Použití atributu
Můžete použít ComponentGuaranteesAttribute u sestavení, typu nebo člena typu. Její aplikace je hierarchická. To znamená, že ve výchozím nastavení záruka definovaná Guarantees vlastností atributu na úrovni sestavení definuje záruku všech typů v sestavení a všechny členy v těchto typech. Podobně platí, že pokud je záruka použita pro typ, ve výchozím nastavení se vztahuje také na každý člen typu.
Tuto zděděnou záruku lze přepsat použitím ComponentGuaranteesAttribute jednotlivých typů a členů typů. Zaručuje však, že přepsání výchozího nastavení může pouze oslabit záruku; nemohou ji posílit. Pokud je například sestavení označeno zárukou None , jeho typy a členy nemají žádnou záruku kompatibility a všechny další záruky použité u typů nebo členů v sestavení se ignorují.
Otestování záruky
Vlastnost Guarantees vrátí člen výčtu ComponentGuaranteesOptions , který je označen atributem FlagsAttribute . To znamená, že byste měli otestovat příznak, který vás zajímá, maskováním potenciálně neznámých příznaků. Například následující příklad testuje, zda je typ označen jako Stable.
// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee);
' Test whether guarantee is Stable.
If (guarantee And ComponentGuaranteesOptions.Stable) = ComponentGuaranteesOptions.Stable Then
Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee)
End If
Následující příklad testuje, zda je typ označen jako Stable nebo Exchange.
// Test whether guarantee is Stable or Exchange.
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) > 0)
Console.WriteLine("{0} is marked as Stable or Exchange.", typ.Name, guarantee);
' Test whether guarantee is Stable or Exchange.
If (guarantee And (ComponentGuaranteesOptions.Stable Or ComponentGuaranteesOptions.Exchange)) > 0 Then
Console.WriteLine("{0} is marked as Stable or Exchange.", typ.Name, guarantee)
End If
Následující ukázkové testy při použití typu jsou označeny jako None (to znamená, že ani ExchangeStable ).
// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
Console.WriteLine("{0} has no compatibility guarantee.", typ.Name, guarantee);
' Test whether there is no guarantee (neither Stable nor Exchange).
If (guarantee And (ComponentGuaranteesOptions.Stable Or ComponentGuaranteesOptions.Exchange)) = 0 Then
Console.WriteLine("{0} has no compatibility guarantee.", typ.Name, guarantee)
End If
