ComponentGuaranteesAttribute Osztály

Definíció

Névtér:

System.Runtime.Versioning

Szerelvények:

netstandard.dll, System.Runtime.dll

Forrás:

ComponentGuaranteesAttribute.cs

Meghatározza egy olyan összetevő, típus vagy típustag kompatibilitási garanciát, amely több verzióra is kiterjedhet.

public ref class ComponentGuaranteesAttribute sealed : Attribute

[System.AttributeUsage(System.AttributeTargets.Assembly | System.AttributeTargets.Class | System.AttributeTargets.Constructor | System.AttributeTargets.Delegate | System.AttributeTargets.Enum | System.AttributeTargets.Event | System.AttributeTargets.Interface | System.AttributeTargets.Method | System.AttributeTargets.Module | System.AttributeTargets.Property | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)]
public sealed class ComponentGuaranteesAttribute : Attribute

[<System.AttributeUsage(System.AttributeTargets.Assembly | System.AttributeTargets.Class | System.AttributeTargets.Constructor | System.AttributeTargets.Delegate | System.AttributeTargets.Enum | System.AttributeTargets.Event | System.AttributeTargets.Interface | System.AttributeTargets.Method | System.AttributeTargets.Module | System.AttributeTargets.Property | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)>]
type ComponentGuaranteesAttribute = class
    inherit Attribute

Public NotInheritable Class ComponentGuaranteesAttribute
Inherits Attribute

Öröklődés

Object

Attribute

ComponentGuaranteesAttribute

Attribútumok

AttributeUsageAttribute

Megjegyzések

Az ComponentGuaranteesAttribute összetevők és osztálykódtárak fejlesztői azt a kompatibilitási szintet jelzik, amelyet a kódtárak felhasználói több verzióban is elvárhatnak. Azt jelzi, hogy mekkora a garancia arra, hogy a kódtár vagy komponens jövőbeli verziója nem fogja megsérteni a meglévő alkalmazásokat. Az ügyfelek ezután segítségként használhatják a ComponentGuaranteesAttribute saját interfészek tervezéséhez, hogy a verziók stabilitását biztosítsák.

Megjegyzés:

A közös nyelvi futtatókörnyezet (CLR) semmilyen módon nem használja ezt az attribútumot. Ennek értéke az összetevő szerzőjének szándékának formális dokumentálása. A fordítási idő eszközei ezeket a deklarációkat is használhatják olyan fordítási idő hibáinak észlelésére, amelyek egyébként megszegnék a deklarált garanciát.

Kompatibilitási szintek

A ComponentGuaranteesAttribute következő kompatibilitási szinteket támogatja, amelyeket az ComponentGuaranteesOptions enumerálás tagjai képviselnek:

• Nincs verzió-verzió kompatibilitás (ComponentGuaranteesOptions.None). Az ügyfél számíthat arra, hogy a jövőbeli verziók megszakítják a meglévő klienst. További információt a cikk későbbi, Kompatibilitás nélküli szakaszában talál.

• Verzióról verzióra való egymás melletti kompatibilitás (ComponentGuaranteesOptions.SideBySide). Az összetevőt tesztelték, hogy működjön, ha a szerelvény több verziója is betöltődik ugyanabban az alkalmazástartományban. A jövőbeli verziók általában megszakíthatják a kompatibilitást. A kompatibilitástörő módosítások végrehajtásakor azonban a régi verzió nem módosul, hanem az új verzió mellett létezik. Az egymás melletti végrehajtás az elvárt módszer arra, hogy a meglévő kliensek működjenek a kompatibilitástörő módosítások végrehajtásakor. További információt a cikk későbbi, egymás melletti kompatibilitási szakaszában talál.

• Stabil verzió-verzió kompatibilitás (ComponentGuaranteesOptions.Stable). A jövőbeli verziók nem szakíthatják meg a kliens működését, és nem kell szükség párhuzamos futtatásra. Ha azonban az ügyfél véletlenül megszakad, lehetséges, hogy a probléma megoldásához párhuzamos végrehajtást is használhat. További információkért lásd a Stabil kompatibilitás című szakaszt.

