XDev.EasyVersion.Core 1.0.0.1

这还是一个正在进行中的项目

目录

• 简介
  • 支持文件
  • dotnet Tool ##待更新 TOC！

简介

在保持语义版本控制方案的情况下，自动化构建版本可能会变得相对复杂，特别是当您尝试使方法足够灵活以适应不同的版本和命名方案时。此存储库包含一系列工具，帮助您使用最少的环境特定脚本构建可靠的 CI/CD 管道。唯一的实际要求是 CLI 工具的 .Net 6 或更高版本运行时，或者您可以使用 Cake 构建，直接导入 XDev.EasyVersion.Core 或其他包。

此项目中封装的版本概念是，所有可发布的产品都应该有一个唯一的版本号，该版本号在单独构建中永远不会重复。此外，构建号作为 CI/CD 管道流程的一部分生成，而不是手动分配。这两个规则使我们能够在构建各种代码库（如 NuGet 包和跨平台应用程序包，如 Xamarin 或 Maui 应用以及桌面应用程序）时，不必担心意外重复，从而以人类可读的形式生成应用在语义版本控制方案中的唯一构建号。

支持文件

Build Information.txt

该文件负责指定为特定仓库生成版本号所需的信息，并必须包含在仓库中。默认情况下，工具会在根源目录中查找该文件。

/// ***********************************************************************************
/// **  The Release Pipeline will use this file to auto-version and track releases.  **
/// ***********************************************************************************

/// <summary>
/// Specifies the name of the package to release.
/// This tag and value is required.
/// </summary>
/// <example>
/// [Package Name]
/// My.Package
/// </example>
[Package Name]
My.Package

/// <summary>
/// Specifies the 3 octet version of the release.  This is the versioning schema used by Nuget.
/// This tag and value is required.
/// </summary>
/// <example>
/// [Release Version]
/// 1.2.3
/// </example>
[Release Version]
1.0.1

Build Information.txt 文件提供了两条关键信息，即在语义形式（主版本.次版本.修订版）下的包名和发布版本，仓库所有者可以手动按需增加。

包名

这是包的公共名称。无论我们是在构建 Nuget 仓库、iOS 或 Android 应用程序，还是桌面应用程序，这都是包含在发布元数据中的产品名称。

发布版本

这是包的 Major.Minor.Patch 语义版本。这种注释来源于 Nuget 指南，它还允许 CI-CD 管道自动增加文件版本号中使用的第四位字节。您可以选择任何三种字节版本号方案，如 Major.Minor.Patch、Major.Minor.Revision、Year.Quarter.Patch 等。只需记住，修改 Build Information.txt 文件是为了更新前三字节，并且非常适合与 CI-CD DevOps 进程结合使用的 Git-Flow 分支和合并策略，该策略在一个或多个长期分支（如 dev 和 main 或您所叫的任何名称）上执行自动构建。

发布历史.json

此文件独立于源代码存在，并跟踪特定仓库的所有构建和发布。此文件的存在使构建过程能够生成唯一的版本号，同时易于阅读，无需在现代代码或长哈希代码作为版本号的一部分。将构建历史和构建代码本身保留在同一仓库中是构建历史和构建代码版本管理（CM）的一个非常流行的选项。这是一个非常简单且易于操作的选项，如果不介意“混合”构建代码和源代码，并且如果您的开发团队也负责 DevOps 的话。然而，这确实引入了一些困难，例如，任何更新历史的构建现在都必须将提交返回到源仓库，这可能引发递归构建场景，除非您从自动构建触发中排除历史文件/目录，以及引入未审查的改变到其他受保护的分支。

作者认为，以下是更好的 CM 选项，因为它们允许分离 CI-CD 和源代码的职责：

• 在本地构建机器上，简单地将此文件保存在构建代理（运行器）可访问的位置。
• 将此文件保存在 git 子仓库中，并在构建中添加步骤，在构建开始时拉取正确的子仓库，并且只提交更改到负责构建历史的子仓库。
• 如果您使用 Azure DevOps，通用包 是在构建之间保持具有版本号的资产（包括代码覆盖率结果或我们的 Release History.json 文件）的一种非常简单的方法。
• 最后，如果您没有其他方法或它们不适用于您，则 XDev.EasyVersion.Nuget.History 可以提供一个工具，其功能几乎与 ADO 的通用包一样简单，但使用 NuGet 作为打包工具。

下面提到的 XDev.EasyVersion.exe 能够检索特定的发布信息以及滚动构建号，从语义版本中生成特定上下文的版本号（包括构建），并将新的构建添加到历史文件：Release History.json。

