System.Runtime.Versioning.ComponentGuaranteesAttribute, klasa

Ten artykuł zawiera dodatkowe uwagi dotyczące dokumentacji referencyjnej dla tego interfejsu API.

Element ComponentGuaranteesAttribute jest używany przez deweloperów składników i bibliotek klas, aby wskazać poziom zgodności, którego użytkownicy bibliotek mogą oczekiwać w wielu wersjach. Wskazuje poziom gwarancji, że przyszła wersja biblioteki lub składnika nie spowoduje przerwania istniejącego klienta. Klienci mogą następnie używać elementu ComponentGuaranteesAttribute jako pomocy w projektowaniu własnych interfejsów, aby zapewnić stabilność w różnych wersjach.

Uwaga

Środowisko uruchomieniowe języka wspólnego (CLR) nie używa tego atrybutu w żaden sposób. Jego wartość polega na formalnym dokumentowaniu intencji autora składnika. Narzędzia czasu kompilacji mogą również używać tych deklaracji do wykrywania błędów czasu kompilacji, które w przeciwnym razie przerwałyby zadeklarowaną gwarancję.

Poziomy zgodności

Element ComponentGuaranteesAttribute obsługuje następujące poziomy zgodności, które są reprezentowane przez elementy członkowskie ComponentGuaranteesOptions wyliczenia:

• Brak zgodności wersji do wersji (ComponentGuaranteesOptions.None). Klient może oczekiwać, że przyszłe wersje spowodują przerwanie istniejącego klienta. Aby uzyskać więcej informacji, zobacz sekcję Brak zgodności w dalszej części tego artykułu.

• Zgodność z wersją do wersji równoległej (ComponentGuaranteesOptions.SideBySide). Składnik został przetestowany pod kątem działania w przypadku załadowania więcej niż jednej wersji zestawu w tej samej domenie aplikacji. Ogólnie rzecz biorąc, przyszłe wersje mogą przerwać zgodność. Jednak w przypadku wprowadzania zmian powodujących niezgodność stara wersja nie jest modyfikowana, ale istnieje wraz z nową wersją. Wykonywanie równoległe to oczekiwany sposób działania istniejących klientów podczas wprowadzania zmian powodujących niezgodność. Aby uzyskać więcej informacji, zobacz sekcję zgodność obok siebie w dalszej części tego artykułu.

• Stabilna zgodność wersji z wersją (ComponentGuaranteesOptions.Stable). Przyszłe wersje nie powinny przerywać działania klienta, a wykonywanie równoległe nie powinno być potrzebne. Jeśli jednak klient jest przypadkowo uszkodzony, może być możliwe użycie wykonywania równoległego w celu rozwiązania problemu. Aby uzyskać więcej informacji, zobacz sekcję Stabilna zgodność .

• Zgodność z wersją do wersji programu Exchange (ComponentGuaranteesOptions.Exchange). W celu zapewnienia, że przyszłe wersje nie spowodują przerwania działania klienta. Klient powinien używać tylko tych typów w podpisie interfejsów używanych do komunikacji z innymi zestawami, które są wdrażane niezależnie od siebie. Oczekuje się, że tylko jedna wersja tych typów znajduje się w danej domenie aplikacji, co oznacza, że w przypadku przerwania działania klienta wykonywanie równoległe nie może rozwiązać problemu ze zgodnością. Aby uzyskać więcej informacji, zobacz sekcję Zgodność typów programu Exchange.

W poniższych sekcjach omówiono bardziej szczegółowo każdy poziom gwarancji.

Brak zgodności

Oznaczanie składnika jako ComponentGuaranteesOptions.None wskazuje, że dostawca nie gwarantuje zgodności. Klienci powinni unikać podejmowania wszelkich zależności od uwidocznionych interfejsów. Ten poziom zgodności jest przydatny w przypadku typów eksperymentalnych lub udostępnianych publicznie, ale przeznaczonych tylko dla składników, które są zawsze aktualizowane w tym samym czasie. None jawnie wskazuje, że ten składnik nie powinien być używany przez składniki zewnętrzne.

Zgodność równoległa

Oznaczanie składnika jako ComponentGuaranteesOptions.SideBySide wskazuje, że składnik został przetestowany pod kątem działania, gdy więcej niż jedna wersja zestawu jest ładowana do tej samej domeny aplikacji. Zmiany powodujące niezgodność są dozwolone, o ile są wprowadzane do zestawu, który ma większy numer wersji. Oczekuje się, że składniki powiązane ze starą wersją zestawu będą nadal powiązane ze starą wersją, a inne składniki mogą wiązać się z nową wersją. Istnieje również możliwość zaktualizowania składnika zadeklarowanego SideBySide przez destruktywną modyfikację starej wersji.

Stabilna zgodność

Oznaczanie typu wskazuje ComponentGuaranteesOptions.Stable , że typ powinien pozostać stabilny w różnych wersjach. Jednak może być również możliwe, aby wersje równoległe stabilnego typu istniały w tej samej domenie aplikacji.

Stabilne typy utrzymują wysoki pasek zgodności binarnej. W związku z tym dostawcy powinni unikać wprowadzania zmian powodujących niezgodność w stabilnych typach. Dopuszczalne są następujące rodzaje zmian:

• Dodawanie pól wystąpienia prywatnego do lub usuwanie pól z typu, o ile nie spowoduje to przerwania formatu serializacji.
• Zmiana typu niesererowalnego na typ możliwy do serializacji. (Nie można jednak zmienić typu możliwego do serializacji na typ nies serializowalny).
• Zgłaszanie nowych, bardziej pochodnych wyjątków z metody.
• Poprawianie wydajności metody.
• Zmiana zakresu wartości zwracanych, o ile zmiana nie ma negatywnego wpływu na większość klientów.
• Naprawianie poważnych usterek, jeśli uzasadnienie biznesowe jest wysokie, a liczba klientów, których to dotyczy, jest niska.

Ponieważ nowe wersje stabilnych składników nie powinny przerywać istniejących klientów, w domenie aplikacji jest wymagana tylko jedna wersja stabilnego składnika. Nie jest to jednak wymagane, ponieważ stabilne typy nie są używane jako dobrze znane typy wymiany, na które zgadzają się wszystkie składniki. W związku z tym, jeśli nowa wersja stabilnego składnika przypadkowo uszkodzi jakiś składnik, a jeśli inne składniki potrzebują nowej wersji, może być możliwe rozwiązanie problemu przez załadowanie zarówno starego, jak i nowego składnika.

Stable zapewnia silniejszą gwarancję zgodności wersji niż None. Jest to typowa wartość domyślna dla składników z wieloma wersjami.

Stable można połączyć z elementem SideBySide, co oznacza, że składnik nie spowoduje przerwania zgodności, ale jest testowany pod kątem działania w przypadku załadowania więcej niż jednej wersji w danej domenie aplikacji.

Po oznaczeniu typu lub metody jako Stablemożna go uaktualnić do Exchangeklasy . Nie można go jednak obniżyć do .None

Zgodność typu programu Exchange

Oznaczanie typu jako ComponentGuaranteesOptions.Exchange zapewnia silniejszą gwarancję zgodności wersji niż Stable, i powinny być stosowane do najbardziej stabilnych wszystkich typów. Te typy mają być używane do wymiany między niezależnie utworzonymi składnikami we wszystkich granicach składników w obu przypadkach (dowolna wersja środowiska CLR lub dowolnej wersji składnika lub aplikacji) i spacji (między procesami, cross-CLR w jednym procesie, domeną między aplikacjami w jednym środowisku CLR). Jeśli zmiana powodująca niezgodność zostanie wprowadzona w typie wymiany, nie można rozwiązać problemu przez załadowanie wielu wersji typu.

Typy wymiany powinny być zmieniane tylko wtedy, gdy problem jest bardzo poważny (taki jak poważny problem z zabezpieczeniami) lub prawdopodobieństwo przerwania jest bardzo niskie (czyli jeśli zachowanie zostało już przerwane w losowy sposób, że kod nie mógł podjąć zależności). Możesz wprowadzić następujące rodzaje zmian w typie wymiany:

• Dodaj dziedziczenie nowych definicji interfejsu.

• Dodaj nowe metody prywatne, które implementują metody nowo odziedziczonych definicji interfejsu.

• Dodaj nowe pola statyczne.

• Dodaj nowe metody statyczne.

• Dodaj nowe metody wystąpień innych niż wirtualne.

Poniżej przedstawiono zmiany powodujące niezgodność i nie są dozwolone dla typów pierwotnych:

• Zmienianie formatów serializacji. Wymagana jest serializacja odporna na wersje.

• Dodawanie lub usuwanie pól wystąpienia prywatnego. Wiąże się to ze zmianą formatu serializacji typu i powodującego niezgodność kodu klienta, który używa odbicia.

• Zmiana serializacji typu. Typ nies serializowalny może nie być serializowalny i odwrotnie.

• Zgłaszanie różnych wyjątków od metody.

• Zmiana zakresu zwracanych wartości metody, chyba że definicja elementu członkowskiego zgłasza tę możliwość i wyraźnie wskazuje, jak klienci powinni obsługiwać nieznane wartości.

• Naprawianie większości usterek. Konsumenci typu będą polegać na istniejącym zachowaniu.

Po oznaczeniu składnika, typu lub elementu członkowskiego z gwarancją Exchange nie można go zmienić na Stable lub None.

Zazwyczaj typy wymiany to podstawowe typy (takie jak i String na platformie .NET) i interfejsy (takie jak IList<T>Int32 , IEnumerable<T>i IComparable<T>), które są często używane w interfejsach publicznych.

Typy programu Exchange mogą publicznie uwidaczniać tylko inne typy, które są również oznaczone zgodnością Exchange . Ponadto typy wymiany nie mogą zależeć od zachowania interfejsów API systemu Windows, które są podatne na zmianę.

Gwarancje składników

W poniższej tabeli przedstawiono, jak cechy i użycie składnika wpływają na jego gwarancję zgodności.

Charakterystyka składników	Exchange	Stable	Obok siebie	Brak
Może być używany w interfejsach między składnikami, które niezależnie są wersjonujące.	Y	N	N	N
Może być używany (prywatnie) przez zestaw, który wersje niezależnie.	Y	Y	Y	N
Może mieć wiele wersji w jednej domenie aplikacji.	N	Y	Y	Y
Może wprowadzać zmiany powodujące niezgodność	N	N	Y	Y
Przetestowano, aby niektóre wersje zestawu mogły być ładowane razem.	N	N	Y	N
Może wprowadzać zmiany powodujące niezgodność.	N	N	N	Y
Może wprowadzać bardzo bezpieczne zmiany obsługi powodujące niezgodność.	Y	Y	Y	Y

Stosowanie atrybutu

Można zastosować element ComponentGuaranteesAttribute do zestawu, typu lub elementu członkowskiego typu. Jego aplikacja jest hierarchiczna. Oznacza to, że domyślnie gwarancja zdefiniowana przez Guarantees właściwość atrybutu na poziomie zestawu definiuje gwarancję wszystkich typów w zestawie i wszystkich elementów członkowskich w tych typach. Podobnie, jeśli gwarancja jest stosowana do typu, domyślnie ma zastosowanie również do każdego elementu członkowskiego typu.

Ta dziedziczona gwarancja może zostać zastąpiona przez zastosowanie elementu ComponentGuaranteesAttribute do poszczególnych typów i składowych typów. Jednak gwarancje, które zastępują wartość domyślną, mogą jedynie osłabić gwarancję; nie mogą go wzmocnić. Na przykład jeśli zestaw jest oznaczony gwarancją None , jego typy i elementy członkowskie nie mają gwarancji zgodności, a każda inna gwarancja, która jest stosowana do typów lub elementów członkowskich w zestawie, jest ignorowana.

Testowanie gwarancji

Właściwość Guarantees zwraca element członkowski ComponentGuaranteesOptions wyliczenia, który jest oznaczony atrybutem FlagsAttribute . Oznacza to, że należy przetestować flagę, którą cię interesuje, maskując potencjalnie nieznane flagi. Na przykład poniższy przykład sprawdza, czy typ jest oznaczony 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

Poniższy przykład sprawdza, czy typ jest oznaczony jako Stable lub 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

W poniższym przykładzie testy z typem są oznaczone jako None (to znaczy, ani StableExchange).

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