Класс System.Runtime.Versioning.ComponentGuaranteesAttribute

В этой статье приводятся дополнительные замечания к справочной документации по этому API.

ComponentGuaranteesAttribute используется разработчиками компонентов и библиотек классов, чтобы указать уровень совместимости, который потребители своих библиотек могут ожидать в нескольких версиях. Он указывает уровень гарантии того, что будущая версия библиотеки или компонента не прерывает существующий клиент. Затем клиенты могут использовать ComponentGuaranteesAttribute в качестве помощи в разработке собственных интерфейсов для обеспечения стабильности между версиями.

Примечание.

Общая языковая среда выполнения (CLR) никак не использует этот атрибут. Его значение заключается в формальном документировании намерений автора компонента. Средства на этапе компиляции также могут использовать эти объявления для обнаружения ошибок, которые в противном случае нарушают объявленную гарантию.

Уровни совместимости

ComponentGuaranteesAttribute поддерживает следующие уровни совместимости, представленные членами перечисления ComponentGuaranteesOptions:

• Нет совместимости версий (ComponentGuaranteesOptions.None). Клиент может ожидать, что будущие версии нарушат работу существующего клиента. Дополнительные сведения см. в разделе Отсутствие совместимости далее в этой статье.

• Совместимость версий, работающих параллельно (ComponentGuaranteesOptions.SideBySide). Компонент протестирован для работы, если в одном домене приложения загружается несколько версий сборки. Как правило, будущие версии могут нарушить совместимость. Однако при внесении критических изменений старая версия не изменяется, но существует вместе с новой версией. Параллельное выполнение — это ожидаемый способ сделать так, чтобы существующие клиенты работали при внесении изменений, нарушающих совместимость. Для получения дополнительной информации см. раздел о параллельной совместимости, который находится далее в этой статье.

• Стабильная совместимость между версиями (ComponentGuaranteesOptions.Stable). Будущие версии не должны прерывать клиент, а параллельное выполнение не должно быть необходимо. Однако если клиент непреднамеренно разбит, возможно, можно использовать параллельное выполнение для устранения проблемы. Дополнительные сведения см. в разделе стабильной совместимости .

• Совместимость между версиями Exchange (ComponentGuaranteesOptions.Exchange). Особое внимание уделяется тому, чтобы гарантировать, что будущие версии не нарушат работу клиента. Клиент должен использовать только эти типы в сигнатуре интерфейсов, которые используются для взаимодействия с другими сборками, развернутыми независимо друг от друга. Ожидается, что только одна версия этих типов находится в определенном домене приложения, что означает, что если клиент прерывает работу, параллельное выполнение не может устранить проблему совместимости. Дополнительные сведения см. в разделе о совместимости типов Exchange .

В следующих разделах подробно рассматриваются все уровни гарантии.

Без совместимости

Маркировка компонента как ComponentGuaranteesOptions.None указывает, что поставщик не гарантирует совместимость. Клиенты должны избегать принятия зависимостей от предоставляемых интерфейсов. Этот уровень совместимости полезен для типов, которые являются экспериментальными или общедоступными, но предназначены только для компонентов, которые всегда обновляются одновременно. None явно указывает, что этот компонент не должен использоваться внешними компонентами.

Одновременная совместимость

Пометка компонента как ComponentGuaranteesOptions.SideBySide указывает, что компонент протестирован для работы при загрузке нескольких версий сборки в тот же домен приложения. Критические изменения допускаются, если они вносятся в сборку с более высоким номером версии. Компоненты, привязанные к старой версии сборки, должны продолжать привязываться к старой версии, а другие компоненты могут привязаться к новой версии. Кроме того, можно обновить компонент, объявленный как SideBySide путем разрушительного изменения старой версии.

Стабильная совместимость

Пометка типа как ComponentGuaranteesOptions.Stable указывает, что тип должен оставаться стабильным в разных версиях. Однако можно также использовать параллельные версии стабильного типа, которые будут существовать в том же домене приложения.

Стабильные типы поддерживают высокий двоичный индикатор совместимости. Из-за этого поставщики должны избегать критических изменений в стабильных типах. Допустимы следующие типы изменений:

• Добавление полей частного экземпляра или удаление полей из типа, если это не нарушает формат сериализации.
• Изменение несериализируемого типа на сериализуемый тип. (Однако сериализуемый тип нельзя изменить на несериализируемый тип.)
• Создание новых, более производных исключений из метода.
• Повышение производительности метода.
• Изменение диапазона возвращаемых значений при условии, что изменение не оказывает негативного влияния на большинство клиентов.
• Исправление серьезных ошибок, если бизнес-обоснование является высоким, а количество пострадавших клиентов низко.

Так как новые версии стабильных компонентов не должны прерывать существующие клиенты, обычно в домене приложения требуется только одна версия стабильного компонента. Однако это не является обязательным требованием, так как стабильные типы не используются как известные типы обмена, на которые согласуются все компоненты. Таким образом, если новая версия стабильного компонента непреднамеренно прерывает некоторый компонент, и если другие компоненты нуждаются в новой версии, это может быть возможно, чтобы устранить проблему, загрузив старый и новый компонент.

