如何在build.cake中访问Team City参数及基于分支配置路径

1. 如何在build.cake中访问Team City参数？ #

Team City会自动将大部分内置参数（比如分支、构建编号等）暴露为环境变量，你可以直接在Cake脚本中通过EnvironmentVariable方法读取这些变量。另外也可以通过命令行参数的方式将Team City参数传递给Cake脚本，两种方式都可行：

方式一：读取环境变量（推荐） #

Team City的参数名称会被转换为大写，并用下划线分隔，比如%teamcity.build.branch%对应的环境变量是TEAMCITY_BUILD_BRANCH。在build.cake中这样获取：

// 获取分支参数，本地运行时用默认值"Master"兜底
var branch = EnvironmentVariable("TEAMCITY_BUILD_BRANCH") ?? "Master";

// 其他参数示例：获取构建编号
var buildNumber = EnvironmentVariable("TEAMCITY_BUILD_NUMBER") ?? "1.0.0-local";

方式二：通过命令行参数传递 #

像你尝试的那样，在Team City的构建步骤里将参数传递给build.ps1，然后在Cake脚本中用Argument方法接收：

// Cake脚本中定义参数
var branch = Argument("branch", "Master");

然后在Team City构建步骤的命令行中写：

.\build.ps1 -Branch %teamcity.build.branch%

2. 解决Team City提示需定义teamcity.build.branch且无可用代理的问题 #

你遇到的问题核心是Team City无法自动获取到分支信息，导致%teamcity.build.branch%这个内置参数未被填充，进而触发了代理分配的限制。按以下步骤排查解决：

步骤1：确保VCS根配置正确，让Team City能识别分支 #

Team City的teamcity.build.branch参数是从关联的VCS根中自动获取的，所以首先要确认你的构建配置正确关联了VCS仓库，并且分支规范设置正确：

• 进入你的Team City构建配置，切换到Version Control Settings标签页
• 检查是否已经添加了正确的VCS根（比如你的Git/SVN仓库）
• 点击VCS根的编辑按钮，找到Branch Specification（分支规范），添加合适的规则：
  • 对于Git，一般可以填+:*（表示包含所有分支）或者更具体的规则比如+:refs/heads/main、+:refs/heads/feature/*
  • 配置完成后，Team City会扫描仓库分支，自动为每个分支构建填充teamcity.build.branch参数

步骤2：调整Cake脚本或构建步骤（二选一） #

选项A：改用环境变量读取分支（更省心）

直接在build.cake中读取Team City的环境变量，不需要在命令行传递参数，这样就避开了参数未定义的问题：

var branch = EnvironmentVariable("TEAMCITY_BUILD_BRANCH") ?? "Master";

选项B：继续使用命令行参数传递

确认VCS配置正确后，Team City会自动填充%teamcity.build.branch%，此时你的构建步骤命令行.\build.ps1 ... -Branch %teamcity.build.branch%就能正常工作，不会再提示参数未定义。

步骤3：检查代理的需求设置 #

如果还是提示无可用代理，可能是代理的Agent Requirements（代理需求）中添加了分支相关的限制：

• 进入Team City的Agents页面，找到你的代理，查看其需求配置
• 检查是否有类似teamcity.build.branch equals XXX的条件，如果有且当前分支不匹配，就会导致无法分配代理，此时需要调整需求条件或者确保当前分支符合要求

内容的提问来源于stack exchange，提问作者Chris Nelson