System.Runtime.Versioning.ComponentGuaranteesAttribute-Klasse

Artikel
01/11/2024

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 dies dann als Hilfe beim Entwerfen eigener Schnittstellen verwenden ComponentGuaranteesAttribute , um stabilitätsübergreifend 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

Dies ComponentGuaranteesAttribute unterstützt die folgenden Kompatibilitätsebenen, die durch Member 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.
Parallele Versions-zu-Version-Kompatibilität (ComponentGuaranteesOptions.SideBySide). Die Komponente wurde getestet, um zu funktionieren, wenn mehrere Versionen der Assembly in derselben Anwendung geladen werden Standard. Im Allgemeinen können zukünftige Versionen die Kompatibilität unterbrechen. Wenn jedoch Änderungen geändert werden, wird die alte Version nicht geändert, sondern neben der neuen Version vorhanden. Die parallele Ausführung ist die erwartete Möglichkeit, vorhandene Clients beim Unterbrechen von Änderungen zu bearbeiten. 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 erwartet, dass nur eine Version dieser Typen in einer bestimmten Anwendung enthalten ist Standard was bedeutet, dass die Kompatibilitätsproblem nicht behoben werden kann, wenn ein Client unterbrochen wird. 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 Anwendung geladen werden Standard. Unterbrechungsänderungen sind zulässig, solange sie an der Assembly vorgenommen werden, die 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 Komponente zu aktualisieren, die deklariert wird, indem die alte Version destruktiv geändert wird SideBySide .

Stabile Kompatibilität

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

Stabile Typen Standard eine hohe binäre Kompatibilitätsleiste enthalten. Aus diesem Gründen sollten Anbieter verhindern, dass änderungen an stabilen Typen geändert werden. Die folgenden Arten von Änderungen sind akzeptabel:

Hinzufügen von Feldern für private Instanzen zu oder Entfernen von Feldern aus einem Typ, sofern dadurch das Serialisierungsformat nicht getrennt wird.
Ä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 abgeleiteterer Ausnahmen.
Verbessern der Leistung einer Methode.
Ändern des Rückgabebereichs, 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 neue Versionen von stabilen Komponenten nicht erwartet werden, dass vorhandene Clients abgebrochen werden, ist in der Regel nur eine Version einer stabilen Komponente in einer Anwendung erforderlich Standard. Dies ist jedoch keine Voraussetzung, da stabile Typen nicht als bekannte Austauschtypen verwendet werden, die alle Komponenten zustimmen. 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.

Stablekann mit SideBySidekombiniert werden, die besagt, dass die Komponente die Kompatibilität nicht unterbricht, aber getestet wird, um zu funktionieren, wenn mehrere Versionen in einer bestimmten Anwendung geladen werden Standard.

Nachdem ein Typ oder eine Methode als Stablegekennzeichnet wurde, kann es aktualisiert werden.Exchange Es kann jedoch nicht herabgestuft werden.None

Exchange-Typkompatibilität

Das Kennzeichnen eines Typs als ComponentGuaranteesOptions.Exchange eine stärkere Versionskompatibilitätsgarantie als Stable, und sollte auf die stabilste aller Typen angewendet werden. Diese Typen sollen für den Austausch zwischen unabhängig erstellten Komponenten über alle Komponentengrenzen hinweg verwendet werden (jede Version der CLR oder eine beliebige Version einer Komponente oder Anwendung) und Speicherplatz (prozessübergreifende, cross-CLR in einem Prozess, cross-application do Standard in einem CLR). Wenn an einem Exchange-Typ eine änderung vorgenommen wird, ist es unmöglich, das Problem zu beheben, indem mehrere Versionen des Typs geladen werden.

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.

Im Folgenden werden unterbrechungsveränderte Änderungen betrachtet und sind für primitive Typen nicht zulässig:

Ändern von Serialisierungsformaten Versionstolerante Serialisierung ist erforderlich.
Hinzufügen oder Entfernen von Feldern für private Instanzen. Dadurch wird das Serialisierungsformat des Typs und das Unterbrechen von Clientcode, der Spiegelung verwendet, geändert.
Ändern der Serialisierbarkeit eines Typs. Ein nicht serialisierbarer Typ kann nicht serialisierbar gemacht werden und umgekehrt.
Auslösen unterschiedlicher Ausnahmen von einer Methode.
Ändern des Bereichs der Rückgabewerte einer Methode, es sei denn, die Memberdefinition löst diese Möglichkeit aus und gibt eindeutig an, wie Clients unbekannte Werte behandeln sollen.
Beheben der meisten Fehler. Verbraucher des Typs basieren auf dem vorhandenen Verhalten.

Nachdem eine Komponente, ein Typ oder ein Element mit der Exchange Garantie gekennzeichnet wurde, kann sie nicht in eine Stable oder Nonemehrere Elemente geändert werden.

In der Regel sind Exchange-Typen die grundlegenden Typen (z Int32 . B. und String in .NET) und Schnittstellen (z IList<T>. B. , 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	Exchange	Stable	Nebeneinander	Keine
Kann in Schnittstellen zwischen Komponenten verwendet werden, die unabhängig voneinander ausgeführt werden.	Y	N	N	N
Kann (privat) von einer Assembly verwendet werden, die unabhängig voneinander ausgeführt wird.	Y	Y	Y	N
Kann mehrere Versionen in einer einzigen Anwendung haben Standard.	N	J	Y	J
Änderungen können geändert werden	N	N	J	J
Getestet, um bestimmte mehrere Versionen der Assembly zusammen zu laden.	N	N	Y	N
Kann änderungen an Ort und Stelle vornehmen.	N	N	N	J
Kann sehr sichere ungebrochene Wartungsänderungen vornehmen.	Y	Y	Y	J

Anwenden des Attributs

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

Diese geerbte Garantie kann überschrieben werden, indem die ComponentGuaranteesAttribute einzelnen Typen und Typenmmber angewendet werden. Garantien, die den Standardwert außer Kraft setzen, können jedoch nur die Garantie schwächen; sie können es 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.

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

Im folgenden Beispiel wird überprüft, ob ein Typ als Stable oder 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

Im folgenden Beispiel wird ein Typ mit einem Typ markiert None (d. a. weder Stable noch Exchange).

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