Este artículo se tradujo automáticamente. Para ver el artículo en inglés, active la casilla Inglés. Además, puede mostrar el texto en inglés en una ventana emergente si mueve el puntero del mouse sobre el texto.
Traducción
Inglés

Clase ComponentGuaranteesAttribute

 

Publicado: octubre de 2016

Define la garantía de compatibilidad de un componente, tipo o miembro de tipo que puede abarcar varias versiones.

Espacio de nombres:   System.Runtime.Versioning
Ensamblado:  mscorlib (en mscorlib.dll)

System.Object
  System.Attribute
    System.Runtime.Versioning.ComponentGuaranteesAttribute

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

NombreDescripción
System_CAPS_pubmethodComponentGuaranteesAttribute(ComponentGuaranteesOptions)

Inicializa una nueva instancia de la ComponentGuaranteesAttribute clase con un valor que indica una biblioteca, un tipo o un del miembro nivel garantizado de compatibilidad entre varias versiones.

NombreDescripción
System_CAPS_pubpropertyGuarantees

Obtiene un valor que indica el nivel de compatibilidad de una biblioteca, un tipo o un miembro que abarca varias versiones garantizado.

System_CAPS_pubpropertyTypeId

Cuando se implementa en una clase derivada, obtiene un identificador único para este Attribute.(Heredado de Attribute).

NombreDescripción
System_CAPS_pubmethodEquals(Object)

Esta API admite la infraestructura producto y no está diseñada para usarse directamente desde el código. Devuelve un valor que indica si esta instancia equivale al objeto especificado. (Heredado de Attribute).

System_CAPS_pubmethodGetHashCode()

Devuelve el código hash de esta instancia.(Heredado de Attribute).

System_CAPS_pubmethodGetType()

Obtiene el Type de la instancia actual.(Heredado de Object).

System_CAPS_pubmethodIsDefaultAttribute()

Si se reemplaza en una clase derivada, indica si el valor de esta instancia es el valor predeterminado de la clase derivada.(Heredado de Attribute).

System_CAPS_pubmethodMatch(Object)

Cuando se invalida en una clase derivada, devuelve un valor que indica si esta instancia es igual al objeto especificado. (Heredado de Attribute).

System_CAPS_pubmethodToString()

Devuelve una cadena que representa al objeto actual. (Heredado de Object).

NombreDescripción
System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

Asigna un conjunto de nombres a un conjunto correspondiente de identificadores de envío.(Heredado de Attribute).

System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Obtiene la información del tipo de un objeto, que puede utilizarse para obtener la información del tipo de una interfaz. (Heredado de Attribute).

System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.GetTypeInfoCount(UInt32)

Recupera el número de interfaces de tipo de información que suministra un objeto (0 ó 1)

(Heredado de Attribute).

System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Proporciona acceso a las propiedades y los métodos expuestos por un objeto.(Heredado de Attribute).

El ComponentGuaranteesAttribute lo utilizan los desarrolladores de componentes y bibliotecas de clases para indicar el nivel de compatibilidad que los consumidores de sus bibliotecas pueden esperar en varias versiones. Indica el nivel de garantía que una versión futura de la biblioteca o componente no interrumpirá a un cliente existente. Los clientes pueden utilizar entonces la ComponentGuaranteesAttribute como ayuda para diseñar sus propias interfaces para asegurarse la estabilidad de versiones.

System_CAPS_noteNota

Common language runtime (CLR) no utiliza este atributo en modo alguno. Su valor se encuentra en la documentación formal de la intención del autor del componente. Herramientas de tiempo de compilación también pueden usar estas declaraciones para detectar errores en tiempo de compilación que lo contrario interrumpirían la garantía declarada.