• Az Exchange verzióról verzióra kompatibilitása (ComponentGuaranteesOptions.Exchange). Különös figyelmet fordítunk arra, hogy a jövőbeli verziók ne törik meg az ügyfelet. Az ügyfélnek csak ezeket a típusokat kell használnia a más, egymástól függetlenül üzembe helyezett szerelvényekkel való kommunikációhoz használt interfészek aláírásában. Ezeknek a típusoknak csak egy verziója várható egy adott alkalmazástartományban, ami azt jelenti, hogy ha egy ügyfél meghibásodik, a párhuzamos végrehajtás nem tudja megoldani a kompatibilitási problémát. További információt az Exchange-típus kompatibilitási szakaszában talál.

A következő szakaszok részletesebben ismertetik az egyes garanciális szinteket.

Nincs kompatibilitás

Az összetevők ComponentGuaranteesOptions.None megjelölése azt jelzi, hogy a szolgáltató nem garantálja a kompatibilitást. Az ügyfeleknek kerülniük kell, hogy függőséget építsenek a közzétett felületeken. Ez a kompatibilitási szint olyan típusok esetén hasznos, amelyek kísérleti jellegűek vagy nyilvánosan közzétettek, de csak olyan összetevőkre szolgálnak, amelyek mindig frissülnek egyszerre. None kifejezetten jelzi, hogy ezt az összetevőt nem használhatják külső összetevők.

Egymás melletti kompatibilitás

Az összetevő ComponentGuaranteesOptions.SideBySide megjelölése azt jelzi, hogy az összetevőt tesztelték, hogy működjön, ha a szerelvény több verziója is betöltődik ugyanabba az alkalmazástartományba. A kompatibilitástörő módosítások mindaddig engedélyezettek, amíg a nagyobb verziószámmal rendelkező összeállításon történnek. A szerelvény egy régi verziójához kötött összetevők várhatóan továbbra is a régi verzióhoz fognak kapcsolódni, más összetevők pedig az új verzióhoz köthetnek. A régi verzió romboló módosításával frissíthető egy deklarált SideBySide összetevő is.

Stabil kompatibilitás

A típus ComponentGuaranteesOptions.Stable megjelölése azt jelzi, hogy a típusnak a verziók között stabilnak kell maradnia. Előfordulhat azonban, hogy egy stabil típus egymás melletti verziói is létezhetnek ugyanabban az alkalmazástartományban.

A stabil típusok magas bináris kompatibilitási sávot tartanak fenn. Emiatt a szolgáltatóknak kerülnie kell a stabil típusokat érintő, kompatibilitást megszakító változtatásokat. A következő típusú módosítások elfogadhatók:

• Privát példány mezőinek hozzáadása egy típushoz, vagy a mezők eltávolítása egy típushoz, feltéve, hogy ez nem szakítja meg a szerializálási formátumot.
• Nem szerializálható típus módosítása szerializálható típusra. (A szerializálható típus azonban nem módosítható nem szerializálható típusra.)
• Új, több származtatott kivételt dobni egy metódusból.
• Egy metódus teljesítményének javítása.
• A visszatérési értékek tartományának módosítása mindaddig, amíg a változás nem befolyásolja hátrányosan az ügyfelek többségét.
• Súlyos hibák kijavítása, ha az üzleti indok magas, és a hátrányosan érintett ügyfelek száma alacsony.

Mivel a stabil összetevők új verziói várhatóan nem szakítják meg a meglévő ügyfeleket, általában csak egy stabil összetevő egy verziójára van szükség egy alkalmazástartományban. Ez azonban nem követelmény, mert a stabil típusokat nem használják olyan jól ismert cseretípusokként, amelyekben minden összetevő egyetért. Ezért ha egy stabil összetevő új verziója véletlenül megszakít bizonyos összetevőket, és ha más összetevőknek szüksége van az új verzióra, lehetséges, hogy a problémát a régi és az új összetevő betöltésével is meg lehet oldani.

Stable erősebb verziókompatibilitási garanciát biztosít, mint Nonea . Ez a többverziós összetevők gyakori alapértelmezett beállítása.

Stable kombinálható azzal SideBySide, amely azt állítja, hogy az összetevő nem szakítja meg a kompatibilitást, de tesztelve van, hogy működjön, ha egy adott alkalmazástartományba több verzió is betöltődik.

Egy típus vagy metódus, miután Stable meg lett jelölve, frissíthető Exchange. Azonban nem lehet None szintre visszaminősíteni.

Exchange-típus kompatibilitása

A típus ComponentGuaranteesOptions.Exchange megjelölése erősebb verziókompatibilitási garanciát nyújt, mint Stablea , és az összes típus közül a legstabilabbra kell alkalmazni. Ezeket a típusokat arra szánják, hogy az egymástól függetlenül létrehozott összetevők közötti adatcserét végezzék, mind időben (a CLR bármely verziójában vagy egy összetevő vagy alkalmazás bármely verziójában), mind térben (folyamatközi, egy folyamaton belül több CLR között, vagy alkalmazástartományok között egy CLR-ben). Ha egy exchange-típuson kompatibilitástörő módosítás történik, a hiba nem oldható meg a típus több verziójának betöltésével.

Az Exchange-típusokat csak akkor kell módosítani, ha egy probléma nagyon súlyos (például súlyos biztonsági probléma), vagy a törés valószínűsége nagyon alacsony (vagyis ha a viselkedés már véletlenszerűen megszakadt, és a kód nem tudott volna függőséget venni). Exchange-típuson a következő módosításokat végezheti el:

• Új felületdefiníciók öröklésének hozzáadása.

• Adjon hozzá új privát metódusokat, amelyek implementálják az újonnan örökölt felületdefiníciók metódusait.

• Új statikus mezők hozzáadása.

• Adjon hozzá új statikus metódusokat.

• Adjon hozzá új, nem virtuális példány metódusokat.

A következők kompatibilitástörő változásoknak minősülnek, és a primitív típusok esetében nem engedélyezettek:

• Szerializálási formátumok módosítása. Verziótűrő szerializálás szükséges.

• Privát példánymezők hozzáadása vagy eltávolítása. Ez a típus szerializálási formátumának megváltoztatását és a tükrözést használó ügyfélkód feltörését kockáztatja.

• Típus szerializálhatóságának módosítása. Nem szerializálható típus nem hozható szerializálhatóvá, és fordítva.

• Eltérő kivételek kivetése egy metódusból.

• A metódus visszatérési értékeinek tartományának módosítása, hacsak a tagdefiníció nem teszi lehetővé ezt a lehetőséget, és egyértelműen jelzi, hogy az ügyfelek hogyan kezeljenek ismeretlen értékeket.

• A legtöbb hiba kijavítása. A típus felhasználói a meglévő viselkedésre támaszkodnak.

Miután egy összetevőt, típust vagy tagot megjelölt a Exchange garanciával, nem módosítható Stable vagy None típusra.

Az exchange típusok általában a nyilvános felületeken gyakran használt alaptípusok (mint például Int32 és String a .NET-ben) és interfészek (mint például IList<T>, IEnumerable<T> és IComparable<T>).

Az Exchange-típusok csak azokat a típusokat tehetik nyilvánosan közzé, amelyeket szintén Exchange kompatibilisként jelöltek meg. Ezenkívül az exchange-típusok nem függenek a windowsos API-k viselkedésétől, amelyek hajlamosak a változásra.

Összetevőkre vonatkozó garanciák

Az alábbi táblázat azt mutatja be, hogy egy összetevő jellemzői és használata hogyan befolyásolja a kompatibilitási garanciát.

Összetevők jellemzői	Exchange	Stabil	Egymás mellett	Nincs
Az egymástól független verziójú összetevők közötti felületeken használható.	Y	N	N	N
Olyan szerelvény használható (privát módon), amely különálló verziószámokkal rendelkezik.	Y	Y	Y	N
Egyetlen alkalmazástartományban több verzió is lehet.	N	Y	Y	Y
Kompatibilitástörő módosításokat hajthat végre	N	N	Y	Y
Arra tesztelték, hogy a szerelvény több verziója együtt tölthető legyen be.	N	N	Y	N
A kompatibilitástörő módosításokat közvetlenül a helyszínen végezheti el.	N	N	N	Y
Nagyon biztonságos, nem megszakító karbantartási változtatásokat végezhet.	Y	Y	Y	Y

Az attribútum alkalmazása

Alkalmazhatja a ComponentGuaranteesAttribute szerelvényre, típusra vagy típustagra. Alkalmazása hierarchikus. Ez alapértelmezés szerint a szerelvény szintjén az Guarantees attribútum tulajdonsága által meghatározott garancia határozza meg a szerelvény összes típusának és az ilyen típusú tagoknak a garanciát. Hasonlóképpen, ha a garancia a típusra vonatkozik, alapértelmezés szerint a típus minden tagjára is vonatkozik.

Ezt az örökölt garanciát felül lehet bírálni az ComponentGuaranteesAttribute egyes típusok és típustagok alkalmazásával. Az alapértelmezett garanciákat felülíró garanciák azonban csak gyengíthetik a garanciát; nem tudják megerősíteni. Ha például egy szerelvényt garanciával None jelöl meg, a típusok és tagok nem rendelkeznek kompatibilitási garanciával, és a szerelvény típusokra vagy tagokra alkalmazott egyéb garanciák figyelmen kívül lesznek hagyva.

A garancia tesztelése

A Guarantees tulajdonság az ComponentGuaranteesOptions enumerálás egy tagját adja vissza, amely az FlagsAttribute attribútummal van megjelölve. Ez azt jelenti, hogy a potenciálisan ismeretlen jelzők maszkolásával tesztelnie kell az önt érdeklő jelzőt. Az alábbi példa például azt ellenőrzi, hogy egy típus van-e megjelölve.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

Az alábbi példa azt teszteli, hogy egy típus a következőként StableExchangevan-e megjelölve.

// 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

Az alábbi példa azt teszteli, hogy egy típus None-ként van-e megjelölve (vagyis sem Stable-ként, sem Exchange-ként).

// 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

Konstruktorok

Name	Description
ComponentGuaranteesAttribute(ComponentGuaranteesOptions)	Inicializálja az ComponentGuaranteesAttribute osztály új példányát egy olyan értékkel, amely egy kódtár, típus vagy tag garantált kompatibilitási szintjét jelzi több verzióban.

Tulajdonságok

Name	Description
Guarantees	Olyan értéket kap, amely egy több verzióra kiterjedő kódtár, típus vagy típustag garantált kompatibilitási szintjét jelzi.
TypeId	Ha származtatott osztályban implementálják, ehhez egy egyedi azonosítót Attributekap. (Öröklődés forrása Attribute)

Metódusok

Name	Description
Equals(Object)	Olyan értéket ad vissza, amely jelzi, hogy ez a példány egyenlő-e egy adott objektummal. (Öröklődés forrása Attribute)
GetHashCode()	A példány kivonatkódját adja vissza. (Öröklődés forrása Attribute)
GetType()	Lekéri az Type aktuális példányt. (Öröklődés forrása Object)
IsDefaultAttribute()	Ha egy származtatott osztályban felül van bírálva, azt jelzi, hogy a példány értéke-e a származtatott osztály alapértelmezett értéke. (Öröklődés forrása Attribute)
Match(Object)	Származtatott osztály felülírásakor egy olyan értéket ad vissza, amely jelzi, hogy ez a példány egy adott objektummal egyenlő-e. (Öröklődés forrása Attribute)
MemberwiseClone()	Az aktuális Objectpéldány sekély másolatát hozza létre. (Öröklődés forrása Object)
ToString()	Az aktuális objektumot jelképező sztringet ad vissza. (Öröklődés forrása Object)

Lásd még

• ComponentGuaranteesOptions