Aspire 内部 Azure DevOps 流水线实战指南触发、监控与安全验证 dnceng/internal 构建【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本指南系统讲解 .NET Aspire 开源仓库microsoft/aspire内部 Azure DevOps 流水线的完整操作流程涵盖内部镜像仓库的分支推送、通过 Azure CLI 手动触发microsoft-aspiredefinition 1602构建、构建状态监控以及发布/发布相关变更的安全验证方法论。读完本文你将掌握在个人功能分支上测试流水线改动、用DryRun模式零副作用验证发布路径、以及快速定位阶段跳过的完整实战能力。本文以仓库内 .agents/skills/azdo-internal/SKILL.md 为骨架结合 eng/pipelines/azure-pipelines.yml、eng/pipelines/release-publish-nuget.yml 等真实流水线定义展开。一、总体架构GitHub 仓库与内部 AzDO 镜像Aspire 的正式代码托管在 GitHub 的microsoft/aspire但它同时维护着一个位于 Azure DevOpsdnceng组织internal项目下的内部镜像仓库。内部流水线在该镜像上运行产出包括native CLI 编译产物osx/linux/windows 各 RID 的二进制归档以及安装包准备WinGet 清单与 Homebrew Cask。以下是关键信息速查表项目值AzDO 组织/项目dnceng/internal流水线定义 ID1602流水线名称microsoft-aspire内部 Git 仓库https://dev.azure.com/dnceng/internal/_git/microsoft-aspireGit Remote 名称任意以git remote -v \| grep internal/_git/microsoft-aspire实际发现为准示例中以INTERNAL_REMOTE占位流水线 URLhttps://dev.azure.com/dnceng/internal/_build?definitionId1602流水线 YAMLeng/pipelines/azure-pipelines.yml相关流水线一览除主流水线外仓库还维护着一组配套定义流水线定义 IDYAML用途microsoft-aspire主1602eng/pipelines/azure-pipelines.yml官方内部构建PR CImicrosoft-aspire unofficial需动态发现eng/pipelines/azure-pipelines-unofficial.yml非官方/开发构建unofficial 流水线的定义 ID 未被硬编码因为它可能变动可通过以下命令动态发现az pipelines list --organization https://dev.azure.com/dnceng --project internal \ --query [?contains(name,aspire)].{name:name,id:id} -o table关于 Shell 环境的说明本文示例命令使用 bash 编写。在 Windows 上请改用pwsh或 Git Bash 执行——az、git、gh均为跨平台工具差异只在于 Shell 胶水语法。常用 PowerShell 等价写法cmd /dev/null 21→cmd * $nullcmd || echo msg→cmd; if (-not $?) { Write-Host msg }git remote -v | grep internal→git remote -v | Select-String internalgrep 作业日志 → 将日志管道给Select-String二、前置条件环境自检与权限确认触发或查询构建前必须先确认环境就绪。建议在任何命令可能报错之前尽早失败Fail early而不是等到执行到一半才暴露问题# 1. 确认 Azure CLI 已安装 az version /dev/null 21 || echo az CLI not installed # 2. 确认 azure-devops 扩展已安装提供 az pipelines / az devops 子命令 az extension show --name azure-devops /dev/null 21 || az extension add --name azure-devops # 3. 确认已认证到 dnceng 组织交互式登录或设置 AZURE_DEVOPS_EXT_PAT az devops project show --project internal --organization https://dev.azure.com/dnceng /dev/null 21 \ || echo Not authenticated to dnceng/internal — run az login or set AZURE_DEVOPS_EXT_PAT权限边界dnceng/internal是微软内部组织。如果用户没有访问权限应当立即停止并明确告知——外部无法触发该构建。不要在认证错误上反复循环尝试。三、向内部仓库推送分支内部 AzDO 仓库镜像自 GitHub。要为一个手动构建推送分支只需将本地分支推送到内部 remote# 将本地分支推送到内部 remoteremote 名以实际配置为准 git push INTERNAL_REMOTE local-branch:remote-branch-name # 示例使用你自己的别名作为分支前缀 git push INTERNAL_REMOTE fix-azdo-pr-build:your-alias/fix-azdo-pr-build如果本地还没有指向内部仓库的 remote可以添加一个名称随意git remote add INTERNAL_REMOTE https://dncengdev.azure.com/dnceng/internal/_git/microsoft-aspire分支规则重要只允许推送/构建个人分支例如your-alias/branch。内部镜像强制执行分支策略main和release/*受策略门控——直接推送或强推会被拒绝需要走 PR因此不要用它们作为临时验证分支如果触发的构建迟迟不启动或推送被拒原因通常是分支不在流水线分支控制范围内而不是你的 YAML。此时应切换到your-alias/...分支重试。这一规则与主流水线的触发器配置相互印证查看 eng/pipelines/azure-pipelines.yml 可以看到trigger仅包含main*、release/*、internal/release/*pr触发器包含main*、release/*、feature/*、internal/release/*而个人别名分支不属于任何内置匹配模式。四、触发流水线通过 Azure CLI 手动触发首选方式# 在指定分支上触发构建 az pipelines run \ --id 1602 \ --organization https://dev.azure.com/dnceng \ --project internal \ --branch branch-name # 示例 az pipelines run \ --id 1602 \ --organization https://dev.azure.com/dnceng \ --project internal \ --branch your-alias/fix-azdo-pr-build命令返回包含构建详情的 JSON其中包括id构建 ID和url。从源码看主流水线还暴露了两个可在触发时控制的参数eng/pipelines/azure-pipelines.ymlpackageVSCodeExtensionAsPreRelease布尔默认false控制 VS Code 扩展是否按预发布版本打包会透传到独立的build_extension阶段aspireCliChannelOverride字符串默认auto可选auto/stable/staging/daily覆盖烘焙进 native CLI 二进制的 Aspire 频道。默认auto会根据Build.Reason与Build.SourceBranch推导release/*与internal/release/*分支始终解析为staging避免稳定化 dogfood 构建被误标为stable。从release/*分支发起正式 GA 发布构建时应显式设为stable使分发二进制标识为稳定版并让aspire init写出仅指向 nuget.org 的 nuget.config。五、流水线结构速览不要依赖本文的快照——阶段、作业条件与变量会持续演进。始终以仓库中的实时定义为准eng/pipelines/azure-pipelines.yml —— 阶段stages、作业jobs、门控条件eng/pipelines/templates/ —— 各作业的步骤模板eng/pipelines/scripts/ —— 这些步骤实际运行的脚本以当前源码为例主流水线的阶段拓扑可以概括为仅作理解参考build_sign_native—— 三组并行的 native 编译签名作业macOS/linux/Windows产出各 RID 的 CLI 归档与 nupkglinux-x64 作业末尾通过ComputeVars步骤计算安装包所需版本变量build_extension—— 独立编译/签名 VS Code 扩展 VSIXdependsOn: []与其余阶段并行source_index—— 仅main分支编译时注入独立的完整重建以生成 source.dot.net 索引dependsOn: []不阻塞发布路径build—— 托管构建/签名/打包与模板测试产物通过managed_packages_shipping、managed_dashboard_artifacts两个 pipeline artifact 交接给下游template_tests—— 依赖build验证打包的 Aspire.* nupkg 能产出可用的aspire new项目质量门但不阻塞 assembleassemble—— 汇聚 native 归档 托管包 VSIX Dashboard zip执行统一的-publish生成覆盖全部产出的 BAR AssetManifest并附有AssetManifest 非平凡健全性检查prepare_installers—— 依赖build_sign_native而非 assemble生成 WinGet 清单、Homebrew Cask 并执行 npm 安装验证产物供发布流水线消费。要弄清某次具体构建中某个阶段/作业为何运行或被跳过必须读取构建的 timeline——az pipelines build show --id BUILD_ID只返回总体状态/结果不包含逐任务记录。应直接查询 timeline 资源az devops invoke --area build --resource Timeline \ --route-parameters projectinternal buildIdBUILD_ID \ --org https://dev.azure.com/dnceng或打开构建的 Web UI真正求值生效的条件就在 YAML 里。六、监控构建构建结果 URLhttps://dev.azure.com/dnceng/internal/_build/results?buildIdBUILD_ID通过 Azure CLI 监控# 查看构建状态 az pipelines build show \ --id BUILD_ID \ --organization https://dev.azure.com/dnceng \ --project internal # 列出该流水线最近的构建 az pipelines build list \ --definition-ids 1602 \ --organization https://dev.azure.com/dnceng \ --project internal \ --top 5 # 列出特定分支的构建 az pipelines build list \ --definition-ids 1602 \ --organization https://dev.azure.com/dnceng \ --project internal \ --branch refs/heads/your-alias/fix-azdo-pr-build \ --top 5七、常见任务实战7.1 在功能分支上测试流水线改动# 1. 推送到内部 remote仅限个人分支——见分支规则 git push INTERNAL_REMOTE my-branch:your-alias/my-branch # 2. 触发构建 az pipelines run --id 1602 --organization https://dev.azure.com/dnceng --project internal --branch your-alias/my-branch # 3. 监控构建 ID 取自步骤 2 输出 az pipelines build show --id BUILD_ID --organization https://dev.azure.com/dnceng --project internal --query {status:status,result:result,sourceBranch:sourceBranch}7.2 监控长时间运行的构建az没有az pipelines watch命令。对长构建不要在前台循环轮询——应运行一个独立的、分离的后台 watcher周期性轮询az pipelines build show将状态写入文件并在完成时发出通知。轮询应关注构建的status/result字段而不是抓取日志。7.3 个人分支上的验证边界哪些无法完整验证某些阶段只在main/release/*上运行在your-alias/...分支上会被跳过或失败因此无法通过个人分支验证发布/发布阶段NuGet 推送、WinGet/Homebrew PR 提交在发布流水线中运行不在功能分支 CI 上读取publish-build-assets变量组的步骤在非main/非release/*分支上会失败——按 Arcade 约定该变量组只为非 PR 官方分支拉取功能分支构建本就无法访问。这在主流水线源码中有直接对应assemble阶段仅在main、release/*、internal/release/*分支上启用enablePublishBuildAssetseng/pipelines/azure-pipelines.yml。因此验证流水线改动前要先确认你要测的路径在个人分支上是否可达如果不可达就按下一节的方式安全地验证机制本身而不是在发布分支上真实跑一遍。7.4 安全验证仅发布/发布相关的改动当改动只影响main/release/*路径发布、NuGet 推送、WinGet/Homebrew PR 提交、发布通知时必须在不产生真实副作用的前提下验证机制。绝不允许发布步骤或 PR 提交步骤在验证期间真实运行。按优先级推荐三种方式方式 1以DryRuntrue运行发布流水线首选发布流水线eng/pipelines/release-publish-nuget.yml暴露了DryRun运行时参数其默认值为false即真实运行——所以必须显式传入az pipelines run --id RELEASE_PIPELINE_ID \ --organization https://dev.azure.com/dnceng --project internal \ --branch your-alias/branch \ --parameters DryRuntrue在源码中DryRun门控着真实的发布动作NuGet 发布只在DryRunfalse时走1ES.PublishNuget1任务DryRuntrue时仅列出将发布的包清单npm 相关步骤同样被DryRun分支控制ESRP 签名/发布、gh release上传eng/pipelines/scripts/publish-release-cli-assets.ps1 的-DryRunswitch、WinGet/npm 发布步骤均受该标志门控。因此整条路径会端到端跑通而不推送任何东西。务必从日志确认 dry-run 确实生效不要想当然。相关脚本会打印标识在作业日志中 grepDryRun: True # publish-release-cli-assets.ps1 Dry Run: true # release-publish-nuget.yml如果看不到该输出就把步骤当作真实运行处理。历史上曾出现过畸形-DryRun参数静默按位置绑定、对错误目标真实运行的事故——以日志为准不要相信意图。方式 2抽取步骤脚本本地运行把步骤涉及的脚本抽出来用测试输入加-DryRun在本地执行。最适合改动的是脚本逻辑版本计算、manifest/cask 生成、通知而非 YAML 装配的场景——不跑流水线、无副作用、迭代最快。方式 3只测门控不测效果如果改动只影响阶段何时运行就在有代表性的分支上触发构建通过构建 timeline 检查哪些阶段被调度、哪些被跳过。发布动作本身完全不需要触发。明确禁止不要通过把发布目标改指向个人 fork / 测试 feed / 测试仓库来验证——一旦配置错误就会命中真实目标而这正是你要避免的副作用。7.5 将流水线精简为单个作业scratch worktree要快速迭代某个作业自身的机制最有效的办法是临时把流水线精简到只剩该作业移除其他阶段、去掉dependsOn、把门控条件硬编码为true。务必在独立 worktree 中的一次性分支上操作保证被掏空的 YAML 永远不会进入你的真实 PRgit worktree add ../azdo-scratch -b your-alias/azdo-scratch # 将 eng/pipelines/azure-pipelines.yml 精简到只剩一个作业提交然后 git push INTERNAL_REMOTE your-alias/azdo-scratch:your-alias/azdo-scratch az pipelines run --id 1602 --organization https://dev.azure.com/dnceng --project internal --branch your-alias/azdo-scratch注意事项精简后的作业只能验证该作业自身的逻辑而非其集成——剥离上游阶段会丢失它本应接收的变量和产物所以这里通过不代表完整运行一定通过合并前仍需端到端重验装配关系精简时保留作业自身的 setup 步骤restore 等完成后清理现场删除 worktree并在内部 remote 上删除 scratch 分支精简后的 YAML 不在你的 PR 中因此要在 PR 描述里注明你验证了什么并附上构建链接。八、发布流水线参数速查DryRun 之外验证发布路径时eng/pipelines/release-publish-nuget.yml 还提供了一批Skip*高级参数用于部分失败后的重跑与发布编排均默认false参数说明ReleaseVersion发布版本默认auto从源构建的release-version - *标签自动推导IsPrerelease是否为预览/预发布版本DryRun是否跳过实际发布默认false验证时必须显式传trueGaChannelNamedarc 升级目标频道默认Aspire 9.x GA历史命名勿改SkipNuGetPublish/SkipNpmRidPublish/SkipNpmPointerPublish/SkipChannelPromotion/SkipWinGetPublish/SkipGitHubTasks/SkipReleaseAssets/SkipNixPackageUpdate各类发布的跳过开关重跑与裁剪用SkipVSCodeExtensionPublish默认trueVS Code 扩展发布默认关闭NpmPublishOwners/NpmPublishApproversnpm ESRP 所有者/审批者别名必须为指定微软别名且不可相同注意源码中一个重要的安全设计当DryRunfalse且IsPrereleasetrue时npm 发布会被硬阻断因为 MicroBuild npm 发布模板尚不支持 dist-tag 参数预发布构建要验证 npm 路径必须用DryRuntrue。九、总结处理 Aspire 内部 AzDO 流水线时核心原则可以归纳为四条只推个人分支your-alias/...是唯一合法的临时验证分支main/release/*受策略门控先确认环境再动手az CLI、azure-devops 扩展、dnceng 认证三项缺一不可且内部组织权限是硬边界发布路径一律 DryRun 验证DryRun默认false必须显式传true并以作业日志中的DryRun: True/Dry Run: true标记为准读 timeline 而非只看 headline阶段为何运行或跳过答案在构建 timeline 与 YAML 的求值条件里。这套方法论同样适用于其他基于 Arcade 1ES 的 .NET 仓库内部流水线运维。深入阅读流水线定义可继续查看 eng/pipelines/azure-pipelines.yml、eng/pipelines/release-publish-nuget.yml、eng/pipelines/templates/ 及 eng/pipelines/scripts/ 下的脚本实现。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考