ComponentGuaranteesAttribute Clase

Definición

Define la garantía de la compatibilidad de un componente, tipo o miembro de tipo que puede abarcar varias versiones.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
Herencia
ComponentGuaranteesAttribute
Atributos

Comentarios

Los ComponentGuaranteesAttribute desarrolladores de componentes y bibliotecas de clases utilizan la clase para indicar el nivel de compatibilidad que los consumidores de sus bibliotecas pueden esperar en varias versiones.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. Indica el nivel de garantía de que una versión futura de la biblioteca o componente no interrumpirá a un cliente existente.It indicates the level of guarantee that a future version of the library or component will not break an existing client. Los clientes pueden usar como ComponentGuaranteesAttribute ayuda para diseñar sus propias interfaces con el fin de garantizar la estabilidad entre las versiones.Clients can then use the ComponentGuaranteesAttribute as an aid in designing their own interfaces to ensure stability across versions.

Nota

El Common Language Runtime (CLR) no usa este atributo de ninguna manera.The common language runtime (CLR) does not use this attribute in any way. Su valor se basa en documentar formalmente la intención del autor del componente.Its value lies in formally documenting the intent of the component author. Las herramientas de tiempo de compilación también pueden utilizar estas declaraciones para detectar errores en tiempo de compilación que, de otro modo, podrían romper la garantía declarada.Compile-time tools can also use these declarations to detect compile-time errors that would otherwise break the declared guarantee.

Niveles de compatibilidadLevels of Compatibility

Admite los siguientes niveles de compatibilidad, que están representados por miembros de ComponentGuaranteesOptions la enumeración: ComponentGuaranteesAttributeThe ComponentGuaranteesAttribute supports the following levels of compatibility, which are represented by members of the ComponentGuaranteesOptions enumeration:

  • No hay compatibilidad de versión a versión (ComponentGuaranteesOptions.None).No version-to-version compatibility (ComponentGuaranteesOptions.None). El cliente puede esperar que las versiones futuras interrumpan el cliente existente.The client can expect that future versions will break the existing client. Para obtener más información, vea la sección no compatibilidad más adelante en este tema.For more information, see the No Compatibility section later in this topic.

  • Compatibilidad de la versión a la versión en paralelo (ComponentGuaranteesOptions.SideBySide).Side-by-side version-to-version compatibility (ComponentGuaranteesOptions.SideBySide). El componente se ha probado para que funcione cuando se carga más de una versión del ensamblado en el mismo dominio de aplicación.The component has been tested to work when more than one version of the assembly is loaded in the same application domain. En general, las versiones futuras pueden interrumpir la compatibilidad.In general, future versions can break compatibility. Sin embargo, cuando se realizan cambios importantes, la versión anterior no se modifica, sino que se encuentra junto a la nueva versión.However, when breaking changes are made, the old version is not modified but exists alongside the new version. La ejecución en paralelo es la manera esperada de hacer que los clientes existentes funcionen cuando se realizan cambios importantes.Side-by-side execution is the expected way to make existing clients work when breaking changes are made. Para obtener más información, vea la sección compatibilidad en paralelo más adelante en este tema.For more information, see the Side-by-Side Compatibility section later in this topic.

  • Compatibilidad de versión a versión estable (ComponentGuaranteesOptions.Stable).Stable version-to-version compatibility (ComponentGuaranteesOptions.Stable). Las versiones futuras no deben interrumpir el cliente y no es necesario ejecutar en paralelo.Future versions should not break the client, and side-by-side execution should not be needed. Sin embargo, si el cliente se interrumpe involuntariamente, es posible que se pueda usar la ejecución en paralelo para solucionar el problema.However, if the client is inadvertently broken, it may be possible to use side-by-side execution to fix the problem. Para obtener más información, consulte la sección compatibilidad estable .For more information, see the Stable Compatibility section.

  • Compatibilidad de versión a versión de Exchange (ComponentGuaranteesOptions.Exchange).Exchange version-to-version compatibility (ComponentGuaranteesOptions.Exchange). Se debe tener especial cuidado para asegurarse de que las versiones futuras no interrumpan el cliente.Extraordinary care is taken to ensure that future versions will not break the client. El cliente solo debe usar estos tipos en la firma de interfaces que se usan para la comunicación con otros ensamblados que se implementan de forma independiente entre sí.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. Solo se espera que una versión de estos tipos esté en un dominio de aplicación determinado, lo que significa que si un cliente se interrumpe, la ejecución en paralelo no puede corregir el problema de compatibilidad.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. Para obtener más información, consulte la sección compatibilidad de tipos de Exchange .For more information, see the Exchange Type Compatibility section.

