版本管理

软件库在版本 1.0 中很少是完整的。 良好的库随时间而演变，例如，添加功能、修复缺陷和提高性能。 重要的是你可以发布新版本的 .NET 库，为每个版本提供附加值，而不会中断现有用户。

重大更改

有关处理版本之间的重大更改的信息，请参阅重大更改。

版本号

.NET 库有多种方法用来指定版本。 以下版本是最重要的：

NuGet 包版本

使用 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 指示可能有重大更改。

✔️ 请考虑使用 SemVer 2.0.0 控制 NuGet 包的版本。

✔️ 请在公共文档中使用 NuGet 包版本，因为它是用户通常看到的版本号。

✔️ 请在发布非稳定版包时包含预发行后缀。

用户必须选择获取预发行包，以便了解包不是完整的。

程序集版本

程序集版本是 CLR 在运行时用来选择要加载哪个程序集版本的依据。 使用版本控制选择程序集仅适用于具有强名称的程序集。

<AssemblyVersion>1.0.0.0</AssemblyVersion>

.NET Framework CLR 要求完全匹配以便加载具有强名称的程序集。 例如，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 都具有 AssemblyVersion 1.0.0.0，而库 2.0 则具有 AssemblyVersion 2.0.0.0。 当程序集版本不常更改时，会减少绑定重定向。

✔️ 请考虑使 AssemblyVersion 的主版本号与 NuGet 包版本保持同步。

AssemblyVersion 包含在向用户显示的一些信息性消息中，例如异常消息中的程序集名称和程序集限定类型名称。 维持版本之间的关系可向开发人员提供有关所用版本的详细信息。

❌ 不要有固定的 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 格式。 如果版本不遵循此格式，则会引发警告。

程序集信息性版本

程序集信息性版本用于记录附加版本信息，并且对运行时行为没有影响。 设置此版本是可选的。 如果使用的是源链接，则将在具有 NuGet 包版本以及源代码管理版本的内部版本上设置此版本。 例如，1.0.0-beta1+204ff0a 包括从中生成程序集的源代码的提交哈希。 有关详细信息，请参阅源链接。

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

注意

如果此版本不遵循格式 Major.Minor.Build.Revision，则较早版本的 Visual Studio 会引发生成警告。 可放心忽略此警告。

❌ 请避免自行设置程序集信息性版本。

允许 SourceLink 自动生成包含 NuGet 和源代码管理元数据的版本。

上一页下一页