XDev.EasyVersion 1.0.0.1

这仍然是一个正在进行中的工作

目录

• 简介
  • 支持文件
  • dotnet 工具 ##todo: 更新目录!

简介

自动创建构建版本的同时保持语义版本规则的可选性，当尝试通过足够灵活的方法来适应不同的版本和命名规则时，会迅速变得复杂。此仓库包含了一系列工具，以帮助您构建最少需要环境特定脚本的可靠的 CI/CD 流程。唯一的实际要求是 CLI 工具需要 .NET 6 或更高版本的运行时，或者您可以使用 Cake 构建来导入 XDev.EasyVersion.Core 或其他包直接。

此项目包含的版本概念是，所有可发布的产品都应有唯一的版本号，该版本号不会在单独的构建中重复。此外，版本号是作为 CI/CD 流程的一部分生成的，而不是手动分配。这2个规则允许我们生成适用在语义版本方案中的人类可读的唯一构建号，无需担心在构建各种代码库（如 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 文件提供了2个关键信息，即语义形式（主.minor.修订）中的 包名 和 发布版本，将由仓库所有者手动增加。

包名

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

发布版本

这是软件包的主要版本号、次要版本号和修补程序版本号的语义版本号。这种表示法来源于Nuget指南，它还允许CI-CD流水线自动增加用于文件版本化的第4个八位字节。您可以使用您选择的任何3个八位字节版本号方案，例如主要版本号.次要版本号.修补程序版本号，主要版本号.次要版本号.修订号，年度.季度.修补程序版本号等。只需记住，修改Build Information.txt是更新前3个八位字节所必需的，并且非常适合与CI-CD DevOps配合使用的Git-Flow分支合并策略，在一个或多个长期分支上自动构建，例如dev和main或您可能称呼的其他分支。

发布历史记录.json

此文件与源代码分开存储，并跟踪特定机构库中所有构建和发布。此文件的 присутствие给予构建过程生成独特版本号的能力，这些版本号易于阅读，无需在版本号中包含一些日期码或长哈希码。构建历史和构建代码的CM的一个非常流行的选择是将其存储在源代码仓库中。这是一个非常简单且容易的选择，如果不想“混合”构建代码和源代码，并且如果您的开发团队也负责DevOps。然而，这确实引入了某些困难，例如，现在必须对历史文件/目录进行commit以更新历史记录的任何构建，可能引发递归构建场景，除非将历史文件/目录排除在自动构建触发器之外，以及在对其他受保护分支引入未经审查的更改。

作者认为，以下是一些更好的CM选择，因为它们允许CI-CD和源代码之间的关注点分离

• 在本地构建机器上，只需将此文件保存在构建代理（运行器）可访问的位置
• 将此文件保存在git子仓库中，并在构建中添加步骤，以在构建开始时拉取正确的子仓库，并且只向负责构建历史的子仓库提交更改
• 如果您使用Azure Devops，通用软件包是保持构建之间版本化项目的一个简单方法，包括代码覆盖率结果或我们的发布历史记录.json文件。
• 最后，如果没有其他选项可用或符合您的要求，XDev.EasyVersion.Nuget.History可以提供一个几乎与ADO的通用软件包一样简单的工具，但是使用Nuget作为打包工具。

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

##待办事项：添加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 的位置，如果在前所有构建步骤成功之前保存 Release History.json，则可能会出现“跳过”的构建号码。同样，您控制何时将 Release History.json 文件存储在您的构建中，因此可以“丢弃”失败的构建号码或重用构建号码，直到构建成功。

Android VersionCode 限制

根据谷歌的开发者文档，最大 VersionCode 是 2100000000。此工具可能生成大于此的值。 版本化您的应用程序 | Android Studio | Android 开发者

这意味着，如果次要版本 > 99，并且/或者语义版本（如 12.100.222.3）中的补丁版本 > 99，则此工具 可能 生成无效的 AndroidVersion 代码，版本码将为 12100222003，这 > 2100000000，这是谷歌支持的最大值。存在一个问题，通过检查并附加 "-invalid" 来减轻这种场景，但这应该是一个罕见且容易避免的情况。

为了避免这种情况，请在通过此工具生成 Android-VersionCode 时，将输入的语义版本限制为 MMM.mm.pp.bbb 模式，如前面的示例所示。

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 的返回文本，并设置 Pipeline 的 AndroidVersionCode、FileVersion 和 PackageVersion 变量。

设置并可用于管道中后续任务的 ADO 管道变量

• AndroidVersionCode
• FileVersion
• PackageVersion