Stable обеспечивает более надежную гарантию совместимости версий, чем None. Это обычное значение по умолчанию для компонентов с несколькими версиями.

Stable можно сочетать с SideBySide, что указывает, что компонент не прерывает совместимость, но проверяется для работы при загрузке нескольких версий в определенном домене приложения.

После того как тип или метод помечается как Stable, его можно обновить до Exchange. Однако его нельзя уменьшить до None.

Совместимость типов Exchange

Маркировка типа как ComponentGuaranteesOptions.Exchange обеспечивает более надежную гарантию совместимости версий, чем Stable, и следует применять к наиболее стабильной из всех типов. Эти типы предназначены для обмена между независимо построенными компонентами на всех границах компонентов во временном аспекте (любая версия среды CLR или любая версия компонента или приложения) и в пространственном аспекте (кросспроцессный обмен, кросс-CLR в одном процессе, обмен между доменами приложений в одной среде CLR). Если критическое изменение вносится в тип обмена, невозможно устранить проблему, загрузив несколько версий этого типа.

Типы Exchange должны изменяться только в том случае, если проблема очень серьезна (например, серьезная проблема безопасности) или вероятность поломки крайне мала (то есть, если поведение уже было нарушено случайным образом, и на него невозможно было бы положиться в коде). Вы можете внести следующие изменения в тип exchange:

• Добавьте наследование новых определений интерфейса.

• Добавьте новые частные методы, реализующие методы недавно унаследованных определений интерфейса.

• Добавьте новые статические поля.

• Добавьте новые статические методы.

• Добавьте новые не виртуальные методы экземпляра.

Следующие изменения считаются ломаюшими и не допускаются для примитивных типов:

• Изменение форматов сериализации. Требуется сериализация с поддержкой различных версий.

• Добавление или удаление полей частного экземпляра. Существует риск изменения формата сериализации типа и нарушения клиентского кода, который использует рефлексию.

• Изменение сериализуемости типа. Несериализуемый тип не может стать сериализуемым, и наоборот.

• Создание различных исключений из метода.

• Изменение диапазона возвращаемых значений метода, если только определение элемента не указывает эту вероятность и четко указывает, как клиенты должны обрабатывать неизвестные значения.

• Исправление большинства ошибок. Потребители типа будут полагаться на существующее поведение.

После того как компонент, тип или член помечен меткой Exchange, его нельзя изменить на Stable или None.

Как правило, типы обмена — это базовые типы (например, Int32 и String в .NET) и интерфейсы (например, IList<T>, IEnumerable<T>и IComparable<T>), которые обычно используются в общедоступных интерфейсах.

Типы Exchange могут быть публично доступны только для других типов с совместимостью Exchange. Кроме того, типы обмена не могут зависеть от поведения API Windows, подверженных изменению.

Гарантии компонентов

В следующей таблице показано, как характеристики и использование компонента влияют на ее гарантию совместимости.

Характеристики компонентов	Обмен	Стабильный	Бок о бок	Нет
Можно использовать в интерфейсах между компонентами, которые обновляются независимо.	У	Н	Н	Н
Можно использовать (приватно) сборкой, которая обновляется независимо.	У	У	У	Н
Может иметь несколько версий в одном домене приложения.	Н	У	У	У
Может вносить критические изменения	Н	Н	У	У
Протестировано, чтобы убедиться, что несколько версий сборки можно загрузить вместе.	Н	Н	У	Н
Может произвести критические изменения в месте.	Н	Н	Н	У
Может вносить очень безопасные неисключаемые изменения в обслуживание.	У	У	У	У

Применение атрибута

Вы можете применить ComponentGuaranteesAttribute к сборке, типу или члену типа. Его приложение является иерархическим. То есть по умолчанию гарантия, определяемая свойством Guarantees атрибута на уровне сборки, определяет гарантию всех типов в сборке и всех членов этих типов. Аналогичным образом, если гарантия применяется к типу, по умолчанию она также применяется к каждому элементу типа.

Эта наследуемая гарантия может быть переопределена путем применения ComponentGuaranteesAttribute к отдельным типам и элементам типов. Однако гарантии, которые отменяют изначальные условия, могут только ослабить гарантию; они не могут её укрепить. Например, если сборка помечена гарантией None, его типы и члены не имеют гарантии совместимости, а другая гарантия, применяемая к типам или элементам в сборке, игнорируется.

Проверка гарантии

Свойство Guarantees возвращает элемент перечисления ComponentGuaranteesOptions, помеченный атрибутом FlagsAttribute. Это означает, что вы должны проверить флаг, который вас интересует, маскируя потенциально неизвестные флаги. Например, в следующем примере проверяется, помечен ли тип как Stable.

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine($"{typ.Name} is marked as {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.

// Test whether guarantee is Stable or Exchange.
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) > 0)
   Console.WriteLine($"{typ.Name} is marked as Stable or Exchange.");

' 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).

// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
   Console.WriteLine($"{typ.Name} has no compatibility 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