.NET MAUI 仓库的工程基础设施eng 目录与 Arcade/darc 依赖管理实战指南【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui导读本指南以 .NET MAUI 仓库根目录下的 eng/README.md 为核心线索系统讲解 .NET MAUI 这类大型 .NET 仓库如何依托 Arcade SDK 与 darcDependency ARC工具实现跨仓库、跨生态的依赖管理与自动更新。读完本文你将掌握eng目录的角色定位、Version.Details.xml与Versions.props两个版本清单文件的内部结构、darc 客户端的本地配置方法以及add-dependency、update-dependencies、add-subscription、add-default-channel四大核心命令的完整用法并能理解构建产物如何通过 Build Asset Registry 与 channel 在 dotnet 生态中流转。一、eng目录到底是什么Arcade SDK 的一部分engengineering目录是 dotnet 生态中所有大型仓库的工程化中枢。在 .NET MAUI 仓库中它承载了构建、测试、发布、依赖管理、CI 流水线等几乎所有工程能力。根据 eng/README.md 的说明Theengfolder contains and is used by parts of the [dotnet/arcade] SDK.也就是说该目录由 Arcade SDK 提供并维护。Arcade 是 dotnet 官方构建与工程标准化 SDK它把数以百计 dotnet 仓库共用的构建逻辑工具链安装、版本管理、流水线模板、签名、发布等抽取为共享资产。当你打开仓库根目录会看到 eng/commonArcade 共享脚本与模板、eng/pipelinesCI 流水线定义、eng/cakeCake 构建脚本等子目录这些都是 Arcade 约定的标准布局。这一点在仓库中有直接证据eng/Version.Details.xml的ToolsetDependencies一节声明了Microsoft.DotNet.Arcade.Sdk版本10.0.0-beta.25523.113等一整套 Arcade 工具集依赖见 eng/Version.Details.xml而 eng/configure-toolset.sh 则体现了 Arcade 工具链安装的约定——注释明确写道不能使用已安装的 dotnet CLI因为我们需要安装额外的工作负载workloads并将useInstalledDotNetCli置为false这正是 .NET MAUI 依赖 Android/iOS/Mac Catalyst 等平台工作负载的典型场景。二、依赖管理的核心两个版本清单文件darc 的运作建立在两个关键文件之上它们是仓库与 dotnet 生态其他仓库之间依赖关系的唯一事实来源。2.1eng/Version.Details.xml依赖关系清单eng/Version.Details.xml 记录了 .NET MAUI 依赖的每个外部组件的精确版本与来源。文件分为两大节ProductDependencies产品依赖运行时与 SDK 级别的组件例如Microsoft.NET.Sdk10.0.100-rtm.25523.113来源 dotnet/dotnetMicrosoft.Android.Sdk.Windows36.1.2来源 dotnet/androidMicrosoft.iOS.Sdk.net10.0_26.0、Microsoft.MacCatalyst.Sdk.net10.0_26.0等来源 dotnet/maciosMicrosoft.NETCore.App.Ref、Microsoft.AspNetCore.*系列来源 dotnet/dotnet以及 XHarness 测试运行器系列来源 dotnet/xharnessToolsetDependencies工具集依赖构建期工具包括Microsoft.DotNet.Arcade.Sdk、Microsoft.DotNet.Build.Tasks.Feed、Microsoft.DotNet.Build.Tasks.Workloads、Microsoft.DotNet.Helix.Sdk等统一为10.0.0-beta.25523.113。每个Dependency节点包含四个关键属性属性含义示例Name依赖包名Microsoft.MacCatalyst.Sdk.net10.0_26.0Version精确版本号26.0.11017Uri上游仓库地址dotnet/maciosSha上游提交哈希23eb1c2c9465fe76c810c8a69982c1254161f4b0此外还有CoherentParentDependency属性用于表达联动版本例如.NET 9系列的Microsoft.iOS.Sdk.net9.0_26.0以Microsoft.iOS.Sdk.net10.0_26.0为父依赖确保新旧两代平台 SDK 版本同步演进。这意味着每个依赖不仅锁定版本还锁定来源提交为可复现构建与精确的自动更新提供了基础。2.2eng/Versions.propsMSBuild 版本属性eng/Versions.props 把这些依赖转换成 MSBuild 属性供构建脚本引用。文件头部定义了产品品牌版本MajorVersion10/MajorVersion MinorVersion0/MinorVersion PatchVersion110/PatchVersion SdkBandVersion10.0.100/SdkBandVersion PreReleaseVersionLabelci.main/PreReleaseVersionLabel随后是一大批*PackageVersion属性与Version.Details.xml一一对应例如MicrosoftAndroidSdkWindowsPackageVersion、MicrosoftiOSSdknet100_260PackageVersion、MicrosoftWindowsAppSDKPackageVersion1.8.260529003等。属性之间还可以互相引用例如多个MicrosoftAspNetCore*PreviousPackageVersion统一取值为上一代MicrosoftAspNetCorePackageVersion8.0.16。两个文件的分工可以这样理解Version.Details.xml面向 darc/Maestro 的机器可读依赖图Versions.props面向 MSBuild 的属性引用。darc 更新依赖时会同步修改这两份文件保证版本信息单一来源、双端一致。2.3 版本如何进入构建产物从源码结构看eng/Versions.targets 定义了SetVersionsMSBuild Target它挂接到编译与打包流程CoreCompileDependsOn、GenerateNuspecDependsOn、GetPackageVersionDependsOn并依据 CI 环境注入版本元数据PR 构建附加pr.PR号、定时构建打上nightly标签、SourceLink 附加sha.提交、Azure DevOps 构建附加azdo.构建ID。这解释了为什么每次 CI 构建产出的 NuGet 包版本都是唯一且可追溯的——这正是后续 darc/BAR 消费版本信息的前提。三、核心概念Build Asset Registry 与 Channeldarc 所管理的依赖流转建立在两个抽象之上Build Asset RegistryBAR构建资产注册表dotnet 生态的中央位置存放各仓库构建产物的元数据。构建完成后产物信息主要是 NuGet 包被推送至此。Channel渠道与 BAR 中的构建产物关联的投放目标。每个 channel 代表一条发布/消费线如.NET 6、.NET 9.0.1xx SDK它决定某个产物何时可供下游消费。其工作流程是仓库构建 → 推送产物与元数据到 BAR → 产物关联到某个 channel → 本地更新或自动订阅subscription对比仓库版本文件与目标 channel 中的可用版本 → 决定是否需要更新。darc工具正是这个流程的操纵杆。在 .NET MAUI 仓库中这一机制的落地可见于 eng/pipelines/common/sdk-insertion.yml流水线中会安装指定版本的microsoft.dotnet.darc工具然后执行darc add-build-to-channel --default-channels --id $(BARBuildId) --ci --publishing-infra-version 3 --azdev-pat $(System.AccessToken)这一步将当前构建加入其默认 channel完成构建产物入 BAR 并投放渠道的动作。而 NuGet.config 中出现的darc-pub-dotnet-dotnet-e17b0d0、dotnet-public、dotnet-eng等源正是 darc 发布流程写入的公共包源——构建时这些源保证能拿到与Version.Details.xml锁定的精确版本。四、本地配置 darc 客户端要在本地使用 darc需要完成三步初始化安装 darc 全局工具在 dotnet/arcade 仓库提供的安装脚本Arcade 文档中有详细说明指导下以 dotnet 全局工具方式安装microsoft.dotnet.darc。加入arcade-contribGitHub 团队darc 的部分操作需要该团队权限。执行darc authenticate为工具添加所需的 PATPersonal Access Token。关于 PAT 权限有一个关键约束The GitHub PAT that you add must have the fullreposcope enabled if you want to work with any of thesubcriptioncommands.即只有开启完整reposcope 的 PAT 才能操作 subscription订阅类命令因为订阅控制着依赖更新 PR 的自动创建涉及跨仓库写操作。仓库内提供了这一流程的自动化脚本佐证eng/common/darc-init.sh 从https://maestro.dot.net/api/assets/darc-version动态获取推荐版本然后执行dotnet tool install microsoft.dotnet.darc --version 版本 --add-source arcade-services源完成安装支持--darcversion、--versionendpoint、--toolpath、--verbosity等参数Windows 环境对应 eng/common/darc-init.ps1。此外 eng/common/SetupNugetSources.sh 会在构建前自动为NuGet.config补齐内部源并启用被禁用的内部 Maestrodarc-int*源为 darc 相关包源访问铺路。五、darc 核心命令实战5.1 添加新依赖darc add-dependency在仓库根目录执行为仓库注册一个新的产品依赖darc add-dependency -n Microsoft.Dotnet.Sdk.Internal -t product -v 6.0.0-preview.2.21154.6 -r https://github.com/dotnet/installer参数说明参数含义-n依赖包名Microsoft.Dotnet.Sdk.Internal-t依赖类型product产品依赖 /toolset工具集依赖-v初始版本号-r上游仓库地址命令执行后darc 会将该依赖写入eng/Version.Details.xml并同步Versions.props。注意此处仅注册依赖关系本身实际还原仍需包源可达——上文提到的NuGet.config中的darc-pub-*源即服务于这一目的。5.2 批量更新依赖darc update-dependencies当目标 channel 上有新版本时一次拉取该 channel 下的全部更新darc update-dependencies --channel .NET 6该命令对比当前Version.Details.xml与.NET 6channel 中登记的版本将可更新的依赖全部升到 channel 中的最新可用版本。这是本地按渠道升级的核心入口。5.3 配置自动更新订阅darc add-subscription将目标仓库/分支订阅到某个 channel 的更新流之后由 Maestro bot 自动接管darc add-subscription --channel .NET 6 --source-repo https://github.com/dotnet/installer --target-repo https://github.com/dotnet/maui --target-branch main --update-frequency everyWeek --standard-automerge参数含义--channel订阅的 channel 名--source-repo依赖源仓库--target-repo被更新目标仓库本例为 dotnet/maui--target-branch被更新的目标分支--update-frequency更新频率如everyWeek--standard-automerge启用标准自动合并测试通过后自动合入订阅生效后每当依赖可用更新dotnet Maestro bot 会自动创建依赖更新 PR无需人工提交。这是 .NET MAUI 这类大型仓库能够持续同步 dotnet/android、dotnet/macios 等数十个上游仓库新版本的关键机制。5.4 订阅的手动维护需要明确的是订阅目前仍需要人工管理。文档特别指出当创建新的 release 分支时拥有本地 darc 的维护者需要手动执行add-subscription命令为新分支配置更新订阅。也就是说Maestro 负责更新自动到达但订阅本身的创建与调整是人工流程的一部分。六、构建资产清单提升Build Asset Manifest Promotion与默认 Channel来自main与 release 分支的构建会把 NuGet 包元数据推送到 darc/Maestro 的 Build Asset Registry如果配置了默认 channel该构建信息还会被提升promote到默认 channel。默认 channel 同样是手动管理的。配置仓库/分支与 channel 的默认关联使用darc add-default-channeldarc add-default-channel --channel .NET 9.0.1xx SDK --branch net9.0 --repo https://github.com/dotnet/maui当新的 release 分支创建时该命令的典型形态为darc add-default-channel --channel .NET 9.0.1xx SDK Preview 1 --branch release/9.0.1xx-preview1 --repo https://github.com/dotnet/maui这样未来该分支上的每次构建都会自动进入对应的 Preview channel供订阅了该 channel 的下游仓库消费。七、反向场景让其他仓库消费 .NET MAUI 的包依赖管理是双向的。不仅 .NET MAUI 依赖上游其他产品/工具也可以反过来把 .NET MAUI 的包版本登记为依赖。eng/README.md给出的示例是darc add-dependency -n Microsoft.Maui.Sdk -t product -r https://github.com/dotnet/maui -v 1.2.3其逻辑与 5.1 节完全对称-n指定包名Microsoft.Maui.Sdk-r指向 dotnet/maui 仓库-v指定消费版本。这印证了 darc 是一个对等协作的网络——所有 dotnet 仓库既是依赖方也是被依赖方共同编织成一张可查询、可自动更新的依赖图。八、全链路串联从提交到下游自动更新的完整闭环综合以上各节.NET MAUI 仓库中一次典型的依赖更新闭环可以归纳为上游产出dotnet/android、dotnet/macios 等上游仓库完成构建。入 BAR上游构建产物元数据推送至 Build Asset Registry 并关联到对应 channel如.NET 10相关渠道。下游订阅触发Maestro 依据 eng/Version.Details.xml 中登记的订阅关系检测到 .NET MAUI 的main分支订阅了该 channel 且存在新版本。自动 PRMaestro bot 创建依赖更新 PR同步更新Version.Details.xml与 eng/Versions.props--standard-automerge使 CI 通过后自动合入。构建与发布合入后的新构建经 eng/pipelines/ci-official.yml触发分支含main、net*.0、release/*等构建产物元数据再次进入 BAR并按默认 channel 配置被提升投放供更下游的仓库消费。而版本号在这一闭环中的可追溯性由 eng/Versions.targets 的元数据注入机制pr.*/sha.*/azdo.*/nightly保证。对 .NET MAUI 这种需要同时对齐 .NET SDK、各平台 SDK、XHarness、Windows App SDK 等多个上游版本的仓库而言这套版本清单 中央注册表 渠道订阅 机器人自动 PR的体系是维持数十个依赖同步演进、同时保持构建可复现的根本保障。延伸阅读本文涉及的工程资产均在当前仓库内可继续深入eng/Version.Details.xml完整的依赖关系清单eng/Versions.props版本属性定义eng/Versions.targets版本注入 MSBuild 实现eng/common/darc-init.sh 与 eng/common/darc-init.ps1darc 客户端安装脚本eng/pipelines/common/sdk-insertion.yml构建产物入 BAR 与加入默认 channel 的流水线实现NuGet.configdarc 发布流程写入的包源配置【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考