System.Runtime.Versioning.ComponentGuaranteesAttribute-Klasse

Dieser Artikel enthält ergänzende Hinweise zur Referenzdokumentation für diese API.

Dies ComponentGuaranteesAttribute wird von Entwicklern von Komponenten und Klassenbibliotheken verwendet, um den Kompatibilitätsgrad anzugeben, den Verbraucher ihrer Bibliotheken in mehreren Versionen erwarten können. Sie gibt die Garantieebene an, dass eine zukünftige Version der Bibliothek oder Komponente einen vorhandenen Client nicht unterbricht. Kunden können das ComponentGuaranteesAttribute dann als Hilfe beim Entwerfen ihrer eigenen Schnittstellen verwenden, um Stabilität über verschiedene Versionen hinweg zu gewährleisten.

Hinweis

Die Common Language Runtime (CLR) verwendet dieses Attribut nicht auf irgendeine Weise. Der Wert liegt in der formalen Dokumentation der Absicht des Komponentenautors. Kompilierungszeittools können diese Deklarationen auch verwenden, um Kompilierungszeitfehler zu erkennen, die andernfalls die deklarierte Garantie unterbrechen würden.

Kompatibilitätsstufen

Dieser ComponentGuaranteesAttribute unterstützt die folgenden Kompatibilitätsebenen, die durch Mitglieder der ComponentGuaranteesOptions-Enumeration dargestellt werden:

• Keine Versions-zu-Version-Kompatibilität (ComponentGuaranteesOptions.None). Der Client kann davon ausgehen, dass zukünftige Versionen den vorhandenen Client unterbrechen. Weitere Informationen finden Sie im Abschnitt "Keine Kompatibilität" weiter unten in diesem Artikel.

• Side-by-Side Version-to-Version-Kompatibilität (ComponentGuaranteesOptions.SideBySide). Die Komponente wurde getestet, um zu funktionieren, wenn mehrere Versionen der Assembly in derselben Anwendungsdomäne geladen werden. Im Allgemeinen können zukünftige Versionen die Kompatibilität unterbrechen. Wenn jedoch grundlegende Änderungen vorgenommen werden, wird die alte Version nicht modifiziert, sondern existiert neben der neuen Version. Die Side-by-Side-Ausführung ist der erwartete Weg, um bestehende Kunden zum Laufen zu bringen, wenn Änderungen vorgenommen werden. Weitere Informationen finden Sie im Abschnitt " Parallele Kompatibilität " weiter unten in diesem Artikel.

• Stabile Versions-zu-Version-Kompatibilität (ComponentGuaranteesOptions.Stable). Zukünftige Versionen sollten den Client nicht unterbrechen, und die parallele Ausführung sollte nicht erforderlich sein. Wenn der Client jedoch versehentlich beschädigt ist, kann es möglich sein, die parallele Ausführung zu verwenden, um das Problem zu beheben. Weitere Informationen finden Sie im Abschnitt "Stable Compatibility" .

• Kompatibilität der Exchange-Version zu Version (ComponentGuaranteesOptions.Exchange). Außerordentliche Sorgfalt wird unternommen, um sicherzustellen, dass zukünftige Versionen den Client nicht unterbrechen. Der Client sollte nur diese Typen in der Signatur von Schnittstellen verwenden, die für die Kommunikation mit anderen Assemblys verwendet werden, die unabhängig voneinander bereitgestellt werden. Es wird davon ausgegangen, dass sich nur eine Version dieser Typen in einer bestimmten Anwendungsdomäne befindet, was bedeutet, dass, wenn ein Client ausfällt, die parallele Ausführung das Kompatibilitätsproblem nicht beheben kann. Weitere Informationen finden Sie im Exchange-Typkompatibilitätsbereich .

In den folgenden Abschnitten werden die einzelnen Garantieebenen ausführlicher erläutert.

Keine Kompatibilität

Das Kennzeichnen einer Komponente als ComponentGuaranteesOptions.None Hinweis darauf, dass der Anbieter keine Garantien hinsichtlich der Kompatibilität gewährleistet. Clients sollten keine Abhängigkeiten von den verfügbar gemachten Schnittstellen übernehmen. Diese Kompatibilitätsstufe ist nützlich für Typen, die experimentell sind oder öffentlich verfügbar gemacht werden, aber nur für Komponenten vorgesehen sind, die immer gleichzeitig aktualisiert werden. None gibt explizit an, dass diese Komponente nicht von externen Komponenten verwendet werden soll.

Parallele Kompatibilität