##todo: 添加 buildinfo.txt 详细信息...

dotnet 工具安装

要作为本地工具安装，请参阅此处的说明来设置本地工具存储库，然后从 nuget.org 安装包。

 dotnet new tool-manifest
 .
 .
 .
 dotnet tool install XDev.EasyVersion

要作为全局工具安装（需要管理员或 root 权限，因此这可能不是适用于管道的好选项）：dotnet tool install --global XDev.EasyVersion

要安装预发布版本，请包括 --prerelease 可能还包括 --allow-downgrade

dotnet 工具使用

XDev.EasyVersion

在 CI 或 CD 流水线中使用命令行工具设置 EasyVersion，传入包名（例如 "My.Custom.Package"），3 位数版本号（例如 1.2.3），以及丢弃类型（例如 alpha、beta 等，用于带有标签格式的预发布语义版本）（可选）。

对于预发布构建，选项可能如下所示
dotnet easyVersion roll --PackageName=Foo.Bar --ReleaseVersion=1.2.3 --DropType=beta --ReleaseHistoryJsonPath="./Build Tracking/Release History.json"

输出结果如下

Package Name         : Foo.Bar  
Semantic Version     : 1.2.3
Build                : beta043
Package Version      : 11.2.3-beta043  
File Version         : 11.3.3.43  
Android Version Code : 110203043  
Build Date           : 2020-06-01T16:30:03.9423513-05:00

对于发布构建，选项可能如下所示
Bloomerang.Build.Versioning.exe roll --PackageName=Foo.Bar --ReleaseVersion=1.2.3 --ReleaseHistoryJsonPath="./Build Tracking/Release History.json"

输出结果如下

Package Name         : Foo.Bar 
Semantic Version     : 1.2.3
Build                : 43
Package Version      : 11.2.3  
File Version         : 11.3.3.44  
Android Version Code : 110203044  
Build Date           : 2020-06-01T16:30:03.9423513-05:00

• 注意：构建号是连续且单调递增的，无论构建是预发布（标签）还是发布（无标签），因此可能从一系列构建结果中出现以下版本号
• 1.2.3-rc001
• 1.2.3.2
• 1.2.3-rc003

假设您想避免发布版本号比上一个版本号更高的场景，可以手动更新 BuildInfo.txt 文件中的主版本号、次版本号或修订版本号。您可以根据您的项目或首选约定自由管理何时如何滚动主版本号、次版本号和修订版本号。

根据您在流水线中保存 Release History.json 的位置，如果在使用前没有确保所有构建步骤都成功，您可能“跳过”构建号。再次强调，您控制何时将 Releas History.json 文件存储在您的构建中，因此可以“丢弃”失败的构建号，或重用构建号直到构建成功。

Android 版本码限制

根据谷歌的开发者文档，最大版本码为 2100000000。此工具可能会生成大于这个值的值。 为您的应用版本号 | Android Studio | Android 开发者

这意味着如果次版本号 > 99，以及/或者在一个语义版本中修补版本 > 99，比如 12.100.222.3 将产生版本码 12100222003，大于 2100000000，这是 Google 支持的最大值。有一个问题通过检查并附加 "-invalid" 检查和缓解此场景，但这种情况应该是很少见且易于避免的。

为了避免这种情况，限制输入的语义版本模式为 MMM.mm.pp.bbb，当通过此工具消费 Android-VersionCode 生成时，按照之前的示例。

EasyVersionRoll.ps1

此 PowerShell 脚本提供了一种简单的方式来读取 Build-Info.txt 文件中的主.次.修补版本信息，向 CLI 工具提供输入，然后将工具的输出存储到 ADO 流水线变量中，用于稍后的步骤，例如在构建之前设置 .csproj 文件或 AssemblyInfo.cs 文件中的版本信息。

• 目前仅支持 ADO，但您可以根据不同的构建托管环境轻松修改它。

对于预发布构建，调用版本脚本可能如下所示
EasyVersionRoll.ps1 -buildInfoPath "SomeDir\BuildInfo.txt" -easyVersionToolPath "SomeDir\XDev.EasyVersion.exe" -dropType "beta"

脚本将读取来自 BuildInfo.txt 的 包名 和 发布版本，调用 XDev.EasyVersion.exe 并设置参数。然后它会处理来自 XDev.EasyVersion.exe 的返回文本，并设置流水线的 AndroidVersionCode、FileVersion 和 PackageVersion 变量。

设置的 ADO 流水线变量以及后面的任务中可供使用

• AndroidVersionCode
• FileVersion
• PackageVersion