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 zajistit, aby stávající klienti fungovali 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 verze po 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á vyšší číslo verze. Očekává se, že komponenty vázané na starou verzi sestavení budou pokračovat ve vazbě na starou verzi a další komponenty se mohou připojit k nové verzi. Je také možné aktualizovat komponentu, která je deklarována jako SideBySide, destruktivní úpravou staré verze.

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í vysokou úroveň binární kompatibility. 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ávání nebo odebírání privátních instančních polí z typu, pokud tím nedojde k naruš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 ustálené typy se nepoužívají jako dobře známé typy výměny, na kterých se všechny komponenty shodují. 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 měnit pouze tehdy, je-li problém velmi závažný (například závažný problém se zabezpečením) nebo je-li pravděpodobnost přerušení velmi nízká (tj. pokud bylo chování již dříve náhodně porušeno způsobem, na kterém kód pravděpodobně nemohl být závislý). U typu výměny můžete provést následující druhy změn:

• Přidejte dědičnost 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é nevirtuální instanční metody.

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 verzím odolná serializace.

• Přidání nebo odebrání privátních instančních polí Existuje riziko, že se změní formát serializace typu, což může narušit 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 Spotřebitelé daného 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	Výměna	Stabilní	Vedle sebe	Žádné
Lze použít v rozhraních mezi komponentami, které mají nezávislé verze.	Й	N	N	N
Lze použít (soukromě) sestavením, které nezávisle verze.	Й	Й	Й	N
Může mít více verzí v jedné doméně aplikace.	N	Й	Й	Й
Může provádět zásadní změny	N	N	Й	Й
Otestováno, aby bylo možné načíst několik verzí sestavení dohromady.	N	N	Й	N
Může provádět zásadní změny na místě.	N	N	N	Й
Může přímo provádět velmi bezpečné bezvýpadkové servisní změny.	Й	Й	Й	Й

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 na jednotlivé typy a jejich členy. 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($"{typ.Name} is marked as {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($"{typ.Name} is marked as Stable or Exchange.");

' 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í příklad testuje, zda je typ označen jako None (tj. ani Stable ani Exchange).

// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
   Console.WriteLine($"{typ.Name} has no compatibility 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