En las secciones siguientes se describe cada nivel de garantía con mayor detalle.The following sections discuss each level of guarantee in greater detail.

Sin compatibilidadNo Compatibility

Al marcar un componente ComponentGuaranteesOptions.None como, indica que el proveedor no garantiza la compatibilidad.Marking a component as ComponentGuaranteesOptions.None indicates that the provider makes no guarantees about compatibility. Los clientes deben evitar tener que tomar dependencias en las interfaces expuestas.Clients should avoid taking any dependencies on the exposed interfaces. Este nivel de compatibilidad es útil para los tipos que son experimentales o que se exponen públicamente, pero que solo están diseñados para componentes que se actualizan siempre al mismo tiempo.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. Noneindica explícitamente que este componente no debe ser utilizado por componentes externos.None explicitly indicates that this component should not be used by external components.

Compatibilidad en paraleloSide-by-Side Compatibility

Marcar un componente como ComponentGuaranteesOptions.SideBySide indica que el componente se ha probado para funcionar cuando se carga más de una versión del ensamblado en el mismo dominio de aplicación.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. Se permiten cambios importantes siempre que se realicen en el ensamblado que tenga el número de versión más alto.Breaking changes are allowed as long as they are made to the assembly that has the greater version number. Se espera que los componentes que están enlazados a una versión anterior del ensamblado sigan enlazando a la versión anterior y otros componentes puedan enlazarse a la nueva versión.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. También es posible actualizar un componente que se declara para SideBySide que modifique de forma destructiva la versión anterior.It is also possible to update a component that is declared to be SideBySide by destructively modifying the old version.

Compatibilidad estableStable Compatibility

Marcar un tipo como ComponentGuaranteesOptions.Stable indica que el tipo debe permanecer estable en todas las versiones.Marking a type as ComponentGuaranteesOptions.Stable indicates that the type should remain stable across versions. Sin embargo, también es posible que existan versiones en paralelo de un tipo estable en el mismo dominio de aplicación.However, it may also be possible for side-by-side versions of a stable type to exist in the same application domain.

Los tipos estables mantienen una barra de compatibilidad binaria alta.Stable types maintain a high binary compatibility bar. Por este motivo, los proveedores deben evitar realizar cambios importantes en los tipos estables.Because of this, providers should avoid making breaking changes to stable types. Se aceptan los siguientes tipos de cambios:The following kinds of changes are acceptable:

  • Agregar campos de instancia privados o quitar campos de un tipo, siempre y cuando esto no interrumpa el formato de serialización.Adding private instance fields to, or removing fields from, a type, as long as this does not break the serialization format.

  • Cambiar un tipo no serializable a un tipo serializable.Changing a non-serializable type to a serializable type. (Sin embargo, un tipo serializable no se puede cambiar a un tipo no serializable).(However, a serializable type cannot be changed to a non-serializable type.)

  • Producir nuevas excepciones más derivadas de un método.Throwing new, more derived exceptions from a method.

  • Mejorar el rendimiento de un método.Improving the performance of a method.

  • Cambiar el intervalo de valores devueltos, siempre que el cambio no afecte negativamente a la mayoría de los clientes.Changing the range of return values, as long as the change does not adversely affect the majority of clients.

  • Corrección de errores graves, si la justificación empresarial es alta y el número de clientes afectados negativamente es bajo.Fixing serious bugs, if the business justification is high and the number of adversely affected clients is low.

Dado que no se espera que las nuevas versiones de componentes estables interrumpan los clientes existentes, por lo general, solo se necesita una versión de un componente estable en un dominio de aplicación.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. Sin embargo, esto no es un requisito, porque los tipos estables no se usan como tipos de intercambio conocidos con los que todos los componentes están de acuerdo.However, this is not a requirement, because stable types are not used as well-known exchange types that all components agree upon. Por lo tanto, si una nueva versión de un componente estable interrumpe accidentalmente algún componente y otros componentes necesitan la nueva versión, es posible que se solucione el problema cargando el componente anterior y el nuevo.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.

Stableproporciona una garantía de compatibilidad de versiones más Nonesegura que.Stable provides a stronger version compatibility guarantee than None. Es un valor predeterminado común para los componentes de varias versiones.It is a common default for multi-version components.

Stablese puede combinar con SideBySide, que indica que el componente no interrumpirá la compatibilidad, pero se prueba para funcionar cuando se carga más de una versión en un dominio de aplicación determinado.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.

Una vez que un tipo o un método Stableestá marcado como, se puede actualizar a Exchange.After a type or method is marked as Stable, it can be upgraded to Exchange. Sin embargo, no se puede degradar Nonea.However, it cannot be downgraded to None.

Compatibilidad de tipos de ExchangeExchange Type Compatibility

Marcar un tipo como ComponentGuaranteesOptions.Exchange proporciona una garantía de compatibilidad de la versión Stablemás segura que, y debe aplicarse a todos los tipos más estables.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. Estos tipos están diseñados para usarse para el intercambio entre componentes compilados de forma independiente en todos los límites de componentes en el tiempo (cualquier versión de CLR o cualquier versión de un componente o aplicación) y espacio (entre procesos, entre CLR en un proceso, dominio entre aplicaciones en un 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). Si se realiza un cambio importante en un tipo de intercambio, es imposible corregir el problema cargando varias versiones del tipo.If a breaking change is made to an exchange type, it is impossible to fix the issue by loading multiple versions of the type.

Los tipos de intercambio deben cambiarse solo cuando un problema es muy grave (por ejemplo, un problema grave de seguridad) o la probabilidad de que la ruptura sea muy baja (es decir, si el comportamiento ya se ha interrumpido de manera aleatoria que el código no ha podido tomar una dependencia en).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). Puede realizar los siguientes tipos de cambios en un tipo de intercambio:You can make the following kinds of changes to an exchange type:

  • Agregue herencia de nuevas definiciones de interfaz.Add inheritance of new interface definitions.

  • Agregue nuevos métodos privados que implementen los métodos de definiciones de interfaz recién heredadas.Add new private methods that implement the methods of newly inherited interface definitions.

  • Agregar nuevos campos estáticos.Add new static fields.

  • Agregue nuevos métodos estáticos.Add new static methods.

  • Agregue nuevos métodos de instancia no virtuales.Add new non-virtual instance methods.

Los siguientes se consideran cambios importantes y no están permitidos para los tipos primitivos:The following are considered breaking changes and are not allowed for primitive types:

  • Cambiar formatos de serialización.Changing serialization formats. Se requiere la serialización tolerante a versiones.Version-tolerant serialization is required.

  • Agregar o quitar campos de instancia privados.Adding or removing private instance fields. Esto arriesga el cambio del formato de serialización del tipo y la interrupción del código de cliente que usa la reflexión.This risks changing the serialization format of the type and breaking client code that uses reflection.

  • Cambiar la serialización de un tipo.Changing the serializability of a type. Un tipo no serializable no se puede convertir en Serializable y viceversa.A non-serializable type may not be made serializable, and vice versa.

  • Producir diferentes excepciones de un método.Throwing different exceptions from a method.

  • Cambiar el intervalo de valores devueltos de un método, a menos que la definición de miembro provoque esta posibilidad e indique claramente cómo los clientes deben controlar los valores desconocidos.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.

  • Corregir la mayoría de los errores.Fixing most bugs. Los consumidores del tipo se basarán en el comportamiento existente.Consumers of the type will rely on the existing behavior.

Una vez que un componente, tipo o miembro está marcado con Exchange la garantía, no se puede cambiar Stable a o None.After a component, type, or member is marked with the Exchange guarantee, it cannot be changed to either Stable or None.

Normalmente, los tipos de intercambio son los tipos básicos ( Int32 como String y en el .NET Framework) IList<T>e interfaces (como, IEnumerable<T>y IComparable<T>) que se suelen usar en las interfaces públicas.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.

Los tipos de intercambio pueden exponer públicamente solo otros tipos que también Exchange están marcados con compatibilidad.Exchange types may publicly expose only other types that are also marked with Exchange compatibility. Además, los tipos de intercambio no pueden depender del comportamiento de las API de Windows que son propensos a cambios.In addition, exchange types cannot depend on the behavior of Windows APIs that are prone to change.

Garantías de componentes: Un resumenComponent Guarantees: A Summary

En la tabla siguiente se indica el modo en que las características y el uso de un componente afectan a su garantía de compatibilidad.The following table indicates how a component's characteristics and usage affect its compatibility guarantee.

Características del componenteComponent characteristics ExchangeExchange StableStable En paraleloSide-by-Side NingunaNone
Se puede usar en interfaces entre componentes que son independientes de la versión.Can be used in interfaces between components that version independently. YY NN NN NN
Un ensamblado que tiene versiones independientes puede utilizar (de forma privada).Can be used (privately) by an assembly that versions independently. YY YY YY NN
Puede tener varias versiones en un dominio de aplicación único.Can have multiple versions in a single application domain. NN YY YY YY
Puede realizar cambios importantesCan make breaking changes NN NN YY YY
Se ha probado para que se puedan cargar en conjunto varias versiones del ensamblado.Tested to make certain multiple versions of the assembly can be loaded together. NN NN YY NN
Puede realizar cambios importantes.Can make breaking changes in place. NN NN NN YY
Puede realizar cambios de servicio sin interrupción muy seguros.Can make very safe non-breaking servicing changes in place. YY YY YY YY

Aplicar el atributoApplying the Attribute

Puede aplicar ComponentGuaranteesAttribute a un ensamblado, un tipo o un miembro de tipo.You can apply the ComponentGuaranteesAttribute to an assembly, a type, or a type member. Su aplicación es jerárquica.Its application is hierarchical. Es decir, de forma predeterminada, la garantía definida por Guarantees la propiedad del atributo en el nivel de ensamblado define la garantía de todos los tipos en el ensamblado y todos los miembros de esos tipos.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. De forma similar, si se aplica la garantía al tipo, de forma predeterminada también se aplica a cada miembro del tipo.Similarly, if the guarantee is applied to the type, by default it also applies to each member of the type.

Esta garantía heredada se puede invalidar aplicando ComponentGuaranteesAttribute a tipos individuales y miembros de tipo.This inherited guarantee can be overridden by applying the ComponentGuaranteesAttribute to individual types and type members. Sin embargo, garantiza que la invalidación del valor predeterminado solo puede debilitar la garantía; no pueden reforzarlo.However, guarantees that override the default can only weaken the guarantee; they cannot strengthen it. Por ejemplo, si un ensamblado está marcado con None la garantía, sus tipos y miembros no tienen ninguna garantía de compatibilidad y se omite cualquier otra garantía que se aplique a los tipos o miembros del ensamblado.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.

Prueba de la garantíaTesting the Guarantee

La Guarantees propiedad devuelve un miembro de la ComponentGuaranteesOptions enumeración, que se marca con FlagsAttribute el atributo.The Guarantees property returns a member of the ComponentGuaranteesOptions enumeration, which is marked with the FlagsAttribute attribute. Esto significa que debe probar la marca que le interesa mediante la enmascaramiento de marcas potencialmente desconocidas.This means that you should test for the flag that you are interested in by masking away potentially unknown flags. Por ejemplo, en el ejemplo siguiente se prueba si un tipo está Stablemarcado como.For 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

En el ejemplo siguiente se comprueba si un tipo está Stable marcado Exchangecomo o.The 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

En el ejemplo siguiente se prueba pueden un tipo está None marcado como (es decir Stable , Exchangeni ni).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      

Constructores

ComponentGuaranteesAttribute(ComponentGuaranteesOptions)

Inicializa una nueva instancia de la clase ComponentGuaranteesAttribute con un valor que indica el nivel garantizado de compatibilidad entre varias versiones de una biblioteca, un tipo o un miembro.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.

Propiedades

Guarantees

Obtiene un valor que indica el nivel de compatibilidad garantizado de una biblioteca, tipo o miembro de tipo que abarca varias versiones.Gets a value that indicates the guaranteed level of compatibility of a library, type, or type member that spans multiple versions.

TypeId

Cuando se implementa en una clase derivada, obtiene un identificador único para este Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Heredado de Attribute)

Métodos

Equals(Object)

Devuelve un valor que indica si esta instancia es igual que un objeto especificado.Returns a value that indicates whether this instance is equal to a specified object.

(Heredado de Attribute)
GetHashCode()

Devuelve el código hash de esta instancia.Returns the hash code for this instance.

(Heredado de Attribute)
GetType()

Obtiene el Type de la instancia actual.Gets the Type of the current instance.

(Heredado de Object)
IsDefaultAttribute()

Si se reemplaza en una clase derivada, indica si el valor de esta instancia es el valor predeterminado de la clase derivada.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Heredado de Attribute)
Match(Object)

Cuando se invalida en una clase derivada, devuelve un valor que indica si esta instancia es igual a un objeto especificado.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Heredado de Attribute)
MemberwiseClone()

Crea una copia superficial del objeto Object actual.Creates a shallow copy of the current Object.

(Heredado de Object)
ToString()

Devuelve una cadena que representa el objeto actual.Returns a string that represents the current object.

(Heredado de Object)

Implementaciones de interfaz explícitas

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

Asigna un conjunto de nombres a un conjunto correspondiente de identificadores de envío.Maps a set of names to a corresponding set of dispatch identifiers.

(Heredado de Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Obtiene la información de tipos de un objeto, que puede utilizarse para obtener la información de tipos de una interfaz.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Heredado de Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Recupera el número de interfaces de información de tipo que proporciona un objeto (0 ó 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Heredado de Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Proporciona acceso a las propiedades y los métodos expuestos por un objeto.Provides access to properties and methods exposed by an object.

(Heredado de Attribute)

Se aplica a

Consulte también: