使用 bicepconfig.json 中的 bicep.version 属性来声明你的 Bicep 文件支持哪些编译器版本。 你可以要求一个精确版本,或者允许指定版本范围,帮助团队保持本地开发和自动化构建的一致性。
版本固定会检查已经在运行的编译器。 该设置本身不会下载、安装或切换编译器版本。
设置编译器版本要求
{
"bicep": {
"version": "1.2.3"
}
}
该示例仅允许版本 1.2.3。 若要改为指定范围,请使用比较运算符:
{
"bicep": {
"version": ">=1.2.0, <2.0.0"
}
}
该范围允许版本大于等于 1.2.0 且小于 2.0.0。
本文中的版本号展示了语法格式。 它们不是最低支持版本,也不表示这些版本可用。 选择支持该功能和您的 Bicep 文件的已发布编译器版本。
如果未配置生效的版本要求,Bicep 就不会进行这个版本检查。 添加要求不会更改模板的资源 API 版本或固定模块注册表版本。
支持的版本语法
一个版本包含一个、两个或三个数字组成部分:主版本号、次版本号和补丁版本号。 Bicep按这个顺序对组件进行数值比较。 例如,1.10.0 大于 1.2.0。
| Syntax | Meaning |
|---|---|
1.2.3 或 =1.2.3 |
没 1.2.3错。 |
>1.2.3 |
大于 1.2.3,不包括该版本。 |
>=1.2.3 |
大于或等于 1.2.3。 |
<2.0.0 |
低于 2.0.0,不包括该版本。 |
<=2.0.0 |
小于或等于 2.0.0。 |
>=1.2.0, <2.0.0 |
两个条件都必须满足。 |
一个二条件范围必须包含一个下界(> 或 >=)和一个上界(< 或 <=)。 用逗号分隔。 任一顺序均可接受:<2.0.0, >=1.2.0 与 >=1.2.0, <2.0.0 含义相同。 条件周围以及算符与其版本之间的空格是被接受的。
简短版是精确的,不是通配符
缺失组件默认为零:
| 价值 | 等效值 |
|---|---|
1 |
1.0.0 |
1.2 |
1.2.0 |
>=1.2, <2 |
>=1.2.0, <2.0.0 |
尤其是,"1.2" 并不允许所有 1.2 补丁版本。 要允许该范围,写成 ">=1.2.0, <1.3.0"。
不支持的语法
Bicep 使用自己的数值版本约束语法。 不要假设包管理器接受的表达式在这里也能用。
| 不受支持的格式 | Examples |
|---|---|
| Wildcards |
*、1.*、1.2.x |
| 插入符或波浪号范围 |
^1.2.3、~1.2.3 |
| 可选条件或不等条件 |
1.2.3 || 2.0.0、!=1.2.3 |
| 连字符或区间范围 |
1.2.0 - 2.0.0、[1.2.0,2.0.0) |
| 版本前缀 | v1.2.3 |
| 约束中的预发布版本或构建元数据 |
1.2.3-preview、1.2.3+build |
| 重复的下界或上界 | >=1.0.0, >=1.2.0 |
| 一个精确版本加上另一个条件 | =1.2.3, <2.0.0 |
| 超过两个条件 | >=1.0.0, <2.0.0, <=1.9.0 |
| 前置零或超过三个分量 |
01.2.3、1.2.3.4 |
| 空字符串 | "" |
不支持的 bicep.version 表达式会导致 Bicep 报告 BCP273,即针对无效 Bicep 配置文件显示的现有错误。 这个诊断并非版本约束特有。 例如,"version": "^1.2.3" 会生成一条带有配置级上下文的消息,后跟具体原因:
BCP273: Failed to parse the contents of the Bicep configuration file "file:///example/bicepconfig.json": The bicep.version property "^1.2.3" is not a valid Bicep version or version range.
在这种情况下,即使版本表达式不受支持,JSON也可以是有效的。 修正 bicep.version 数值。
一个区间可以有有效的语法,但不匹配任何版本号。 例如,>=2.0.0, <1.0.0 可以被解析,但没有任何数字形式的编译器版本满足它。 同样,没有哪个版本严格介于 1.2.3 和 1.2.4之间。 有效的语法也不保证存在匹配的 Bicep 发布。
理解CLI和编辑器的行为
编译器会将其运行版本与每个源文件的有效要求进行比对。
| 条件 | Bicep CLI(命令行界面) | 编辑器中的Bicep语言服务器 |
|---|---|---|
| 运行版本满足该要求 | 没有版本不匹配诊断信息。 | 没有版本不匹配的提示。 |
| 运行版本不满足这个要求 | BCP456 是阻止成功编译的错误。 | BCP456,警告。 |
| 当前运行版本无法解析,因此无法进行比较 | BCP457,一个警告。 | BCP457,警告。 |
| 配置需求无效 | BCP273,一个配置错误。 | BCP273,一个配置错误。 |
编辑器警告并不意味着同一文件在使用不兼容的 CLI 时也能成功构建。 警告允许你继续编辑,但你仍然需要兼容的编译器来构建。
BCP457意味着该要求无法被检查,并不表示该要求已通过。 其他编译器错误和 linter 诊断仍然适用,无论版本检查结果如何。
跨文件夹和模块使用版本要求
每个 .bicep 或 .bicepparam 文件都会找到自己最近的 bicepconfig.json文件,从源文件的文件夹开始搜索父文件夹。 发现并不是从你shell当前的文件夹开始的。
本地模块使用自身的最近配置,而不是父模块已解析的设置。 一个编译器负责编译,因此该编译器必须满足所有适用要求。 Bicep 不会为每个模块选择不同的可执行文件。
例如:
project\
bicepconfig.json
main.bicep
modules\
bicepconfig.json
storage.bicep
如果根配置需要 >=1.0.0, <2.0.0 ,模块配置要求 >=1.5.0, <2.0.0,则版本 >=1.5.0, <2.0.0 满足两者。 然而,入口点仍允许那些被模块拒绝的旧版本。
两条新的 lint 规则有助于识别这些差异:
| 规则 | 默认级别 | 检查内容 |
|---|---|---|
| no-conflicting-version-constraints | Error | 入口点及其本地模块是否有共同允许的版本。 |
| no-incompatible-entrypoint-version | Warning | 入口点允许的每个版本是否也被每个受约束的本地模块允许。 |
这些是不同的检查项。 重叠的范围可以通过冲突规则,但不通过入口点兼容性规则,如前述例子所示。 将根依赖要求缩小到 >=1.5.0, <2.0.0 可解决这种不兼容。
规则遵循直接且传递的局部 module 引用。 它们不会扫描你仓库中的每个文件,也不会检查注册表和模板规范模块的内部结构。 它们不是对 import 或 .bicepparamusing 引用的通用遍历。 每条规则报告其在入口点文档起点的第一个发现,并使用该入口点的有效规则设置。
如果入口点没有要求,但本地模块有,入口点兼容性规则会警告:该入口点可能会允许模块拒绝的编译器。 没有要求的模块不会增加任何限制。
继承共享需求
父级文件夹配置文件不会自动合并。 为了共享设置同时保持更接近的配置,可以使用 配置继承。
例如,创建 shared\bicepconfig.json:
{
"bicep": {
"version": ">=1.2.0, <2.0.0"
}
}
在 app\bicepconfig.json中,扩展该文件:
{
"extends": "../shared/bicepconfig.json"
}
应用继承了共享的要求。 如果应用提供了自己的非空bicep.version字符串,该字符串将替换继承的要求;Bicep 不会对这两个字符串求交集:
{
"extends": "../shared/bicepconfig.json",
"bicep": {
"version": "1.5.0"
}
}
有效要求恰好是 1.5.0。 省略该属性会保留继承的值。 将其设置为 null 不会清除继承的非空要求。 要移除继承需求,可以更改基础配置或继承结构。
试试版本检查
以下步骤使用独立的 Bicep CLI,而非 Azure CLI 或 Azure PowerShell。
检查你直接调用的编译器:
bicep --version在测试文件旁边创建一个
bicepconfig.json文件,将bicep.version设置为已安装编译器报告的数字版本。 编译器必须支持该配置设置。创建
main.bicep:output message string = 'Version requirement example'编译该文件:
bicep build .\main.bicep匹配的版本不会产生 BCP456 诊断信息。 输出为
main.json.把已配置的要求项改成排除你正在运行的版本,然后再重新运行构建。
构建过程将 BCP456 报告为错误。 当编辑器的语言服务器编译器不满足要求时,会报告BCP456作为警告。
检查报告该诊断的工具所用的编译器。 你的编辑器和命令行工具可以使用不同的 Bicep 安装版本。
bicep --version 命令描述的是该命令解析到的可执行文件,而不是你电脑上的所有工具。
配置兼容性规则
使用现有的 linter 配置 来更改每条规则的等级:
{
"analyzers": {
"core": {
"rules": {
"no-conflicting-version-constraints": {
"level": "error"
},
"no-incompatible-entrypoint-version": {
"level": "warning"
}
}
}
}
}
支持水平为 error、 warning、 info和 off。 这些设置控制了两条兼容性规则的严重程度。
版本要求疑难解答
| 诊断或症状 | Action |
|---|---|
| BCP273 | 请查看详细配置错误信息。 如果识别 bicep.version为某个版本约束,则通过使用支持的数值版本或范围来纠正约束。 BCP273 还可以报告其他配置问题。 |
| BCP456 | 使用满足该要求的编译器,或者在检查兼容性后有意更新该要求。 请阅读消息以查找其声明配置。 |
| BCP457 | 使用其报告版本能够被解析的编译器。 不要把警告当作一次成功的兼容性检查。 |
| 版本约束冲突 | 将入口点和本地模块需求对齐,使得存在一个通用版本。 |
| 不兼容的入口点要求 | 缩小入口点的范围,或者在验证兼容性后更新模块需求,确保所有允许的入口点版本都与模块兼容。 |
| 编辑和CLI意见不合 | 检查每个工具使用的编译器版本以及相关文件的就近配置。 |
如果约束冲突,单靠安装另一个编译器无法解决问题:没有单一版本满足所有要求。