dotnet-ado-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dotnet-ado-patterns

.NET项目Azure DevOps流水线模式

Composable Azure DevOps YAML pipeline patterns for .NET projects: template references with

extends

stages

jobs

, and

steps

keywords for hierarchical pipeline composition, variable groups and variable templates for centralized configuration, pipeline decorators for organization-wide policy injection, conditional insertion with

${{ if }}

and

${{ each }}

expressions, multi-stage pipelines (build, test, deploy), and pipeline triggers for CI, PR, and scheduled runs.

Version assumptions: Azure Pipelines YAML schema.

DotNetCoreCLI@2

task for .NET 8/9/10 builds. Template expressions syntax v2.

适用于.NET项目的可组合Azure DevOps YAML流水线模式：使用

extends

、

stages

、

jobs

和

steps

关键字实现分层流水线组合的模板引用，用于集中配置的变量组和变量模板，用于组织级策略注入的流水线装饰器，通过

${{ if }}

和

${{ each }}

表达式实现的条件插入，包含构建、测试、部署的多阶段流水线，以及用于CI、PR和定时运行的流水线触发器。

版本说明： Azure Pipelines YAML 架构。使用

DotNetCoreCLI@2

任务构建.NET 8/9/10项目。模板表达式语法为v2版本。

Scope

适用范围

Template references with extends, stages, jobs, and steps keywords
Variable groups and variable templates for centralized configuration
Pipeline decorators for organization-wide policy injection
Conditional insertion with ${{ if }} and ${{ each }} expressions
Multi-stage pipelines (build, test, deploy)
Pipeline triggers for CI, PR, and scheduled runs

使用extends、stages、jobs和steps关键字的模板引用
用于集中配置的变量组和变量模板
用于组织级策略注入的流水线装饰器
通过
```
${{ if }}
```
和
```
${{ each }}
```
表达式实现的条件插入
多阶段流水线（构建、测试、部署）
用于CI、PR和定时运行的流水线触发器

Out of scope

不适用范围

Starter CI templates -- see [skill:dotnet-add-ci]
CLI release pipelines (tag-triggered build-package-release for CLI tools) -- see [skill:dotnet-cli-release-pipeline]
ADO-unique features (environments, service connections, classic releases) -- see [skill:dotnet-ado-unique]
Build/test specifics -- see [skill:dotnet-ado-build-test]
Publishing pipelines -- see [skill:dotnet-ado-publish]
GitHub Actions workflow patterns -- see [skill:dotnet-gha-patterns]

Cross-references: [skill:dotnet-add-ci] for starter templates that these patterns extend, [skill:dotnet-cli-release-pipeline] for CLI-specific release automation.

For detailed YAML examples (stage/job/step templates, extends, variable groups, conditional insertion, multi-stage pipelines, triggers), see

examples.md

in this skill directory.

入门级CI模板——请查看[skill:dotnet-add-ci]
CLI工具发布流水线（基于标签触发的构建-打包-发布流程）——请查看[skill:dotnet-cli-release-pipeline]
Azure DevOps独有功能（环境、服务连接、经典发布）——请查看[skill:dotnet-ado-unique]
构建/测试细节——请查看[skill:dotnet-ado-build-test]
发布流水线——请查看[skill:dotnet-ado-publish]
GitHub Actions工作流模式——请查看[skill:dotnet-gha-patterns]

交叉引用：[skill:dotnet-add-ci]提供了本模式所基于的入门模板，[skill:dotnet-cli-release-pipeline]针对CLI工具提供了专属的发布自动化方案。

如需详细的YAML示例（阶段/作业/步骤模板、extends、变量组、条件插入、多阶段流水线、触发器），请查看本skill目录下的

examples.md

文件。

Agent Gotchas

Agent注意事项

Template parameter types are enforced at compile time -- passing a string where
```
type: boolean
```
is expected causes a validation error before the pipeline runs; always match types exactly.
extends
templates cannot be overridden -- callers cannot inject steps before or after the mandatory stages; this is by design for policy enforcement.
Variable group secrets are not available in template expressions --
```
${{ variables.mySecret }}
```
resolves at compile time when secrets are not yet available; use
```
$(mySecret)
```
runtime syntax instead.
${{ each }}
iterates at compile time -- the loop generates YAML before the pipeline runs; runtime variables cannot be used as the iteration source.
CI and PR triggers are mutually exclusive with
trigger: none
and
pr: none
-- omitting both
```
trigger
```
and
```
pr
```
sections enables default CI triggering on all branches; explicitly set
```
trigger: none
```
to disable.
Path filters in triggers use repository root-relative paths -- do not prefix paths with
```
/
```
or
```
./
```
; use
```
src/**
```
not
```
./src/**
```
.
Scheduled triggers always run on the default branch first -- the
```
branches.include
```
filter applies after the schedule fires; the schedule itself is only evaluated from the default branch YAML.
Pipeline resource triggers require the source pipeline name, not the YAML file path -- use the pipeline name as shown in ADO, not the
```
azure-pipelines.yml
```
file path.

模板参数类型在编译时强制执行——如果在需要
```
type: boolean
```
类型的位置传入字符串，会在流水线运行前触发验证错误；请确保参数类型完全匹配。
extends
模板无法被覆盖——调用方无法在强制要求的阶段前后注入步骤；这是为了策略管控而设计的。
变量组中的机密信息无法在模板表达式中使用——
```
${{ variables.mySecret }}
```
在编译时解析，此时机密信息尚未可用；请改用
```
$(mySecret)
```
运行时语法。
${{ each }}
循环在编译时执行——循环会在流水线运行前生成YAML内容；运行时变量不能作为迭代源。
CI和PR触发器与
trigger: none
和
pr: none
互斥——如果同时省略
```
trigger
```
和
```
pr
```
配置段，会启用所有分支的默认CI触发；如需禁用请显式设置
```
trigger: none
```
。
触发器中的路径筛选器使用相对于仓库根目录的路径——不要给路径添加
```
/
```
或
```
./
```
前缀；请使用
```
src/**
```
而非
```
./src/**
```
。
定时触发器始终先在默认分支上运行——
```
branches.include
```
筛选器在定时任务触发后生效；定时任务本身仅从默认分支的YAML文件中读取配置。
流水线资源触发器需要指定源流水线的名称，而非YAML文件路径——请使用Azure DevOps中显示的流水线名称，而非
```
azure-pipelines.yml
```
文件路径。