Управление версиями

Разработка библиотек программного обеспечения редко завершается версией 1.0. Хорошая библиотека постоянно развивается: появляются новые функции, исправляются ошибки и повышается производительность. Очень важно правильно выпускать новые версии библиотеки .NET, расширяя ее возможности и не допуская появления проблем для уже существующих пользователей.

Критические изменения

См. сведения об оценке критических изменений между версиями.

Номера версий

Для библиотеки .NET версию можно указать разными способами. Вот несколько наиболее важных версий:

Версия пакета NuGet

Версия пакета NuGet отображается на сайте NuGet.org в диспетчере пакетов Visual Studio NuGet. Она добавляется к исходному коду при использовании пакета. Именно версию пакета NuGet чаще всего будут видеть пользователи и именно ее они будут считать версией используемой библиотеки. Версия пакета NuGet используется только в пределах NuGet и никак не влияет на поведение во время выполнения.

<PackageVersion>1.0.0-alpha1</PackageVersion>

Идентификатор пакета NuGet в сочетании с версией пакета NuGet используется для идентификации пакета в NuGet. Например, Newtonsoft.Json + 11.0.2. Пакет с суффиксом обозначает пакет предварительной версии, и для него используются специальные правила, благодаря которым он идеально подходит для тестирования. См. с сведения о пакетах предварительной версии.

Так как версия пакета NuGet встречается разработчикам чаще всего, мы рекомендуем обновлять ее с использованием Семантического версионирования (SemVer). SemVer указывает на значимость изменений, реализованных в очередном выпуске, помогая разработчикам правильно выбрать версию для использования. Например, переход от версии 1.0 к 2.0 указывает на наличие потенциальных критических изменений.

✔️ CONSIDER Использование SemVer 2.0.0 для управления версиями пакета NuGet.

✔️ СЛЕДУЕТ использовать версию пакета NuGet в общедоступной документации, так как именно этот номер версии пользователи будут видеть чаще всего.

✔️ СЛЕДУЕТ добавить суффикс предварительной версии при выпуске нестабильной версии пакета.

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

Версия сборки

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

<AssemblyVersion>1.0.0.0</AssemblyVersion>

Среда CLR для .NET Framework при загрузке сборок со строгими именами требует точного соответствия. Предположим, что Library1, Version=1.0.0.0 компилируется со ссылкой на Newtonsoft.Json, Version=11.0.0.0. Тогда .NET Framework будет загружать только версию 11.0.0.0. Чтобы загрузить во время выполнения другую версию, необходимо добавить переадресацию привязок в файл конфигурации приложения .NET.

Использование строгого именования в сочетании с версией сборки позволяет организовать строгую загрузку версий сборок. Хотя строгое именование библиотек имеет ряд преимуществ, оно часто вызывает исключения времени выполнения, если не удается найти точную версию сборки. Для устранения таких проблем требуется исправление переадресации привязок в app.config или web.config. В .NET Core загрузка сборок менее строгая. Среда выполнения .NET Core во время выполнения автоматически загружает сборки с более поздней версией.

✔ РЕКОМЕНДУЕТСЯ указывать в AssemblyVersion только основной номер версии.

Например, библиотека 1.0 и библиотека 1.0.1 имеют СборкуVersion, а библиотека 2.0 имеет AssemblyVersion1.0.0.02.0.0.0. Если версия сборки меняется редко, потребуется меньше переадресаций привязок.

✔ РЕКОМЕНДУЕТСЯ синхронизировать основной номер версии AssemblyVersion и версию пакета NuGet.

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

❌ НЕ СЛЕДУЕТ использовать фиксированное значение AssemblyVersion.

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

Версия файла сборки

Версия файла сборки используется для отображения версии файла в ОС Windows и никак не влияет на поведение во время выполнения. Настройка этой версии является необязательной. Она отображается в диалоговом окне "Свойства файла" в проводнике Windows:

<FileVersion>11.0.2.21924</FileVersion>

✔ РЕКОМЕНДУЕТСЯ использовать номер сборки непрерывной интеграции в качестве номера редакции AssemblyFileVersion.

Например, если вы создаете версию проекта 1.0.0, а номер сборки непрерывной интеграции имеет значение 99, параметр AssemblyFileVersion получит значение 1.0.0.99.

✔️️ СЛЕДУЕТ использовать формат Major.Minor.Build.Revision для версии файла.

Версия файла никогда не применяется в .NET, но в Windows ожидается версия файла в формате Major.Minor.Build.Revision. Если версия не соответствует этому формату, появляется предупреждение.

Информационная версия сборки

Информационная версия сборки используется для сохранения дополнительных сведений о версии и никак не влияет на поведение во время выполнения. Настройка этой версии является необязательной. Если вы используете SourceLink, это значение при сборке составляется из номера версии пакета NuGet и номера в системе управления версиями. Например, 1.0.0-beta1+204ff0a включает хэш фиксации для исходного кода, из которого построена сборка. Дополнительные сведения см. в разделе Ссылка на источник.

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

❌ НЕЖЕЛАТЕЛЬНО самостоятельно указывать информационную версию сборки.

Разрешите SourceLink автоматически создавать этот номер версии из метаданных NuGet и системы управления версиями.