ComponentGuaranteesAttribute 类

定义

定义可以跨多个版本的组件、类型或类型成员的兼容性保证。Defines the compatibility guarantee of a component, type, or type member that may span multiple versions.

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
type ComponentGuaranteesAttribute = class
    inherit Attribute
Public NotInheritable Class ComponentGuaranteesAttribute
Inherits Attribute
继承
ComponentGuaranteesAttribute
属性

注解

ComponentGuaranteesAttribute由组件和类库的开发人员用来指示其库的使用者可跨多个版本的兼容性级别。The ComponentGuaranteesAttribute is used by developers of components and class libraries to indicate the level of compatibility that consumers of their libraries can expect across multiple versions. 它表示库或组件的未来版本不会中断现有客户端的保证级别。It indicates the level of guarantee that a future version of the library or component will not break an existing client. 然后,客户端可以ComponentGuaranteesAttribute使用来帮助设计自己的接口,以确保各版本之间的稳定性。Clients can then use the ComponentGuaranteesAttribute as an aid in designing their own interfaces to ensure stability across versions.

备注

公共语言运行时(CLR)不以任何方式使用此属性。The common language runtime (CLR) does not use this attribute in any way. 它的值是记录组件作者的意图。Its value lies in formally documenting the intent of the component author. 编译时工具还可以使用这些声明来检测编译时错误,否则将破坏声明的保证。Compile-time tools can also use these declarations to detect compile-time errors that would otherwise break the declared guarantee.

兼容性级别Levels of Compatibility

支持以下级别的兼容性,由ComponentGuaranteesOptions枚举的成员表示: ComponentGuaranteesAttributeThe ComponentGuaranteesAttribute supports the following levels of compatibility, which are represented by members of the ComponentGuaranteesOptions enumeration:

  • 无版本到版本的兼容性(ComponentGuaranteesOptions.None)。No version-to-version compatibility (ComponentGuaranteesOptions.None). 客户端预计将来的版本会中断现有客户端。The client can expect that future versions will break the existing client. 有关详细信息,请参阅本主题后面的无兼容性部分。For more information, see the No Compatibility section later in this topic.

  • 并行版本到版本的兼容性(ComponentGuaranteesOptions.SideBySide)。Side-by-side version-to-version compatibility (ComponentGuaranteesOptions.SideBySide). 当在同一个应用程序域中加载程序集的多个版本时,已对该组件进行测试。The component has been tested to work when more than one version of the assembly is loaded in the same application domain. 通常,将来的版本可能会破坏兼容性。In general, future versions can break compatibility. 但是,如果进行了重大更改,则不会修改旧版本,也不会与新版本共存。However, when breaking changes are made, the old version is not modified but exists alongside the new version. 并行执行是在进行重大更改时使现有的客户端正常运行所需的方法。Side-by-side execution is the expected way to make existing clients work when breaking changes are made. 有关详细信息,请参阅本主题后面的并行兼容性部分。For more information, see the Side-by-Side Compatibility section later in this topic.

  • 稳定的版本到版本的兼容性ComponentGuaranteesOptions.Stable()。Stable version-to-version compatibility (ComponentGuaranteesOptions.Stable). 将来的版本不应中断客户端,也不应执行并行的执行。Future versions should not break the client, and side-by-side execution should not be needed. 但是,如果客户端无意中中断,则可以使用并行执行来解决该问题。However, if the client is inadvertently broken, it may be possible to use side-by-side execution to fix the problem. 有关详细信息,请参阅稳定兼容性部分。For more information, see the Stable Compatibility section.

  • 交换版本到版本的兼容性(ComponentGuaranteesOptions.Exchange)。Exchange version-to-version compatibility (ComponentGuaranteesOptions.Exchange). 特别要注意的是确保将来的版本不会中断客户端。Extraordinary care is taken to ensure that future versions will not break the client. 客户端仅应在用于与其他相互独立部署的程序集通信的接口的签名中使用这些类型。The client should use only these types in the signature of interfaces that are used for communication with other assemblies that are deployed independently of one another. 此类类型仅应有一个版本出现在给定的应用程序域中,这意味着,如果客户端中断,并行执行将无法修复兼容性问题。Only one version of these types is expected to be in a given application domain, which means that if a client breaks, side-by-side execution cannot fix the compatibility problem. 有关详细信息,请参阅Exchange 类型兼容性部分。For more information, see the Exchange Type Compatibility section.

以下部分更详细地讨论了每个保证级别。The following sections discuss each level of guarantee in greater detail.