El ComponentGuaranteesAttribute admite los siguientes niveles de compatibilidad, que están representados por los miembros de la ComponentGuaranteesOptions (enumeración):

  • No hay compatibilidad versión a otra (ComponentGuaranteesOptions.None). El cliente puede esperar que las futuras versiones interrumpirán al cliente existente. Para obtener más información, consulte el sin compatibilidad más adelante en este tema.

  • Compatibilidad de versión a versión en paralelo (ComponentGuaranteesOptions.SideBySide). El componente se ha probado para funcionar cuando se cargue más de una versión del ensamblado en el mismo dominio de aplicación. En general, las versiones futuras pueden interrumpir la compatibilidad. Sin embargo, cuando se realizan cambios importantes, la versión anterior no se modifica, pero existe junto con la nueva versión. Ejecución en paralelo es la manera esperada para que los clientes existentes funcionen cuando se realizan cambios importantes. Para obtener más información, consulte el compatibilidad Side-by-Side más adelante en este tema.

  • Estable compatibilidad versión a versión (ComponentGuaranteesOptions.Stable). Las versiones futuras no deben interrumpir al cliente y no debería ser necesario ejecución en paralelo. Sin embargo, si el cliente se interrumpe accidentalmente, es posible usar la ejecución en paralelo para corregir el problema. Para obtener más información, consulte el compatibilidad estable sección.

  • Compatibilidad de versión a versión de Exchange (ComponentGuaranteesOptions.Exchange). Extraordinaria cuidado para asegurarse de que las versiones futuras no interrumpan al cliente. El cliente debería utilizar solo estos tipos en la firma de interfaces que se usan para la comunicación con otros ensamblados que se implementan de forma independiente. Solo una versión de estos tipos se esperaba que estuviera en un dominio de aplicación determinado, lo que significa que si se interrumpe la ejecución de un cliente, la ejecución en paralelo no puede solucionar el problema de compatibilidad. Para obtener más información, consulte el compatibilidad de tipo de intercambio sección.

Las secciones siguientes tratan cada nivel de garantía con mayor detalle.

Marcar un componente como ComponentGuaranteesOptions.None indica que el proveedor no ofrece ninguna garantía sobre la compatibilidad. Los clientes deberían evitar la toma de dependencias en las interfaces expuestas. Este nivel de compatibilidad es útil para los tipos que son experimentales o se exponen públicamente pero están pensados sólo para componentes que siempre se actualizan al mismo tiempo. None indica explícitamente que este componente no debe usarse por componentes externos.

Marcar un componente como ComponentGuaranteesOptions.SideBySide indica que el componente se ha probado para funcionar cuando se cargue más de una versión del ensamblado en el mismo dominio de aplicación. Cambios importantes se permiten siempre que se realizan en el ensamblado que tiene el mayor número de versión. Se espera que los componentes que están enlazados a una versión anterior del ensamblado continúen enlazados a la versión anterior y otros componentes pueden enlazarse a la nueva versión. También es posible actualizar un componente que se declara como SideBySide modificando la versión anterior de destruir datos.

Marcar un tipo como ComponentGuaranteesOptions.Stable indica que el tipo debe permanecer estable entre versiones. Sin embargo, también es posible que las versiones en paralelo de un tipo estable existan en el mismo dominio de aplicación.

Los tipos estables mantienen una barra de compatibilidad binaria alta. Por este motivo, los proveedores deberían evitar realizar cambios importantes en tipos estables. Los siguientes tipos de cambios son aceptables:

  • Agregar campos de instancia privados a o quitar campos de un tipo, siempre y cuando no se interrumpe el formato de serialización.

  • Cambiar un tipo no serializable a un tipo serializable. (Sin embargo, un tipo serializable no se puede cambiar a un tipo no serializable.)

  • Generar nuevas, más las excepciones derivadas de un método.

  • Mejorar el rendimiento de un método.

  • Cambiar el intervalo de valores devueltos, siempre que el cambio no afecta negativamente a la mayoría de los clientes.

  • Corregir los errores graves, si la justificación comercial es alta y el número de clientes adversamente afectado es bajo.

Porque no se esperan que las nuevas versiones de componentes estables interrumpan los clientes existentes, generalmente solo una versión de un componente estable se necesita en un dominio de aplicación. Sin embargo, esto no es un requisito, porque los tipos estables no se usan como tipos de intercambio conocidos que todos los componentes están de acuerdo. Por lo tanto, si una nueva versión de un componente estable interrumpir accidentalmente algún componente, y si otros componentes necesitan la nueva versión, es posible corregir el problema cargando el componente antiguo y nuevo.

StableProporciona una garantía de compatibilidad de versión más fuerte que None. Es un predeterminado común para los componentes de varias versiones.

Stable se puede combinar con SideBySide, que indica que el componente no interrumpirá la compatibilidad pero se prueba para que funcione cuando más de una versión se carga en un dominio de aplicación determinado.

Después de un tipo o método está marcado como Stable, se puede actualizar a Exchange. Sin embargo, no se puede degradar a None.

Marcar un tipo como ComponentGuaranteesOptions.Exchange proporciona una garantía de compatibilidad de versión más fuerte que Stable, y se debe aplicar a todos los tipos más estable. Estos tipos están diseñados para utilizarse en el intercambio entre los componentes compilados de forma independiente en todos los límites de componente tanto tiempo (cualquier versión de CLR) o cualquier versión de una aplicación o componente y espacio (entre procesos, entre CLR en un proceso, dominio entre aplicaciones en un CLR). Si se realiza un cambio importante para un tipo de intercambio, es imposible corregir el problema cargando varias versiones del tipo.

