大网数据广告活动
.NET 与 C# 开发

版本控制和 .NET 库

· 52CE 我爱测

版本控制 .NET 库的最佳实践建议。

软件库在版本 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>

Windows .NET Framework CLR 要求完全匹配以便加载具有强名称的程序集。 例如,Libary1, 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 CLR 将在运行时自动加载更高版本的程序集。

✔️请考虑在 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>

Windows 资源管理器

✔️请考虑包括持续集成内部版本号作为 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 包括从中生成程序集的源代码的提交哈希。 有关详细信息,请参阅源链接。

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

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

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

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

上一页 下一页

历史资料。此文对应 2019-08-18 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者(原始作者元数据 jamesnk)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体、发布器占位标签和导航标记。

资料来源与适用范围

资料来源
Microsoft / .NET 中文文档历史快照
适用范围
历史中文快照 2019-08-18;详见原文产品版本;文档日期 12/10/2018
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。