无兼容性No Compatibility

将组件标记为ComponentGuaranteesOptions.None表示提供程序不保证兼容性。Marking a component as ComponentGuaranteesOptions.None indicates that the provider makes no guarantees about compatibility. 客户端应避免对公开的接口采用任何依赖项。Clients should avoid taking any dependencies on the exposed interfaces. 此级别的兼容性适用于实验性或公开的类型,但仅适用于始终更新的组件。This level of compatibility is useful for types that are experimental or that are publicly exposed but are intended only for components that are always updated at the same time. None显式指示外部组件不应使用此组件。None explicitly indicates that this component should not be used by external components.

并行兼容性Side-by-Side Compatibility

将组件标记为ComponentGuaranteesOptions.SideBySide指示在将程序集的多个版本加载到同一个应用程序域中时,组件已经过测试。Marking a component as ComponentGuaranteesOptions.SideBySide indicates that the component has been tested to work when more than one version of the assembly is loaded into the same application domain. 只要对版本号较高的程序集进行了重大更改,就可以使用这些更改。Breaking changes are allowed as long as they are made to the assembly that has the greater version number. 绑定到旧版本的程序集的组件应继续绑定到旧版本,其他组件可以绑定到新版本。Components that are bound to an old version of the assembly are expected to continue to bind to the old version, and other components can bind to the new version. 还可以SideBySide通过破坏性修改旧版本来更新声明为的组件。It is also possible to update a component that is declared to be SideBySide by destructively modifying the old version.

稳定兼容Stable Compatibility

将类型标记为ComponentGuaranteesOptions.Stable指示该类型应在不同版本之间保持稳定。Marking a type as ComponentGuaranteesOptions.Stable indicates that the type should remain stable across versions. 不过,也可以在同一应用程序域中存在稳定类型的并行版本。However, it may also be possible for side-by-side versions of a stable type to exist in the same application domain.

稳定类型维护较高的二进制兼容性栏。Stable types maintain a high binary compatibility bar. 因此,提供程序应避免对稳定类型进行重大更改。Because of this, providers should avoid making breaking changes to stable types. 以下类型的更改是可接受的:The following kinds of changes are acceptable:

  • 将私有实例字段添加到类型或从类型中删除字段,前提是这不会破坏序列化格式。Adding private instance fields to, or removing fields from, a type, as long as this does not break the serialization format.

  • 将不可序列化的类型更改为可序列化的类型。Changing a non-serializable type to a serializable type. (但是,不可序列化的类型不能更改为不可序列化的类型。)(However, a serializable type cannot be changed to a non-serializable type.)

  • 引发方法中新的、更多的派生异常。Throwing new, more derived exceptions from a method.

  • 提高方法的性能。Improving the performance of a method.

  • 更改返回值的范围,前提是更改不会对大多数客户端产生不利影响。Changing the range of return values, as long as the change does not adversely affect the majority of clients.

  • 解决严重错误,前提是业务理由很高,而受到负面影响的客户端的数量较低。Fixing serious bugs, if the business justification is high and the number of adversely affected clients is low.

由于稳定组件的新版本不会中断现有客户端,因此通常只需要一个应用程序域中的稳定组件版本。Because new versions of stable components are not expected to break existing clients, generally only one version of a stable component is needed in an application domain. 但这并不是必需的,因为不会将稳定类型用作所有组件都同意的已知交换类型。However, this is not a requirement, because stable types are not used as well-known exchange types that all components agree upon. 因此,如果稳定组件的新版本无意中中断了某些组件,并且其他组件需要新版本,则可以通过加载旧组件和新组件来解决此问题。Therefore, if a new version of a stable component does inadvertently break some component, and if other components need the new version, it may be possible to fix the problem by loading both the old and new component.

Stable提供比None更强的版本兼容性保证。Stable provides a stronger version compatibility guarantee than None. 它是多版本组件的常见默认值。It is a common default for multi-version components.

Stable可以与结合使用SideBySide,这表明,组件不会中断兼容性,但在给定的应用程序域中加载多个版本时,会对其进行测试。Stable can be combined with SideBySide, which states that the component will not break compatibility but is tested to work when more than one version is loaded in a given application domain.

将类型或方法标记为Stable后,可以将其升级到。 ExchangeAfter a type or method is marked as Stable, it can be upgraded to Exchange. 但是,不能将它降级None到。However, it cannot be downgraded to None.

交换类型兼容性Exchange Type Compatibility