Tipos de intercambio deben cambiarse únicamente cuando un problema es muy grave (por ejemplo, un problema de seguridad grave) o la probabilidad de interrupción de interbloqueos es muy baja (es decir, si ya se ha roto el comportamiento de forma aleatoria que código podría no es posible que tengan una dependencia en). Puede realizar los siguientes tipos de cambios en un tipo de intercambio:

  • Agregar herencia de nuevas definiciones de interfaz.

  • Agregar nuevos métodos privados que implementan los métodos de definiciones de interfaz recientemente heredadas.

  • Agregar nuevos campos estáticos.

  • Agregar nuevos métodos estáticos.

  • Agregar nuevos métodos de instancia no virtuales.

Los siguientes se consideran cambios problemáticos y no se permiten para los tipos primitivos:

  • Cambiar los formatos de serialización. Se requiere la serialización tolerante a versiones.

  • Agregar o quitar campos de instancia privados. Esto corre el riesgo de cambiar el formato de serialización del tipo e interrupción de código de cliente que usa la reflexión.

  • Cambiar la serialización de un tipo. No se puede hacer serializable, un tipo no serializable y viceversa.

  • Generar excepciones diferentes de un método.

  • Cambiar el intervalo de valores devueltos de un método, a menos que la definición de miembro provoque esta posibilidad y claramente indica cómo los clientes deben controlar valores desconocidos.

  • Corregir la mayoría de los errores. Los consumidores del tipo se basarán en el comportamiento existente.

Después de un componente, tipo o miembro se marca con el Exchange garantiza que no se puede cambiar como Stable o None.

Normalmente, los tipos de intercambio son los tipos básicos (como Int32 y String en .NET Framework) e interfaces (como IList<T>, IEnumerable<T>, y IComparable<T>) que se utilizan normalmente en interfaces públicas.

Tipos de intercambio pueden exponer públicamente sólo otros tipos que también están marcados con Exchange compatibilidad. Además, los tipos de intercambio no pueden depender el comportamiento de las API de Windows que son susceptibles de cambio.

La tabla siguiente indica cómo afectan las características y el uso de un componente a su garantía de compatibilidad.

Características de componentes

Exchange

Stable

Side-by-Side

NONE

Se pueden utilizar en las interfaces entre los componentes de esa versión independientemente.

Y

N

N

N

Se puede utilizar (privada) por un ensamblado que las versiones independientemente.

Y

Y

Y

N

Puede tener varias versiones en un único dominio de aplicación.

N

Y

Y

Y

Puede hacer cambios importantes

N

N

Y

Y

Probar para asegurarse de que se pueden cargar varias versiones del ensamblado juntos.

N

N

Y

N

Puede hacer cambios importantes en su lugar.

N

N

N

Y

Puede hacer muy seguro no importantes cambios en lugar de servicio.

Y

Y

Y

Y

Puede aplicar el ComponentGuaranteesAttribute a un ensamblado, un tipo o un miembro de tipo. Su aplicación es jerárquica. Es decir, de forma predeterminada, la garantía definida por el Guarantees 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. De forma similar, si la garantía se aplica al tipo, de forma predeterminada también se aplica a cada miembro del tipo.

Esta garantía heredada puede invalidarse aplicando la ComponentGuaranteesAttribute para los tipos individuales y miembros de tipo. Sin embargo, garantiza que se invalide el valor predeterminado sólo puede debilitar la garantía; no pueden reforzarlo. Por ejemplo, si un ensamblado está marcado con el None garantizar, sus tipos y miembros no tienen ninguna garantía de compatibilidad y se omite cualquier otra garantía que se aplica a tipos o miembros en el ensamblado.

El Guarantees propiedad devuelve un miembro de la ComponentGuaranteesOptions enumeración, que se marca con el FlagsAttribute atributo. Esto significa que debe comprobar el indicador que están interesados en enmascarando marcas potencialmente desconocidas. Por ejemplo, el siguiente ejemplo se comprueba si un tipo se marca como Stable.

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee);

En el ejemplo siguiente se comprueba si un tipo se marca como Stable o 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);

El siguiente ejemplo se prueba si un tipo se marca como None (es decir, ni Stable ni 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);

.NET Framework
Disponible desde 4.0
Silverlight
Disponible desde 4.0

Cualquier miembro ( Compartido en Visual Basic) estático público de este tipo es seguro para subprocesos. No se garantiza que los miembros de instancia sean seguros para subprocesos.

Volver al principio
Mostrar: