版本管理Versioning

软件库在版本 1.0 中很少是完整的。A software library is rarely complete in version 1.0. 良好的库随时间而演变,例如,添加功能、修复缺陷和提高性能。Good libraries evolve over time, adding features, fixing bugs, and improving performance. 重要的是你可以发布新版本的 .NET 库,为每个版本提供附加值,而不会中断现有用户。It is important that you can release new versions of a .NET library, providing additional value with each version, without breaking existing users.

重大更改Breaking changes

有关处理版本之间的重大更改的信息,请参阅重大更改For information about handling breaking changes between versions, see Breaking changes.

版本号Version numbers

.NET 库有多种方法用来指定版本。A .NET library has many ways to specify a version. 以下版本是最重要的:These versions are the most important:

NuGet 包版本NuGet package version

使用 NuGet 包时,NuGet 包版本会显示在 NuGet.org(即 Visual Studio NuGet 包管理器)上,并添加到源代码。The NuGet package version is displayed on NuGet.org, the Visual Studio NuGet package manager, and is added to source code when the package is used. NuGet 包版本是用户通常看到的版本号,并且会在用户谈论所用的库的版本时引用该包版本。The NuGet package version is the version number users will commonly see, and they'll refer to it when they talk about the version of a library they're using. NuGet 包版本由 NuGet 使用,并且对运行时行为没有影响。The NuGet package version is used by NuGet and has no effect on runtime behavior.

<PackageVersion>1.0.0-alpha1</PackageVersion>

与 NuGet 包版本结合使用的 NuGet 包标识符用于标识 NuGet 中的包。The NuGet package identifier combined with the NuGet package version is used to identify a package in NuGet. 例如,Newtonsoft.Json + 11.0.2For example, Newtonsoft.Json + 11.0.2. 带有后缀的包是一个预发行包,其中的特殊行为非常适用于测试。A package with a suffix is a pre-release package and has special behavior that makes it ideal for testing. 有关详细信息,请参阅预发行包For more information, see Pre-release packages.

由于 NuGet 包版本是开发人员最易于可见的版本,因此最好使用语义化版本控制 (SemVer) 进行更新。Because the NuGet package version is the most visible version to developers, it's a good idea to update it using Semantic Versioning (SemVer). SemVer 指出版本之间的重大更改,并且可以帮助开发人员在选择要使用哪个版本时做出明智的决策。SemVer indicates the significance of changes between release and helps developers make an informed decision when choosing what version to use. 例如,从 1.02.0 指示可能有重大更改。For example, going from 1.0 to 2.0 indicates that there are potentially breaking changes.

✔️ 请考虑使用 SemVer 2.0.0 控制 NuGet 包的版本。✔️ CONSIDER using SemVer 2.0.0 to version your NuGet package.

✔️ 请在公共文档中使用 NuGet 包版本,因为它是用户通常看到的版本号。✔️ DO use the NuGet package version in public documentation as it's the version number that users will commonly see.

✔️ 请在发布非稳定版包时包含预发行后缀。✔️ DO include a pre-release suffix when releasing a non-stable package.

用户必须选择获取预发行包,以便了解包不是完整的。Users must opt in to getting pre-release packages, so they will understand that the package is not complete.

程序集版本Assembly version

程序集版本是 CLR 在运行时用来选择要加载哪个程序集版本的依据。The assembly version is what the CLR uses at run time to select which version of an assembly to load. 使用版本控制选择程序集仅适用于具有强名称的程序集。Selecting an assembly using versioning only applies to assemblies with a strong name.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

.NET Framework CLR 要求完全匹配以便加载具有强名称的程序集。The .NET Framework CLR demands an exact match to load a strong-named assembly. 例如,Libary1, Version=1.0.0.0 已使用对 Newtonsoft.Json, Version=11.0.0.0 的引用进行编译。For example, Libary1, Version=1.0.0.0 was compiled with a reference to Newtonsoft.Json, Version=11.0.0.0. .NET Framework 将仅加载该确切版本 11.0.0.0.NET Framework will only load that exact version 11.0.0.0. 若要在运行时加载其他版本,必须向 .NET 应用程序的配置文件添加绑定重定向。To load a different version at run time, a binding redirect must be added to the .NET application's config file.

与程序集版本组合使用的强命名启用严格的程序集版本加载Strong naming combined with assembly version enables strict assembly version loading. 虽然强命名库具有很多好处,但通常会导致出现找不到程序集的运行时异常,并且在要修复的 app.configweb.config需要绑定重定向While strong naming a library has a number of benefits, it often results in run-time exceptions that an assembly can't be found and requires binding redirects in app.config or web.config to be fixed. 在 .NET Core 中,程序集加载更加宽松。In .NET Core, assembly loading is more relaxed. .NET Core 运行时在运行时自动加载版本较高的程序集。The .NET Core runtime automatically loads assemblies with a higher version at run time.

✔️ 请考虑在 AssemblyVersion 中仅包括主版本。✔️ CONSIDER only including a major version in the AssemblyVersion.

例如,库 1.0 和库 1.0.1 都具有 AssemblyVersion 1.0.0.0,而库 2.0 具有 AssemblyVersion 2.0.0.0e.g. Library 1.0 and Library 1.0.1 both have an AssemblyVersion of 1.0.0.0, while Library 2.0 has AssemblyVersion of 2.0.0.0. 当程序集版本不常更改时,会减少绑定重定向。When the assembly version changes less often, it reduces binding redirects.

✔️ 请考虑使 AssemblyVersion 的主版本号与 NuGet 包版本保持同步。✔️ CONSIDER keeping the major version number of the AssemblyVersion and the NuGet package version in sync.

AssemblyVersion 包含在向用户显示的一些信息性消息中,例如异常消息中的程序集名称和程序集限定类型名称。The AssemblyVersion is included in some informational messages displayed to the user, e.g. the assembly name and assembly qualified type names in exception messages. 维持版本之间的关系可向开发人员提供有关所用版本的详细信息。Maintaining a relationship between the versions provides more information to developers about which version they are using.

❌ 不要有固定的 AssemblyVersion。❌ DO NOT have a fixed AssemblyVersion.

虽然不变的 AssemblyVersion 不需要绑定重定向,但意味着在全局程序集缓存 (GAC) 中只能安装单个程序集版本。While an unchanging AssemblyVersion avoids the need for binding redirects, it means that only a single version of the assembly can be installed in the Global Assembly Cache (GAC). 此外,引用 GAC 中的程序集的应用程序将中断,前提是另一个应用程序使用重大更改更新 GAC 程序集。Also, the applications that reference the assembly in the GAC will break if another application updates the GAC assembly with breaking changes.

程序集文件版本Assembly file version

程序集文件版本用于在 Windows 中显示文件版本,并且对运行时行为没有影响。The assembly file version is used to display a file version in Windows and has no effect on run-time behavior. 设置此版本是可选的。Setting this version is optional. 它在 Windows 资源管理器的“文件属性”对话框中可见:It's visible in the File Properties dialog in Windows Explorer:

<FileVersion>11.0.2.21924</FileVersion>

Windows 资源管理器Windows Explorer

✔️ 请考虑包括持续集成内部版本号作为 AssemblyFileVersion 修订号。✔️ CONSIDER including a continuous integration build number as the AssemblyFileVersion revision.

例如,生成的项目版本为 1.0.0 且持续集成内部版本号为 99,则 AssemblyFileVersion 为 1.0.0.99。For example, you are building version 1.0.0 of your project, and the continuous integration build number is 99 so your AssemblyFileVersion is 1.0.0.99.

✔️ 请对文件版本使用 Major.Minor.Build.Revision 格式。✔️ DO use the format Major.Minor.Build.Revision for file version.

虽然 .NET 从不使用此文件版本,但 Windows 期望文件版本采用 Major.Minor.Build.Revision 格式。While the file version is never used by .NET, Windows expects the file version to be in the Major.Minor.Build.Revision format. 如果版本不遵循此格式,则会引发警告。A warning is raised if the version doesn't follow this format.

程序集信息性版本Assembly informational version

程序集信息性版本用于记录附加版本信息,并且对运行时行为没有影响。The assembly informational version is used to record additional version information and has no effect on runtime behavior. 设置此版本是可选的。Setting this version is optional. 如果使用的是源链接,则将在具有 NuGet 包版本以及源代码管理版本的内部版本上设置此版本。If you're using Source Link, this version will be set on build with the NuGet package version plus a source control version. 例如,1.0.0-beta1+204ff0a 包括从中生成程序集的源代码的提交哈希。For example, 1.0.0-beta1+204ff0a includes the commit hash of the source code the assembly was built from. 有关详细信息,请参阅源链接For more information, see Source Link.

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

备注

如果此版本不遵循格式 Major.Minor.Build.Revision,则较早版本的 Visual Studio 会引发生成警告。Older versions of Visual Studio raise a build warning if this version doesn't follow the format Major.Minor.Build.Revision. 可放心忽略此警告。The warning can be safely ignored.

❌ 请避免自行设置程序集信息性版本。❌ AVOID setting the assembly informational version yourself.

允许 SourceLink 自动生成包含 NuGet 和源代码管理元数据的版本。Allow SourceLink to automatically generate the version containing NuGet and source control metadata.