将类型标记为ComponentGuaranteesOptions.Exchange提供更强的版本兼容性Stable保证,并且应应用于所有类型的最稳定。Marking a type as ComponentGuaranteesOptions.Exchange provides a stronger version compatibility guarantee than Stable, and should be applied to the most stable of all types. 这些类型旨在用于跨所有组件边界(在一个进程中的任意版本的 CLR 或任意版本的组件或应用程序)和空间(在一个进程中跨进程、跨 CLR)之间独立生成的组件之间进行交换。一个 CLR 中的跨应用程序域)。These types are intended to be used for interchange between independently built components across all component boundaries in both time (any version of the CLR or any version of a component or application) and space (cross-process, cross-CLR in one process, cross-application domain in one CLR). 如果对 exchange 类型进行了重大更改,则无法通过加载类型的多个版本来修复此问题。If a breaking change is made to an exchange type, it is impossible to fix the issue by loading multiple versions of the type.

仅当问题非常严重(如严重的安全问题)或破损的概率非常低时(即,如果该行为已经以代码无法完全依赖的方式断开),才应更改 Exchange 类型。Exchange types should be changed only when a problem is very serious (such as a severe security issue) or the probability of breakage is very low (that is, if the behavior was already broken in a random way that code could not have conceivably taken a dependency on). 可以对 exchange 类型进行以下类型的更改:You can make the following kinds of changes to an exchange type:

  • 添加新接口定义的继承。Add inheritance of new interface definitions.

  • 添加新的私有方法,该方法实现新继承的接口定义的方法。Add new private methods that implement the methods of newly inherited interface definitions.

  • 添加新的静态字段。Add new static fields.

  • 添加新的静态方法。Add new static methods.

  • 添加新的非虚拟实例方法。Add new non-virtual instance methods.

以下内容被视为重大更改,不允许用于基元类型:The following are considered breaking changes and are not allowed for primitive types:

  • 更改序列化格式。Changing serialization formats. 需要版本容错序列化。Version-tolerant serialization is required.

  • 添加或删除私有实例字段。Adding or removing private instance fields. 这会改变类型的序列化格式,并打破使用反射的客户端代码。This risks changing the serialization format of the type and breaking client code that uses reflection.

  • 更改类型的 serializability。Changing the serializability of a type. 不可序列化的类型可能无法进行序列化,反之亦然。A non-serializable type may not be made serializable, and vice versa.

  • 引发方法中的不同异常。Throwing different exceptions from a method.

  • 更改方法的返回值的范围,除非成员定义引发了这种可能性,并且清楚地指出了客户端应如何处理未知值。Changing the range of a method's return values, unless the member definition raises this possibility and clearly indicates how clients should handle unknown values.

  • 修复大多数 bug。Fixing most bugs. 该类型的使用者将依赖于现有行为。Consumers of the type will rely on the existing behavior.

在将组件、类型或成员标记Exchange为保证后,不能将其更改Stable为或NoneAfter a component, type, or member is marked with the Exchange guarantee, it cannot be changed to either Stable or None.

通常情况下,exchange 类型是基本类型(如Int32 String在 .NET Framework 中) IList<T>和接口(如、 IEnumerable<T>IComparable<T>),通常用于公共接口。Typically, exchange types are the basic types (such as Int32 and String in the .NET Framework) and interfaces (such as IList<T>, IEnumerable<T>, and IComparable<T>) that are commonly used in public interfaces.

Exchange 类型可能公开仅限也标记Exchange为兼容性的其他类型。Exchange types may publicly expose only other types that are also marked with Exchange compatibility. 此外,exchange 类型不能取决于易于更改的 Windows Api 的行为。In addition, exchange types cannot depend on the behavior of Windows APIs that are prone to change.

组件保证:摘要Component Guarantees: A Summary

下表指示组件特性和用法如何影响其兼容性保证。The following table indicates how a component's characteristics and usage affect its compatibility guarantee.

组件特征Component characteristics ExchangeExchange StableStable 并行Side-by-Side NoneNone
可用于独立于版本的组件之间的接口。Can be used in interfaces between components that version independently. YY NN NN NN
独立于版本的程序集可以使用(私有)。Can be used (privately) by an assembly that versions independently. YY YY YY NN
单个应用程序域中可以有多个版本。Can have multiple versions in a single application domain. NN YY YY YY
可以进行重大更改Can make breaking changes NN NN YY YY
经过测试,可将程序集的多个版本组合在一起。Tested to make certain multiple versions of the assembly can be loaded together. NN NN YY NN
可以就地进行重大更改。Can make breaking changes in place. NN NN NN YY
可以进行非常安全的非重大服务更改。Can make very safe non-breaking servicing changes in place. YY YY YY YY

