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

ComponentGuaranteesAttribute поддерживает следующие уровни совместимости, которые представлены членами перечисления ComponentGuaranteesOptions.The 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.

  • Совместимость версии Exchange с версией (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. Однако это не является обязательным требованием, так как устойчивые типы не используются в качестве хорошо известных типов Exchange, с которыми согласовываются все компоненты.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, его можно обновить до Exchange.After a type or method is marked as Stable, it can be upgraded to Exchange. Однако его нельзя понизить до None.However, it cannot be downgraded to None.

Совместимость типов ExchangeExchange 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). В тип обмена можно внести следующие изменения: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.

  • Изменение возможности сериализации типа.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.

  • Устранение большинства ошибок.Fixing most bugs. Потребители типа будут полагаться на существующее поведение.Consumers of the type will rely on the existing behavior.

После того как компонент, тип или член помечается как Exchange гарантия, его нельзя изменить на Stable или None.After 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 types may publicly expose only other types that are also marked with Exchange compatibility. Кроме того, типы обмена не могут зависеть от поведения интерфейсов API Windows, которые подвержены изменениям.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 стабильныхStable ПараллельноSide-by-Side НетNone
Может использоваться в интерфейсах между компонентами независимо от версии.Can be used in interfaces between components that version independently. YY ВN ВN ВN
Может использоваться (в частном порядке) сборкой, независимой от версий.Can be used (privately) by an assembly that versions independently. YY YY YY ВN
Может иметь несколько версий в одном домене приложения.Can have multiple versions in a single application domain. ВN YY YY YY
Может внести критические измененияCan make breaking changes ВN ВN YY YY
Проверено, что можно загрузить несколько версий сборки вместе.Tested to make certain multiple versions of the assembly can be loaded together. ВN ВN YY ВN
Может внести критические изменения на месте.Can make breaking changes in place. ВN ВN ВN 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

Свойство Guarantees Возвращает элемент перечисления ComponentGuaranteesOptions, помеченный атрибутом FlagsAttribute.The 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. Например, в следующем примере проверяется, помечен ли тип как 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

В следующем примере проверяется, помечен ли тип как Stable или как 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

В следующем примере проверяется, предложено тип помечен как 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()

Возвращает объект Type для текущего экземпляра.Gets 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()

Возвращает строку, представляющую текущий объект.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)

Применяется к

Дополнительно