System.Runtime.Versioning.ComponentGuaranteesAttribute Class

Defines the compatibility guarantee of a component, type, or type member that may span multiple versions.

See Also: ComponentGuaranteesAttribute Members

Syntax

[System.AttributeUsage(System.AttributeTargets.Assembly | System.AttributeTargets.Module | System.AttributeTargets.Class | System.AttributeTargets.Struct | System.AttributeTargets.Enum | System.AttributeTargets.Constructor | System.AttributeTargets.Method | System.AttributeTargets.Property | System.AttributeTargets.Event | System.AttributeTargets.Interface | System.AttributeTargets.Delegate | System.AttributeTargets.All, AllowMultiple=false, Inherited=false)]
public sealed class ComponentGuaranteesAttribute : Attribute

Remarks

The System.Runtime.Versioning.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. Clients can then use the System.Runtime.Versioning.ComponentGuaranteesAttribute as an aid in designing their own interfaces to ensure stability across versions.

Note:

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

The System.Runtime.Versioning.ComponentGuaranteesAttribute supports the following levels of compatibility, which are represented by members of the System.Runtime.Versioning.ComponentGuaranteesOptions enumeration:

The following sections discuss each level of guarantee in greater detail.

No Compatibility

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. ComponentGuaranteesOptions.None explicitly indicates that this component should not be used by external components.

Side-by-Side Compatibility

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. It is also possible to update a component that is declared to be ComponentGuaranteesOptions.SideBySide by destructively modifying the old version.

Stable Compatibility

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:

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.

ComponentGuaranteesOptions.Stable provides a stronger version compatibility guarantee than ComponentGuaranteesOptions.None. It is a common default for multi-version components.

ComponentGuaranteesOptions.Stable can be combined with ComponentGuaranteesOptions.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.

After a type or method is marked as ComponentGuaranteesOptions.Stable, it can be upgraded to ComponentGuaranteesOptions.Exchange. However, it cannot be downgraded to ComponentGuaranteesOptions.None.

Exchange Type Compatibility

Marking a type as ComponentGuaranteesOptions.Exchange provides a stronger version compatibility guarantee than ComponentGuaranteesOptions.Stable, and should be applied to the most stable of all types. 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). 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 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). You can make the following kinds of changes to an exchange type:

The following are considered breaking changes and are not allowed for primitive types:

After a component, type, or member is marked with the ComponentGuaranteesOptions.Exchange guarantee, it cannot be changed to either ComponentGuaranteesOptions.Stable or ComponentGuaranteesOptions.None.

Typically, exchange types are the basic types (such as int and string in the .NET Framework) and interfaces (such as IList`1, IEnumerable`1, and IComparable`1) that are commonly used in public interfaces.

Exchange types may publicly expose only other types that are also marked with ComponentGuaranteesOptions.Exchange compatibility. 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.

Can be used in interfaces between components that version independently.

Y

N

N

N

Can be used (privately) by an assembly that versions independently.

Y

Y

Y

N

Can have multiple versions in a single application domain.

N

Y

Y

Y

Can make breaking changes

N

N

Y

Y

Tested to make certain multiple versions of the assembly can be loaded together.

N

N

Y

N

Can make breaking changes in place.

N

N

N

Y

Can make very safe non-breaking servicing changes in place.

Y

Y

Y

Y

Applying the Attribute

You can apply the System.Runtime.Versioning.ComponentGuaranteesAttribute to an assembly, a type, or a type member. Its application is hierarchical. That is, by default, the guarantee defined by the ComponentGuaranteesAttribute.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.

This inherited guarantee can be overridden by applying the System.Runtime.Versioning.ComponentGuaranteesAttribute to individual types and type members. However, guarantees that override the default can only weaken the guarantee; they cannot strengthen it. For example, if an assembly is marked with the ComponentGuaranteesOptions.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

The ComponentGuaranteesAttribute.Guarantees property returns a member of the System.Runtime.Versioning.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. For example, the following example tests whether a type is marked as ComponentGuaranteesOptions.Stable.

code reference: System.Runtime.Versioning.ComponentGuaranteesAttribute.Class#1

The following example tests whether a type is marked as ComponentGuaranteesOptions.Stable or ComponentGuaranteesOptions.Exchange.

code reference: System.Runtime.Versioning.ComponentGuaranteesAttribute.Class#2

The following example tests wither a type is marked as ComponentGuaranteesOptions.None (that is, neither ComponentGuaranteesOptions.Stable nor ComponentGuaranteesOptions.Exchange).

code reference: System.Runtime.Versioning.ComponentGuaranteesAttribute.Class#3

Requirements

Namespace: System.Runtime.Versioning
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 4.0.0.0