.NET runtime 仓库包版本与程序集文件版本体系解析：构建号计算、官方构建流程与跨平台版本读取

语言运行时标准库JIT编译编译器【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址https://gitcode.com/GitHub_Trending/runtime6/runtime点击查看免费下载导读本文围绕 docs/project/versioning.md 讲述的版本化方案深入解析 .NET runtime 仓库即本仓库 runtime覆盖 coreclr、libraries、mono、installer 等子系统的统一代码库在构建时如何为托管程序集与原生二进制自动生成单调递增、可复现、无需人工登记的包版本和程序集文件版本。读完本文你将掌握 BuildNumberMajor / BuildNumberMinor 的计算规则、OfficialBuildId 在官方构建中的强制版本机制、包版本与文件版本的分隔符差异以及非 Windows 平台下读取原生二进制版本号的两种实战手段。一、版本化需求与设计约束仓库在构建时新增了包版本 程序集文件版本的一体化版本化能力且同时覆盖 Windows 与非 Windows 平台、托管managed库与原生native库。在设计这套方案时仓库方明确列出了以下约束源自 docs/project/versioning.md约束说明高于已发布版本生成版本必须高于历史上已发布过的同库版本避免版本回退支持每天多次构建一天之内要能产出多个不同版本供多次 CI/Official 构建使用版本始终递增任意两次构建的版本都必须严格单调递增方便溯源与差分小于 65535版本被用作程序集文件版本Assembly File Version其各段受unsigned short int上限约束可复现相同输入提交时间、构建号应能重现相同版本免登记nice to have最好不需要在仓库中登记一个包含版本号或修订号的文件从当前仓库的实际产物看这套约束依然成立例如 eng/Versions.props 中维护了产品品牌版本ProductVersion12.0.0、MajorVersion12、MinorVersion0、PatchVersion0以及PreReleaseVersionLabelalpha等固定基座而由构建时间派生的 BuildNumber 部分则动态计算两者拼接成最终版本。二、版本如何被计算BuildNumberMajor 与 BuildNumberMinor按文档描述最终构建版本由两段组成BuildNumberMajor与BuildNumberMinor。典型样例形如00001.01——点号前 5 位是 build number major点号后 2 位是 build number minor。00001.01 └┬─┘ └┬┘ │ └── BuildNumberMinor当日第几次构建01 起每次 1 └─────── BuildNumberMajor由 SeedDate 相对 VersionComparisonDate 推算的 5 位数字2.1 BuildNumberMajor5 位日期推算值BuildNumberMajor 用 5 位数字表示由**最新一次提交的日期SeedDate**与传入的VersionComparisonDate之间的时间差计算而来前 3 位自 VersionComparisonDate 起经过的月份数months since VersionComparisonDate后 2 位SeedDate 当月的日号day of the month。当未显式传入 VersionComparisonDate 时默认使用1996 年 4 月 1 日。选择这一基准日期的原因是确保任何基于 SeedDate 计算出的版本都会高于同库已发布的既有版本1996-04 距今足够久远月份计数值足以覆盖所有历史版本。由于该部分只依赖提交日期与固定基准日期因此这一部分是可复现的——同样的提交、同样的基准必然得到同样的 BuildNumberMajor。2.2 BuildNumberMinor当日构建序号BuildNumberMinor 表示当天这是第几次构建从01开始、每次 1。由于开发机无法获知当天在服务器上已经发生了多少次构建这一数字由官方构建official build系统计算并传入而日常开发构建如果没有手动传入则 BuildNumberMinor 恒为0。据此两类构建的典型版本形态为官方构建00001.01 5 位 major 2 位 minor 开发构建00001.0 minor 固定为 02.3 包版本与文件版本的分隔符差异包版本NuGet package version与程序集文件版本存在一个细微但关键的差异分隔符不同。程序集文件版本使用点号.分隔00001.01NuGet 包版本使用短横线-分隔00001-01。原因在于包名与文件版本各自有不同的语法要求文件版本要求数字段包版本则允许预发布标签加数字后缀。文档给出的示例文件mylibrary.dll的版本为00001.01时对应 NuGet 包名形如mylibrary.1.0.0-prerelease-00001-01.nupkg这里1.0.0-prerelease为库自身的语义化版本主体如当前仓库 eng/Versions.props 中的ProductVersion12.0.0与PreReleaseVersionLabelalpha00001-01为追加的构建标识段。三、官方构建工作流OfficialBuildId 强制指定版本官方构建与普通开发流程不同它不仅需要能强制指定 BuildNumberMinor还需要能强制指定 BuildNumberMajor。其实现方式是通过OfficialBuildId参数传入参数值的前半部分指定SeedDate即用于版本计算的最新提交日期后半部分指定当日构建修订号即 BuildNumberMinor。文档中的典型调用build.cmd -OfficialBuildId20160523.99该调用将使用 2016 年 5 月 23 日作为 SeedDate 生成版本并把99作为 BuildNumberMinor。借助这一机制官方构建的编排器orchestrator可以触发多个子构建并强制它们全部产出同一版本——这对多组件同时发布、保证包间版本一致性至关重要。在当前的 runtime 仓库中这一机制仍在使用见 eng/pipelines/common/global-build-job.yml 第 132 行官方构建流水线将 CI 的构建号直接透传为/p:OfficialBuildId$(Build.BuildNumber) /p:DotNetPublishUsingPipelinestrue ...即把 Azure DevOps 流水线生成的Build.BuildNumber形如20260523.1之类的时间戳.序号作为OfficialBuildId传给构建脚本从而让版本号完全由流水线控制、可复现且全局一致。四、非 Windows 平台读取原生二进制版本号的两种方法在非 Windows 平台上原生二进制.so等没有 Windows PE 那样的版本资源对话框可供查看文档给出了两条路线同样适用于本仓库产生的原生库如 coreclr、libcoreclr.so 等4.1 使用sccs what(1)工具what是经典的 Unix 版本标记扫描工具源自 SCCS部分系统不自带需要额外安装。安装后直接对二进制执行what myNativeNonWindowsBinary.so4.2 使用strings grep免安装如果不愿安装额外工具可以借助strings与grep扫描二进制中嵌入的版本标记strings myNativeNonWindowsBinary.so | grep (#)两种方式的原理一致构建系统会在原生二进制中嵌入以(#)开头的版本标记字符串。这一做法与本仓库 eng/native/version 目录下的版本资源生成逻辑相呼应——原生构建会生成NativeVersion.rc之类的版本资源文件其中定义了FileVersion、ProductVersion等字段见 eng/native/version/NativeVersion.rc并配合copy_version_files.ps1/copy_version_files.cmd见 eng/native/version/copy_version_files.ps1把版本头文件复制到各原生子项目参与编译。五、强制开发构建输出指定版本如果需要在本地开发构建中手动指定输出版本无需修改任何登记文件直接在仓库根目录传入 MSBuild 属性即可Windowsbuild.cmd /p:BuildNumberMajor00001 /p:BuildNumberMinor01非 Windowsbuild.sh /p:BuildNumberMajor00001 /p:BuildNumberMinor01注意参数中的/p:是 MSBuild 属性语法Windows 与 Unix 的脚本都遵循同一套属性传递方式区别仅在入口脚本名build.cmdvsbuild.sh。六、版本号的消费位置程序集文件版本与包版本计算出的版本主要在两个位置被消费程序集文件版本Assembly File Version托管程序集通过AssemblyFileVersionAttribute承载该版本该特性的定义可见 src/libraries/System.Private.CoreLib/src/System/Reflection/AssemblyFileVersionAttribute.cs。这就是为什么版本各段必须小于 65535unsigned short int上限——文件版本的四段数字都会被写入该特性对应的二进制字段。NuGet 包版本号打包时以库语义化版本 构建标识的形式写入.nupkg文件名与包元数据如mylibrary.1.0.0-prerelease-00001-01.nupkg。除这两个主消费点外仓库还通过 eng/versioning.targets 中的GenerateRuntimeVersionFile目标第 149-180 行把FileVersion、Version、MajorVersion等展开写入runtime_version.h供原生代码coreclr 运行时在运行时查询产品版本同一文件还负责为托管程序集注入AssemblyMetadataServiceableTrue、PreferInboxTrue、AssemblyDefaultAliasAttribute、NeutralResourcesLanguage等元数据以及面向 Android/iOS/tvOS/macCatalyst/browser/wasi 的SupportedPlatform/UnsupportedOSPlatform平台特性——这些都属于版本化 平台属性构建基座的组成部分。七、与当前仓库版本基座的衔接需要说明的是本文描述的 BuildNumberMajor/BuildNumberMinor 机制属于构建期自动追加的动态部分而版本的静态基座产品大版本、预发布标签等由 eng/Versions.props 定义当前仓库的关键取值如下属性当前值用途ProductVersion12.0.0.NET 产品品牌版本MajorVersion/MinorVersion/PatchVersion12/0/0三段式版本基座AssemblyVersion11.0.0.0程序集版本早期品牌阶段固定为上一主版本避免引用包与 API 兼容性抑制尚未重定向时破坏 source-build 与包校验PreReleaseVersionLabelalpha预发布标签StabilizePackageVersionfalse是否去除预发布标签置 true 时DotNetFinalVersionKindrelease动态构建号00001-01这类与上述静态基座共同拼装出最终对外可见的版本串两条链路分别满足可复现与单调递增两个约束前者由提交日期与流水线构建号保证后者由 1996-04-01 基准日期与每日递增的 minor 保证。总结runtime 仓库的版本化方案可以概括为一条公式与三条纪律公式BuildNumberMajor(5位) 自1996-04-01起的月数(3位) 当日号数(2位)BuildNumberMinor(2位) 当日构建序号两者用.拼为文件版本、用-拼为包版本后缀。纪律一开发构建 minor 恒为 0官方构建通过OfficialBuildIdSeedDate.修订号强制统一版本编排器可让多个子构建共享同一版本。纪律二需要指定版本时用build.cmd/build.sh传/p:BuildNumberMajor... /p:BuildNumberMinor...无需登记任何版本文件。纪律三非 Windows 下查原生二进制版本用what file或strings file | grep (#)。这套机制至今仍是仓库构建基座的一部分其动态计算逻辑的完整实现位于构建工具链的versioning.targets历史实现见 docs/project/versioning.md 所指向的 buildtools 仓库而当前仓库侧对应的静态基座与消费点分别在 eng/Versions.props、eng/versioning.targets 与 eng/native/version 中可作为继续深入阅读的入口。赞分享语言运行时标准库JIT编译编译器【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址https://gitcode.com/GitHub_Trending/runtime6/runtime点击查看免费下载相关推荐PuerTS for .NET NuGet 分发体系解析包结构、版本定义与构建发布全流程PuerTS for .NET NuGet 分发体系解析包结构、版本定义与构建发布全流程 PuerTS 除了以 UPM 包的形式服务 Unity 工程外还提游戏开发跨平台SpacetimeDB 官方文档仓库维护指南Docusaurus 构建、版本快照与发布全流程SpacetimeDB 官方文档仓库维护指南Docusaurus 构建、版本快照与发布全流程 导读 本文面向 SpacetimeDB 文档维护者、贡献者以及希数据库关系型数据库后端WinUI 构建版本体系全解析microsoft-ui-xaml 中的包配置、包源与 .NET/SDK 版本策略WinUI 构建版本体系全解析microsoft ui xaml 中的包配置、包源与 .NET/SDK 版本策略 本文围绕 WinUI 官方仓库micros前端UI组件桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考