Средства совместимости API

  • Статья

Кроссплатформенная совместимость стала популярным требованием для авторов библиотек .NET. Однако без инструментов для проверки сборок и пакетов они могут содержать непреднамеренные критические изменения. В качестве автора библиотеки необходимо убедиться, что многоцеловые сборки совместимы. Например, для пакета, который предназначен для .NET 6 и .NET Standard 2.0, необходимо убедиться, что код, скомпилированный в двоичном файле .NET Standard 2.0, может выполняться в двоичном файле .NET 6.

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

Пакет SDK для .NET предоставляет различные способы сравнения версий, созданных для различных целевых платформ. Вы также можете проверить более новую версию в базовой версии, чтобы не было введено критических изменений. Включите задачи MSBuild для проверки сборок во время компиляции или пакетов при пакете. Кроме того, используйте глобальное средство Microsoft.DotNet.ApiCompat.Tool для проверки за пределами MSBuild.

Дополнительные сведения о проверке пакетов см. в разделе "Проверка пакетов". Проверка сборки должна использоваться, если приложение не упаковывается. Дополнительные сведения о проверке сборки см. в разделе "Проверка сборки".

Примечание.

Чтобы выполнить проверку сборки в качестве задачи MSBuild, необходимо добавить ссылку на пакет в Microsoft.DotNet.ApiCompat.Task. Аналогичным образом можно также добавить ссылку на этот пакет, если требуется протестировать новые функции, которые еще не доступны в пакете SDK для .NET. Например, можно ссылаться на версию 9.0.100-preview пакета Microsoft.DotNet.ApiCompat.Task при использовании пакета SDK для .NET 8.

Строгий режим

По умолчанию проверка выполняет проверка совместимости. Однако вы также можете выбрать строгий режим. В строгом режиме проверка выполняет проверка равенства. Равенство означает, что не были внесены изменения API или сборки, даже совместимые.

Варианты использования для строгого режима включают следующие:

  • Обслуживание, в котором обычно запрещены дополнения API.
  • Для отслеживания изменений API. Функции совместимости API записывают все различия совместимости в файле подавления, если для параметра ApiCompatGenerateSuppressionFile задано значение true.

Чтобы включить строгий режим для средства командной строки, укажите --strict-mode параметр или один из --enable-strict* параметров. Чтобы включить строгий режим для задач MSBuild, добавьте в файл проекта одно или несколько следующих свойств MSBuild: