System.Runtime.Versioning.ComponentGuaranteesAttribute 類別

  • 發行項

本文提供此 API 參考文件的補充備註。

ComponentGuaranteesAttribute元件和類別庫的開發人員會使用 ，指出其連結庫取用者可在多個版本之間預期的相容性層級。 指出未來連結庫或元件版本不會中斷現有客戶端的保證層級。 用戶端接著 ComponentGuaranteesAttribute 可以使用 做為設計其專屬介面的協助，以確保版本之間的穩定性。

注意

Common Language Runtime （CLR） 不會以任何方式使用此屬性。 其值在於正式記載元件作者的意圖。 編譯時間工具也可以使用這些宣告來偵測編譯時間錯誤，否則會中斷宣告的保證。

相容性層級

ComponentGuaranteesAttribute支援下列層級的相容性，這些層級是由 列舉的成員ComponentGuaranteesOptions表示：

  • 沒有版本對版本相容性 （ComponentGuaranteesOptions.None）。 用戶端可以預期未來的版本會中斷現有的用戶端。 如需詳細資訊，請參閱本文稍後的 <無相容性 >一節。

  • 並存版本對版本相容性 （ComponentGuaranteesOptions.SideBySide）。 元件已在相同應用程式域中載入多個元件版本時進行測試，以運作。 一般而言，未來的版本可能會中斷相容性。 不過，進行重大變更時，不會修改舊版本，但與新版本並存。 並行執行是讓現有客戶端在進行重大變更時運作的預期方式。 如需詳細資訊，請參閱 本文稍後的並存相容性 一節。

  • 穩定版本對版本相容性 （ComponentGuaranteesOptions.Stable）。 未來的版本不應該中斷用戶端，而且不應該需要並存執行。 不過，如果用戶端不小心中斷，則可能可以使用並存執行來修正問題。 如需詳細資訊，請參閱 穩定相容性 一節。

  • Exchange 版本對版本相容性 （ComponentGuaranteesOptions.Exchange）。 請務必特別小心，以確保未來的版本不會中斷用戶端。 客戶端應該只在介面簽章中使用這些類型，這些類型是用來與彼此獨立部署的其他元件通訊。 這些類型的其中一個版本應該在指定的應用程式域中，這表示如果用戶端中斷，並存執行便無法修正相容性問題。 如需詳細資訊，請參閱 Exchange 類型相容性 一節。

下列各節會更詳細地討論每個保證層級。

沒有相容性

將元件標示為 ComponentGuaranteesOptions.None ，表示提供者不會保證相容性。 客戶端應該避免對公開介面採取任何相依性。 此層級的相容性對於實驗性或公開但僅適用於一律同時更新的元件。 None 明確表示外部元件不應使用此元件。

並存相容性

將元件標示為 ComponentGuaranteesOptions.SideBySide ，表示當多個版本的元件載入至相同的應用程式域時，元件已經過測試才能運作。 只要對具有較大版本號碼的元件進行重大變更，就允許進行重大變更。 系結至舊版元件的元件應該會繼續系結至舊版本，而其他元件可以系結至新版本。 您也可以藉由以破壞性方式修改舊版來更新宣告為 SideBySide 的元件。

穩定相容性

將類型標示為 ComponentGuaranteesOptions.Stable ，表示類型應該在版本之間保持穩定。 不過，也可以讓穩定類型的並存版本存在於相同的應用程式域中。

穩定類型會維護高二進位相容性列。 因此，提供者應該避免對穩定類型進行重大變更。 可以接受下列類型的變更：

  • 只要這不會中斷串行化格式，將私用實例欄位新增至 類型，或從中移除欄位。
  • 將不可串行化類型變更為可串行化類型。 （不過，無法將可串行化類型變更為不可串行化的類型。
  • 從方法擲回新的衍生例外狀況。
  • 改善方法的效能。
  • 變更傳回值的範圍，只要變更不會對大多數用戶端造成負面影響。
  • 修正嚴重的錯誤，如果業務理由很高，且受影響的用戶端數目很低。

由於新版穩定元件不會中斷現有的用戶端，因此應用程式域中通常只需要一個穩定元件的版本。 不過，這不是必要專案，因為穩定型別不會當做所有元件都同意的已知交換類型使用。 因此，如果新版的穩定元件不小心中斷某些元件，而如果其他元件需要新版本，則載入舊元件和新元件可能會修正問題。

