Управление версиями
Библиотека программного обеспечения редко завершается в версии 1.0. Хорошие библиотеки развиваются со временем, добавляя функции, устраняя ошибки и повышая производительность. Важно, чтобы вы могли выпускать новые версии библиотеки .NET, не нарушая существующих пользователей.
Критические изменения
Сведения об обработке критических изменений между версиями см. в разделе Критические изменения.
Номера версий
Библиотека .NET имеет множество способов указать версию. Эти версии являются наиболее важными:
Версия пакета NuGet
Версия пакета NuGet отображается на сайте NuGet.org и в диспетчере пакетов NuGet в Visual Studio, а также добавляется в исходный код при использовании пакета. Версия пакета NuGet — это обычно видимый номер версии, и они будут ссылаться на нее при разговоре о версии библиотеки, которую они используют. Версия пакета NuGet используется NuGet и не влияет на поведение среды выполнения.
<PackageVersion>1.0.0-alpha1</PackageVersion>
Идентификатор пакета NuGet в сочетании с версией пакета NuGet используется для идентификации пакета в NuGet. Например, Newtonsoft.Json + 11.0.2. Пакет с суффиксом — это предварительно подготовленный пакет и имеет специальное поведение, которое делает его идеальным для тестирования. Дополнительные сведения см. в разделе о пакетах предварительной версии .
Так как версия пакета NuGet является самой видимой версией для разработчиков, рекомендуется обновить ее с помощью семантического версионирования (SemVer). SemVer указывает на важность изменений между выпусками и помогает разработчикам принимать обоснованные решения при выборе используемой версии. Например, переход от 1.0 к 2.0 указывает на то, что возможны критические изменения.
✔️ Рекомендуется использовать SemVer 2.0.0.0 для версии пакета NuGet.
✔️ Используйте версию пакета NuGet в общедоступной документации, так как это номер версии, который пользователи обычно видят.
✔️ Обязательно включайте суффикс предварительного выпуска при выпуске нестабильного пакета. (Дополнительные сведения о маркировке API в виде предварительной версии или экспериментальной версии см. в предварительных версий API.)
Пользователи должны принять участие в получении пакетов предварительной версии, поэтому они понимают, что пакет не завершен.
Версия сборки
Версия сборки — это то, что среда 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 имеют сборку
1.0.0.0, а библиотека 2.0 имеет AssemblyVersion2.0.0.0. Когда версия сборки изменяется реже, это уменьшает перенаправления привязок.
✔️ Следует синхронизировать основной номер версии AssemblyVersion и версию пакета NuGet.
AssemblyVersion включается в некоторые информационные сообщения, отображаемые пользователю, например имя сборки и имена квалифицированных типов сборки в сообщениях исключений. Поддержание связи между версиями предоставляет дополнительные сведения разработчикам о том, какую версию они используют.
❌ не имеют фиксированной версии сборки.
Хотя использование неизменяющейся AssemblyVersion избегает необходимости в перенаправлении привязок, это означает, что в глобальном кэше сборок (GAC) можно установить только одну версию сборки. Кроме того, приложения, ссылающиеся на сборку в GAC, перестанут работать, если другое приложение обновляет сборку GAC изменениями, нарушающими совместимость.
Версия файла сборки
Версия файла сборки используется для отображения версии файла в 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. Предупреждение возникает, если версия не соответствует этому формату.
Информационная версия сборки
Информационная версия сборки используется для записи дополнительных сведений о версии и не влияет на поведение среды выполнения. Установка этой версии является необязательной. Если вы используете Source Link, эта версия будет установлена при сборке с версией пакета NuGet плюс версией системы контроля версий. Например, 1.0.0-beta1+204ff0a включает хеш коммита исходного кода, из которого была создана сборка. Дополнительные сведения см. в ссылке на источник.
<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>
Заметка
Старые версии Visual Studio вызывают предупреждение о сборке, если эта версия не соответствует формату Major.Minor.Build.Revision. Предупреждение можно безопасно игнорировать.
❌ НЕ НАСТРАИВАЙТЕ информационную версию сборки самостоятельно.
Разрешить SourceLink автоматически создавать версию, содержащую метаданные NuGet и системы управления версиями.
