ComponentGuaranteesAttribute Class

Definition

Definisce la garanzia di compatibilità di un componente, di un tipo o di un membro di tipo che può estendersi a più versioni.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
Inheritance
ComponentGuaranteesAttribute
Attributes

Remarks

Il ComponentGuaranteesAttribute viene usato dagli sviluppatori di componenti e librerie di classi per indicare il livello di compatibilità che i consumer delle librerie possono aspettarsi tra più versioni.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 il livello di garanzia che una versione futura della libreria o del componente non interromperà un client esistente.It indicates the level of guarantee that a future version of the library or component will not break an existing client. I client possono quindi utilizzare il ComponentGuaranteesAttribute come supporto per progettare interfacce personalizzate per garantire la stabilità tra le versioni.Clients can then use the ComponentGuaranteesAttribute as an aid in designing their own interfaces to ensure stability across versions.

Note

Il Common Language Runtime (CLR) non utilizza questo attributo in alcun modo.The common language runtime (CLR) does not use this attribute in any way. Il suo valore risiede nella documentazione formale dello scopo dell'autore del componente.Its value lies in formally documenting the intent of the component author. Gli strumenti in fase di compilazione possono inoltre utilizzare queste dichiarazioni per rilevare errori in fase di compilazione che altrimenti interrompono la garanzia dichiarata.Compile-time tools can also use these declarations to detect compile-time errors that would otherwise break the declared guarantee.

Livelli di compatibilitàLevels of Compatibility

Il ComponentGuaranteesAttribute supporta i livelli di compatibilità seguenti, rappresentati dai membri dell'enumerazione ComponentGuaranteesOptions:The ComponentGuaranteesAttribute supports the following levels of compatibility, which are represented by members of the ComponentGuaranteesOptions enumeration:

  • Nessuna compatibilità tra versioni e versioni (ComponentGuaranteesOptions.None).No version-to-version compatibility (ComponentGuaranteesOptions.None). Il client si aspetta che le versioni future interrompano il client esistente.The client can expect that future versions will break the existing client. Per ulteriori informazioni, vedere la sezione Nessuna compatibilità più avanti in questo argomento.For more information, see the No Compatibility section later in this topic.

  • Compatibilità tra versioni affiancate (ComponentGuaranteesOptions.SideBySide).Side-by-side version-to-version compatibility (ComponentGuaranteesOptions.SideBySide). Il componente è stato testato per funzionare quando più di una versione dell'assembly viene caricata nello stesso dominio applicazione.The component has been tested to work when more than one version of the assembly is loaded in the same application domain. In generale, le versioni future possono interrompere la compatibilità.In general, future versions can break compatibility. Tuttavia, quando vengono apportate modifiche di rilievo, la versione precedente non viene modificata ma esiste insieme alla nuova versione.However, when breaking changes are made, the old version is not modified but exists alongside the new version. L'esecuzione side-by-Side è il modo previsto per far funzionare i client esistenti quando vengono apportate modifiche di rilievo.Side-by-side execution is the expected way to make existing clients work when breaking changes are made. Per ulteriori informazioni, vedere la sezione relativa alla Compatibilità affiancata più avanti in questo argomento.For more information, see the Side-by-Side Compatibility section later in this topic.

  • Compatibilità stabile tra versioni e versioni (ComponentGuaranteesOptions.Stable).Stable version-to-version compatibility (ComponentGuaranteesOptions.Stable). Le versioni future non devono interrompere il client e l'esecuzione side-by-side non è necessaria.Future versions should not break the client, and side-by-side execution should not be needed. Tuttavia, se il client viene inavvertitamente danneggiato, potrebbe essere possibile utilizzare l'esecuzione side-by-side per risolvere il problema.However, if the client is inadvertently broken, it may be possible to use side-by-side execution to fix the problem. Per ulteriori informazioni, vedere la sezione Compatibilità stabile .For more information, see the Stable Compatibility section.

  • Compatibilità tra la versione e la versione di Exchange (ComponentGuaranteesOptions.Exchange).Exchange version-to-version compatibility (ComponentGuaranteesOptions.Exchange). Per garantire che le versioni future non interrompano il client, è necessario prestare particolare attenzione.Extraordinary care is taken to ensure that future versions will not break the client. Il client deve utilizzare solo questi tipi nella firma delle interfacce utilizzate per la comunicazione con altri assembly distribuiti indipendentemente l'uno dall'altro.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. Si prevede che una sola versione di questi tipi si trovi in un determinato dominio applicazione, il che significa che se un client si interrompe, l'esecuzione side-by-side non può risolvere il problema di compatibilità.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. Per ulteriori informazioni, vedere la sezione relativa alla compatibilità dei tipi di Exchange .For more information, see the Exchange Type Compatibility section.

Le sezioni seguenti illustrano ogni livello di garanzia in modo più dettagliato.The following sections discuss each level of guarantee in greater detail.

Nessuna compatibilitàNo Compatibility

Contrassegnare un componente come ComponentGuaranteesOptions.None indica che il provider non fornisce alcuna garanzia sulla compatibilità.Marking a component as ComponentGuaranteesOptions.None indicates that the provider makes no guarantees about compatibility. I client devono evitare di prendere dipendenze dalle interfacce esposte.Clients should avoid taking any dependencies on the exposed interfaces. Questo livello di compatibilità è utile per i tipi sperimentali o esposti pubblicamente, ma destinati solo a componenti che vengono sempre aggiornati nello stesso momento.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 indica in modo esplicito che il componente non deve essere utilizzato dai componenti esterni.None explicitly indicates that this component should not be used by external components.

Compatibilità side-by-sideSide-by-Side Compatibility

Contrassegnare un componente come ComponentGuaranteesOptions.SideBySide indica che il componente è stato testato per funzionare quando più di una versione dell'assembly viene caricata nello stesso dominio applicazione.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. Le modifiche di rilievo sono consentite a condizione che vengano apportate all'assembly con il numero di versione maggiore.Breaking changes are allowed as long as they are made to the assembly that has the greater version number. È previsto che i componenti associati a una versione precedente dell'assembly continuino a essere associati alla versione precedente e che altri componenti possano essere associati alla nuova versione.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. È anche possibile aggiornare un componente dichiarato come SideBySide modificando in modo distruttivo la versione precedente.It is also possible to update a component that is declared to be SideBySide by destructively modifying the old version.

Compatibilità stabileStable Compatibility

Contrassegnare un tipo come ComponentGuaranteesOptions.Stable indica che il tipo deve rimanere stabile tra le versioni.Marking a type as ComponentGuaranteesOptions.Stable indicates that the type should remain stable across versions. Tuttavia, potrebbe essere possibile che le versioni affiancate di un tipo stabile esistano nello stesso dominio applicazione.However, it may also be possible for side-by-side versions of a stable type to exist in the same application domain.

I tipi stabili mantengono una barra di compatibilità binaria elevata.Stable types maintain a high binary compatibility bar. Per questo motivo, i provider devono evitare di apportare modifiche di rilievo ai tipi stabili.Because of this, providers should avoid making breaking changes to stable types. Sono accettabili i tipi di modifiche seguenti:The following kinds of changes are acceptable:

  • Aggiunta di campi di istanza privati a, o rimozione di campi da un tipo, a condizione che non interrompa il formato di serializzazione.Adding private instance fields to, or removing fields from, a type, as long as this does not break the serialization format.

  • Modifica di un tipo non serializzabile in un tipo serializzabile.Changing a non-serializable type to a serializable type. Un tipo serializzabile, tuttavia, non può essere modificato in un tipo non serializzabile.(However, a serializable type cannot be changed to a non-serializable type.)

  • Generazione di nuove eccezioni derivate da un metodo.Throwing new, more derived exceptions from a method.

  • Miglioramento delle prestazioni di un metodo.Improving the performance of a method.

  • Modifica dell'intervallo di valori restituiti, purché la modifica non influisca negativamente sulla maggior parte dei client.Changing the range of return values, as long as the change does not adversely affect the majority of clients.

  • Correzione di bug gravi, se la motivazione aziendale è elevata e il numero di client con conseguenze negative è basso.Fixing serious bugs, if the business justification is high and the number of adversely affected clients is low.

Poiché non è previsto che le nuove versioni dei componenti stabili interrompano i client esistenti, in genere è necessaria una sola versione di un componente stabile in un dominio applicazione.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. Tuttavia, questo non è un requisito, perché i tipi stabili non vengono utilizzati come tipi di scambio noti su cui tutti i componenti sono concordati.However, this is not a requirement, because stable types are not used as well-known exchange types that all components agree upon. Se pertanto una nuova versione di un componente stabile interrompe inavvertitamente un componente e se altri componenti necessitano della nuova versione, potrebbe essere possibile risolvere il problema caricando il componente precedente e quello nuovo.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 offre una garanzia di compatibilità della versione più avanzata rispetto a None.Stable provides a stronger version compatibility guarantee than None. Si tratta di un'impostazione predefinita comune per i componenti multiversione.It is a common default for multi-version components.

Stable possono essere combinati con SideBySide, che indica che il componente non interrompe la compatibilità, ma viene testato per funzionare quando più di una versione viene caricata in un determinato dominio applicazione.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.

Quando un tipo o un metodo è contrassegnato come Stable, è possibile aggiornarlo Exchange.After a type or method is marked as Stable, it can be upgraded to Exchange. Tuttavia, non è possibile effettuare il downgrade a None.However, it cannot be downgraded to None.

Compatibilità tra tipi di ExchangeExchange Type Compatibility

Contrassegnare un tipo come ComponentGuaranteesOptions.Exchange fornisce una garanzia di compatibilità della versione più avanzata rispetto a Stablee deve essere applicata alla più stabile di tutti i tipi.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. Questi tipi sono destinati a essere utilizzati per l'interscambio tra i componenti compilati in modo indipendente in tutti i limiti dei componenti in entrambi i tempi (qualsiasi versione di CLR o qualsiasi versione di un componente o di un'applicazione) e lo spazio (cross-process, Cross-CLR in un processo, il dominio tra applicazioni in un solo 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). Se viene apportata una modifica di rilievo a un tipo di scambio, è Impossibile risolvere il problema caricando più versioni 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.

I tipi di scambio devono essere modificati solo quando un problema è molto grave, ad esempio un problema di sicurezza grave, oppure la probabilità di rottura è molto bassa, ovvero se il comportamento è già stato interrotto in modo casuale per cui il codice non è stato in grado di assumere una dipendenza.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). È possibile apportare i seguenti tipi di modifiche a un tipo di scambio:You can make the following kinds of changes to an exchange type:

  • Aggiungere l'ereditarietà delle nuove definizioni di interfaccia.Add inheritance of new interface definitions.

  • Aggiungere nuovi metodi privati che implementano i metodi delle definizioni di interfaccia appena ereditate.Add new private methods that implement the methods of newly inherited interface definitions.

  • Aggiungere nuovi campi statici.Add new static fields.

  • Aggiungere nuovi metodi statici.Add new static methods.

  • Aggiungere nuovi metodi di istanza non virtuali.Add new non-virtual instance methods.

Le seguenti sono considerate modifiche di rilievo e non sono consentite per i tipi primitivi:The following are considered breaking changes and are not allowed for primitive types:

  • Modifica di formati di serializzazione.Changing serialization formats. La serializzazione a tolleranza di versione è obbligatoria.Version-tolerant serialization is required.

  • Aggiunta o rimozione di campi di istanza privati.Adding or removing private instance fields. Questa operazione rischia di modificare il formato di serializzazione del tipo e di suddividere il codice client che usa la reflection.This risks changing the serialization format of the type and breaking client code that uses reflection.

  • Modifica della serializzabilità di un tipo.Changing the serializability of a type. Un tipo non serializzabile non può essere reso serializzabile e viceversa.A non-serializable type may not be made serializable, and vice versa.

  • Generazione di eccezioni diverse da un metodo.Throwing different exceptions from a method.

  • Modificando l'intervallo dei valori restituiti di un metodo, a meno che la definizione del membro non generi questa possibilità e indichi chiaramente in che modo i client devono gestire valori sconosciuti.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.

  • Correzione della maggior parte dei bug.Fixing most bugs. I consumer del tipo si basano sul comportamento esistente.Consumers of the type will rely on the existing behavior.

Dopo che un componente, un tipo o un membro è contrassegnato con la garanzia Exchange, non può essere modificato in Stable o None.After a component, type, or member is marked with the Exchange guarantee, it cannot be changed to either Stable or None.

In genere, i tipi di scambio sono i tipi di base (ad esempio Int32 e String nel .NET Framework) e le interfacce, ad esempio IList<T>, IEnumerable<T>e IComparable<T>, comunemente utilizzate nelle interfacce pubbliche.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.

I tipi di scambio possono esporre pubblicamente solo altri tipi contrassegnati anche con Exchange compatibilità.Exchange types may publicly expose only other types that are also marked with Exchange compatibility. Inoltre, i tipi di scambio non possono dipendere dal comportamento delle API Windows soggette a modifiche.In addition, exchange types cannot depend on the behavior of Windows APIs that are prone to change.

Garanzie per i componenti: RiepilogoComponent Guarantees: A Summary

La tabella seguente indica il modo in cui le caratteristiche e l'utilizzo di un componente influiscono sulla garanzia di compatibilità.The following table indicates how a component's characteristics and usage affect its compatibility guarantee.

Caratteristiche del componenteComponent characteristics ExchangeExchange StableStable Side-by-sideSide-by-Side nessunoNone
Può essere usato nelle interfacce tra i componenti indipendenti dalla versione.Can be used in interfaces between components that version independently. SY NN NN NN
Può essere usato (privatamente) da un assembly indipendente dalle versioni.Can be used (privately) by an assembly that versions independently. SY SY SY NN
Può avere più versioni in un singolo dominio applicazione.Can have multiple versions in a single application domain. NN SY SY SY
Può apportare modifiche di rilievoCan make breaking changes NN NN SY SY
Testato per fare in modo che alcune versioni dell'assembly possano essere caricate insieme.Tested to make certain multiple versions of the assembly can be loaded together. NN NN SY NN
Può apportare modifiche di rilievo.Can make breaking changes in place. NN NN NN SY
Consente di apportare modifiche molto sicure alla manutenzione senza interruzioni.Can make very safe non-breaking servicing changes in place. SY SY SY SY

Applicazione dell'attributoApplying the Attribute

È possibile applicare la ComponentGuaranteesAttribute a un assembly, un tipo o un membro del tipo.You can apply the ComponentGuaranteesAttribute to an assembly, a type, or a type member. L'applicazione è gerarchica.Its application is hierarchical. Per impostazione predefinita, la garanzia definita dalla proprietà Guarantees dell'attributo a livello di assembly definisce la garanzia di tutti i tipi nell'assembly e di tutti i membri di tali tipi.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. Analogamente, se la garanzia viene applicata al tipo, per impostazione predefinita si applica anche a ogni membro del tipo.Similarly, if the guarantee is applied to the type, by default it also applies to each member of the type.

Questa garanzia ereditata può essere sottoposta a override applicando la ComponentGuaranteesAttribute a singoli tipi e membri di tipo.This inherited guarantee can be overridden by applying the ComponentGuaranteesAttribute to individual types and type members. Tuttavia, le garanzie che sostituiscono il valore predefinito possono indebolire solo la garanzia; non possono potenziarlo.However, guarantees that override the default can only weaken the guarantee; they cannot strengthen it. Se, ad esempio, un assembly è contrassegnato con la garanzia None, i tipi e i membri non hanno alcuna garanzia di compatibilità e qualsiasi altra garanzia applicata ai tipi o ai membri nell'assembly viene ignorata.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.

Test della garanziaTesting the Guarantee

La proprietà Guarantees restituisce un membro dell'enumerazione ComponentGuaranteesOptions, contrassegnata con l'attributo FlagsAttribute.The Guarantees property returns a member of the ComponentGuaranteesOptions enumeration, which is marked with the FlagsAttribute attribute. Ciò significa che è necessario verificare il flag a cui si è interessati mascherando i flag potenzialmente sconosciuti.This means that you should test for the flag that you are interested in by masking away potentially unknown flags. Ad esempio, nell'esempio seguente viene verificato se un tipo è contrassegnato come Stable.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

Nell'esempio seguente viene verificato se un tipo è contrassegnato come Stable o Exchange.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

Nell'esempio seguente i test di un tipo sono contrassegnati come None (ovvero, né StableExchange).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      

Constructors

ComponentGuaranteesAttribute(ComponentGuaranteesOptions)

Inizializza una nuova istanza della classe ComponentGuaranteesAttribute con un valore che indica il livello di compatibilità garantito di librerie, tipi o membri fra più versioni.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.

Properties

Guarantees

Ottiene un valore che indica il livello di compatibilità garantito di una libreria, di un tipo o di un membro di tipo che si estende a più versioni.Gets a value that indicates the guaranteed level of compatibility of a library, type, or type member that spans multiple versions.

TypeId

Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Inherited from Attribute)

Methods

Equals(Object)

Restituisce un valore che indica se questa istanza è uguale a un oggetto specificato.Returns a value that indicates whether this instance is equal to a specified object.

(Inherited from Attribute)
GetHashCode()

Restituisce il codice hash relativo a questa istanza.Returns the hash code for this instance.

(Inherited from Attribute)
GetType()

Ottiene l'oggetto Type dell'istanza corrente.Gets the Type of the current instance.

(Inherited from Object)
IsDefaultAttribute()

In caso di override in una classe derivata, indica se il valore di questa istanza è il valore predefinito per la classe derivata.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Inherited from Attribute)
Match(Object)

Quando è sottoposto a override in una classe derivata, restituisce un valore che indica se questa istanza equivale a un oggetto specificato.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Inherited from Attribute)
MemberwiseClone()

Crea una copia superficiale dell'oggetto Object corrente.Creates a shallow copy of the current Object.

(Inherited from Object)
ToString()

Restituisce una stringa che rappresenta l'oggetto corrente.Returns a string that represents the current object.

(Inherited from Object)

Explicit Interface Implementations

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

Esegue il mapping di un set di nomi a un set corrispondente di ID dispatch.Maps a set of names to a corresponding set of dispatch identifiers.

(Inherited from Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Recupera le informazioni sul tipo relative a un oggetto, che possono essere usate per ottenere informazioni sul tipo relative a un'interfaccia.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Inherited from Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Recupera il numero delle interfacce di informazioni sul tipo fornite da un oggetto (0 o 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Inherited from Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Fornisce l'accesso a proprietà e metodi esposti da un oggetto.Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

Applies to

See also