Stable 提供比 None更強的版本相容性保證。 這是多版本元件的常見預設值。

Stable 可以與 SideBySide結合，指出元件不會中斷相容性，但在指定應用程式域中載入多個版本時，會測試為運作。

在類型或方法標示為 Stable之後，它可以升級至 Exchange。 不過，它無法降級為 None。

Exchange 類型相容性

將類型標示為 ComponentGuaranteesOptions.Exchange 提供比 Stable更強的版本相容性保證，而且應該套用至所有類型中最穩定的類型。 這些類型旨在用於跨兩個時間跨所有元件界限獨立建置元件之間的交換（任何版本的 CLR 或元件或應用程式的任何版本）和空間（跨進程、跨 CLR 在一個進程中跨應用程式域、一個 CLR 中的跨應用程式域）。 如果對交換類型進行重大變更，則無法藉由載入類型的多個版本來修正問題。

只有在問題非常嚴重（例如嚴重安全性問題）或中斷機率非常低時，才應該變更 Exchange 類型（也就是說，如果行為已以無法想像的相依性來隨機中斷）。 您可以對交換類型進行下列類型的變更：

  • 新增新介面定義的繼承。

  • 新增新的私用方法，以實作新繼承介面定義的方法。

  • 新增靜態欄位。

  • 新增靜態方法。

  • 新增非虛擬實例方法。

以下是重大變更，基本類型不允許下列專案：

  • 變更串行化格式。 需要版本容錯串行化。

  • 新增或移除私用實例欄位。 這可能會變更型別的串行化格式，以及中斷使用反映的用戶端程序代碼。

  • 變更型別的串行化性。 不可串行化的類型可能無法串行化，反之亦然。

  • 從方法擲回不同的例外狀況。

  • 除非成員定義引發這個可能性，否則變更方法的傳回值範圍，並清楚指出客戶端應該如何處理未知的值。

  • 修正大部分的錯誤。 型別的取用者會依賴現有的行為。

元件、類型或成員標示為 Exchange 保證之後，就無法將它變更為 Stable 或 None。

一般而言，交換類型是公開介面中常用的基本型別（例如 Int32 . String NET 中的 和 ）和介面（例如 IList<T>、 IEnumerable<T>和 IComparable<T>）。

Exchange 類型可能只公開其他也標示為 Exchange 相容性的類型。 此外，交換類型不取決於容易變更的 Windows API 行為。

元件保證

下表指出元件的特性和使用方式如何影響其相容性保證。

元件特性 Exchange 穩定 並存 無
可用於個別版本的元件之間的介面。 是 N N N
可由獨立版本的元件使用（私下）。 Y Y Y 否
單一應用程式域中可以有多個版本。 否 是 Y Y
可以進行重大變更 N N 是 Y
測試可讓元件的特定多個版本一起載入。 N N Y 否
可以就地進行重大變更。 N N N 是
可以就地進行非常安全的非中斷性服務變更。 Y Y Y Y

套用 屬性

您可以將 套用 ComponentGuaranteesAttribute 至元件、類型或類型成員。 其應用程式是階層式的。 根據預設，元件層級屬性所 Guarantees 定義的保證會定義元件中的所有型別和這些類型中所有成員的保證。 同樣地，如果保證套用至類型，則預設也會套用至類型的每個成員。

將 套用 ComponentGuaranteesAttribute 至個別類型和類型成員，即可覆寫此繼承的保證。 不過，保證覆寫預設值只能削弱保證;他們不能加強它。 例如，如果元件標示為 None 保證，則其類型和成員沒有相容性保證，而且會忽略套用至元件中類型或成員的任何其他保證。

測試保證

屬性 Guarantees 會傳回列舉的成員 ComponentGuaranteesOptions ，這個成員會以 FlagsAttribute 屬性標示。 這表示您應該藉由遮罩可能未知的旗標來測試您感興趣的旗標。 例如，下列範例會測試類型是否標示為 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

下列範例會測試類型是否標示為 Stable 或 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

下列範例會測試具型別的標示為 None （亦即 ， 和 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