Kennzeichnen einer Komponente als ComponentGuaranteesOptions.SideBySide Hinweis darauf, dass die Komponente getestet wurde, um zu funktionieren, wenn mehrere Versionen der Assembly in dieselbe Anwendungsdomäne geladen werden. Wichtige Änderungen sind zulässig, solange sie an dem Assembly vorgenommen werden, das die höhere Versionsnummer aufweist. Komponenten, die an eine alte Version der Assembly gebunden sind, werden voraussichtlich weiterhin an die alte Version gebunden, und andere Komponenten können an die neue Version gebunden werden. Es ist auch möglich, eine als SideBySide deklarierte Komponente zu aktualisieren, indem die alte Version destruktiv geändert wird.

Stabile Kompatibilität

Kennzeichnen eines Typs als ComponentGuaranteesOptions.Stable Hinweis darauf, dass der Typ in allen Versionen stabil bleiben soll. Es kann jedoch auch möglich sein, dass parallele Versionen eines stabilen Typs in derselben Anwendungsdomäne vorhanden sind.

Stabile Typen behalten eine hohe binäre Kompatibilitätsleiste bei. Aus diesem Grund sollten Anbieter vermeiden, dass stabile Typen grundlegend geändert werden. Die folgenden Arten von Änderungen sind akzeptabel:

• Hinzufügen von privaten Instanzfeldern zu oder Entfernen von Feldern aus einem Typ, solange dies das Serialisierungsformat nicht unterbricht.
• Ändern eines nicht serialisierbaren Typs in einen serialisierbaren Typ. (Ein serialisierbarer Typ kann jedoch nicht in einen nicht serialisierbaren Typ geändert werden.)
• Auslösen neuer, von einer Methode abgeleiteten Ausnahmen.
• Verbessern der Leistung einer Methode.
• Ändern des Bereichs der Rückgabewerte, sofern die Änderung die Mehrheit der Clients nicht beeinträchtigt.
• Behebung schwerwiegender Fehler, wenn die geschäftliche Begründung hoch ist und die Anzahl der negativ betroffenen Kunden niedrig ist.

Da es nicht erwartet wird, dass neue Versionen von stabilen Komponenten vorhandene Clients unterbrechen, ist in der Regel nur eine Version einer stabilen Komponente in einer Anwendungsdomäne erforderlich. Dies ist jedoch keine Voraussetzung, da stabile Typen nicht als allgemein anerkannte Austauschtypen verwendet werden, auf die sich alle Komponenten geeinigt haben. Wenn daher eine neue Version einer stabilen Komponente versehentlich einige Komponenten unterbricht und andere Komponenten die neue Version benötigen, kann es möglich sein, das Problem zu beheben, indem sowohl die alte als auch die neue Komponente geladen werden.

Stable bietet eine stärkere Versionskompatibilitätsgarantie als None. Es ist ein gängiger Standardwert für Komponenten mit mehreren Versionen.

Stable kann mit SideBySidekombiniert werden, was angibt, dass die Komponente die Kompatibilität nicht unterbricht, sondern getestet wird, um zu funktionieren, wenn mehrere Versionen in einer bestimmten Anwendungsdomäne geladen werden.

Nachdem ein Typ oder eine Methode als Stable gekennzeichnet wurde, kann sie auf Exchange aktualisiert werden. Es kann jedoch nicht auf None herabgestuft werden.

Exchange-Typkompatibilität

Das Kennzeichnen eines Typs als ComponentGuaranteesOptions.Exchange bietet eine stärkere Versionskompatibilitätsgarantie als Stable und sollte auf die stabilsten aller Typen angewendet werden. Diese Typen sind für den Austausch zwischen unabhängig gebauten Komponenten über alle Komponentengrenzen hinweg sowohl in der Zeit (jede Version der CLR oder jede Version einer Komponente oder Anwendung) als auch im Raum (prozessübergreifend, cross-CLR in einem Prozess, anwendungsübergreifende Domäne in einer CLR) vorgesehen. Wenn an einem Exchange-Typ eine kompatibilitätsbrechende Änderung vorgenommen wird, ist es unmöglich, das Problem durch das Laden mehrerer Versionen des Typs zu beheben.

Exchange-Typen sollten nur geändert werden, wenn ein Problem sehr schwerwiegend ist (z. B. ein schwerwiegendes Sicherheitsproblem) oder die Wahrscheinlichkeit eines Bruchs sehr niedrig ist (d. a., wenn das Verhalten bereits zufällig unterbrochen wurde, dass Code möglicherweise keine Abhängigkeit davon haben konnte). Sie können die folgenden Arten von Änderungen an einem Exchange-Typ vornehmen:

• Fügen Sie die Vererbung neuer Schnittstellendefinitionen hinzu.

• Fügen Sie neue private Methoden hinzu, die die Methoden neu geerbter Schnittstellendefinitionen implementieren.

• Fügen Sie neue statische Felder hinzu.

• Fügen Sie neue statische Methoden hinzu.

• Fügen Sie neue nicht virtuelle Instanzmethoden hinzu.

Die folgenden gelten als wichtige Änderungen und sind bei Primitiven-Typen nicht zulässig:

• Ändern von Serialisierungsformaten Versionstolerante Serialisierung ist erforderlich.

• Hinzufügen oder Entfernen von Feldern für private Instanzen. Dadurch besteht das Risiko, dass das Serialisierungsformat des Typs geändert wird und dadurch der Client-Code beschädigt wird, der Reflection verwendet.

• Ändern der Serialisierbarkeit eines Typs. Ein nicht serialisierbarer Typ kann nicht serialisierbar gemacht werden und umgekehrt.

• Verschiedene Ausnahmen aus einer Methode auslösen.

• Ändern des Bereichs der Rückgabewerte einer Methode, es sei denn, die Mitglieddefinition lässt diese Möglichkeit zu und gibt eindeutig an, wie Clients unbekannte Werte behandeln sollen.

• Beheben der meisten Fehler. Verbraucher dieses Typs werden sich auf das bestehende Verhalten verlassen.

Nachdem eine Komponente, ein Typ oder ein Element mit der Exchange-Garantie gekennzeichnet wurde, kann es nicht in ein Stable oder None geändert werden.

In der Regel sind Exchange-Typen die grundlegenden Typen (z. B. Int32 und String in .NET) und Schnittstellen (z. B. IList<T>, IEnumerable<T> und IComparable<T>), die häufig in öffentlichen Schnittstellen verwendet werden.

Exchange-Typen können nur andere Typen öffentlich verfügbar machen, die ebenfalls mit Exchange Kompatibilität gekennzeichnet sind. Darüber hinaus können Exchange-Typen nicht vom Verhalten von Windows-APIs abhängen, die anfällig für Änderungen sind.

Komponentengarantien

Die folgende Tabelle gibt an, wie sich die Eigenschaften und die Verwendung einer Komponente auf ihre Kompatibilitätsgarantie auswirken.

Komponentenmerkmale	Umtausch	Stable	Side-by-Side	Nichts
Kann in Schnittstellen zwischen Komponenten verwendet werden, die unabhängig voneinander ausgeführt werden.	J	N	N	N
Kann (privat) von einem Assembly verwendet werden, das unabhängig versioniert wird.	J	J	J	N
Kann mehrere Versionen in einer einzigen Anwendungsdomäne haben.	N	J	J	J
Kann Breaking Changes vornehmen	N	N	J	J
Geprüft, um sicherzustellen, dass mehrere Versionen der Assembly zusammen geladen werden können.	N	N	J	N
Kann wichtige Änderungen in-place vornehmen.	N	N	N	J
Kann sehr sichere, bruchfreie Wartungsänderungen vor Ort vornehmen.	J	J	J	J

Anwenden des Attributs

Sie können die ComponentGuaranteesAttribute auf eine Assembly, einen Typ oder ein Typmitglied anwenden. Die Anwendung ist hierarchisch. Das heißt, die Garantie, die durch die Guarantees-Eigenschaft des Attributs auf Assemblyebene definiert wird, legt standardmäßig die Garantie aller Typen in dem Assembly und aller Mitglieder in diesen Typen fest. Ebenso gilt die Garantie, wenn die Garantie auf den Typ angewendet wird, standardmäßig auch für jedes Mitglied des Typs.

Diese geerbte Garantie kann überschrieben werden, indem ComponentGuaranteesAttribute auf einzelne Typen und Typmitglieder angewendet wird. Garantien, die den Standardwert überschreiben setzen, können die Garantie jedoch nur abschwächen; sie können sie nicht stärken. Wenn beispielsweise eine Assembly mit der None Garantie gekennzeichnet ist, haben ihre Typen und Member keine Kompatibilitätsgarantie, und alle anderen Garantien, die auf Typen oder Member in der Assembly angewendet werden, werden ignoriert.

Testen der Garantie

Die Guarantees Eigenschaft gibt ein Element der ComponentGuaranteesOptions Aufzählung zurück, das mit dem FlagsAttribute Attribut gekennzeichnet ist. Dies bedeutet, dass Sie auf die Kennzeichnung testen sollten, an der Sie interessiert sind, indem Sie potenziell unbekannte Kennzeichen maskieren. Im folgenden Beispiel wird beispielsweise getestet, ob ein Typ als Stablegekennzeichnet ist.

C#

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine($"{typ.Name} is marked as {guarantee}.");

Im folgenden Beispiel wird überprüft, ob ein Datentyp als Stable oder Exchange markiert ist.

C#

// Test whether guarantee is Stable or Exchange.
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) > 0)
   Console.WriteLine($"{typ.Name} is marked as Stable or Exchange.");

Im folgenden Beispiel wird überprüft, ob ein Typ als None (d. s. weder Stable noch Exchange) markiert ist.

C#

// 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.");