应用属性Applying the Attribute

您可以将应用ComponentGuaranteesAttribute于程序集、类型或类型成员。You can apply the ComponentGuaranteesAttribute to an assembly, a type, or a type member. 其应用程序是分层的。Its application is hierarchical. 也就是说,默认情况下,由Guarantees程序集级别的特性的属性定义的保证将定义程序集中的所有类型以及这些类型中的所有成员的保证。That is, by default, the guarantee defined by the Guarantees property of the attribute at the assembly level defines the guarantee of all types in the assembly and all members in those types. 同样,如果保证应用于类型,则默认情况下,它也适用于类型的每个成员。Similarly, if the guarantee is applied to the type, by default it also applies to each member of the type.

通过将应用ComponentGuaranteesAttribute于单个类型和类型成员,可以重写此继承保证。This inherited guarantee can be overridden by applying the ComponentGuaranteesAttribute to individual types and type members. 不过,保证重写默认值只能削弱保证;它们不能强化。However, guarantees that override the default can only weaken the guarantee; they cannot strengthen it. 例如,如果程序集标记None为保证,则其类型和成员没有兼容性保证,并且应用于程序集中的类型或成员的任何其他保证将被忽略。For example, if an assembly is marked with the None guarantee, its types and members have no compatibility guarantee, and any other guarantee that is applied to types or members in the assembly is ignored.

测试保证Testing the Guarantee

属性返回ComponentGuaranteesOptions枚举的一个成员,该成员用FlagsAttribute特性标记。 GuaranteesThe Guarantees property returns a member of the ComponentGuaranteesOptions enumeration, which is marked with the FlagsAttribute attribute. 这意味着你应通过屏蔽可能未知标志来测试你感兴趣的标志。This means that you should test for the flag that you are interested in by masking away potentially unknown flags. 例如,下面的示例测试某个类型是否被标记为StableFor example, the following example tests whether a type is marked as 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

下面的示例测试某一类型是否标记为StableExchangeThe following example tests whether a type is marked as Stable or 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为的可以(即Stable ,不是也Exchange不是)。The following example tests wither a type is marked as None (that is, neither Stable nor 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      

构造函数

ComponentGuaranteesAttribute(ComponentGuaranteesOptions)

使用一个指示某个库、类型或成员保证的跨多个版本的兼容性级别的值初始化 ComponentGuaranteesAttribute 类的新实例。Initializes a new instance of the ComponentGuaranteesAttribute class with a value that indicates a library, type, or member's guaranteed level of compatibility across multiple versions.

属性

Guarantees

获取一个值,该值指示保证的跨多个版本的库、类型或类型成员的兼容性级别。Gets a value that indicates the guaranteed level of compatibility of a library, type, or type member that spans multiple versions.

TypeId

在派生类中实现时,获取此 Attribute 的唯一标识符。When implemented in a derived class, gets a unique identifier for this Attribute.

(继承自 Attribute)

方法

Equals(Object)

返回一个值,该值指示此实例是否与指定的对象相等。Returns a value that indicates whether this instance is equal to a specified object.

(继承自 Attribute)
GetHashCode()

返回此实例的哈希代码。Returns the hash code for this instance.

(继承自 Attribute)
GetType()

获取当前实例的 TypeGets the Type of the current instance.

(继承自 Object)
IsDefaultAttribute()

在派生类中重写时,指示此实例的值是否是派生类的默认值。When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(继承自 Attribute)
Match(Object)

当在派生类中重写时,返回一个指示此实例是否等于指定对象的值。When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(继承自 Attribute)
MemberwiseClone()

创建当前 Object 的浅表副本。Creates a shallow copy of the current Object.

(继承自 Object)
ToString()

返回一个表示当前对象的 string。Returns a string that represents the current object.

(继承自 Object)

显式界面实现

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

将一组名称映射为对应的一组调度标识符。Maps a set of names to a corresponding set of dispatch identifiers.

(继承自 Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

检索对象的类型信息,然后可以使用该信息获取接口的类型信息。Retrieves the type information for an object, which can be used to get the type information for an interface.

(继承自 Attribute)
_Attribute.GetTypeInfoCount(UInt32)

检索对象提供的类型信息接口的数量(0 或 1)。Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(继承自 Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

提供对某一对象公开的属性和方法的访问。Provides access to properties and methods exposed by an object.

(继承自 Attribute)

适用于

另请参阅