配置 Bicep 环境

Bicep 支持名为 bicepconfig.json 的可选配置文件。 在此文件中,可以添加用于自定义 Bicep 开发体验的值。 此文件已与默认配置文件合并。 有关详细信息,请参阅了解合并过程。 要自定义配置,可以在 Bicep 文件的同一目录或父目录中创建配置文件,或者在运行 Bicep CLI 命令时使用 --config 传递配置文件路径。 如果有多个包含 bicepconfig.json 文件的父目录,Bicep 将使用最邻近的父目录中的配置。 有关详细信息,请参阅了解文件解析过程。

要配置 Bicep 扩展设置,请参阅 Visual Studio Code 和 Bicep 扩展。

在 Visual Studio Code 中创建配置文件

可以使用任何文本编辑器来创建配置文件。

若要在 Visual Studio Code 中创建 bicepconfig.json 文件,请打开命令面板 ([CTRL/CMD][SHIFT]P),然后选择“Bicep: 创建 Bicep 配置文件”++。 有关详细信息,请参阅创建 Bicep 配置文件。

如何在Visual Studio Code中创建Bicep配置文件的屏幕截图。

Visual Studio Code 的 Bicep 扩展支持对 bicepconfig.json 文件提供 IntelliSense。 使用 IntelliSense 发现可用的属性和值。

支持 _bicepconfig.json_ 文件配置的 IntelliSense 的屏幕截图。

了解合并过程

bicepconfig.json 文件使用默认配置文件执行自下而上的递归合并过程。 在合并过程中,Bicep 会检查这两个配置中的每个路径。 如果默认配置中不存在路径,则路径及其关联值将添加到最终结果中。 相反,如果默认配置中存在具有不同值的路径,则 bicepconfig.json 中的值会在合并结果中优先。

假设默认配置的定义如下:

{
  "cloud": {
    ...
    "credentialPrecedence": [
      "AzureCLI",
      "AzurePowerShell"
    ]
  },
  "moduleAliases": {
    "ts": {},
    "br": {
      "public": {
        "registry": "mcr.microsoft.com",
        "modulePath": "bicep"
      }
    }
  },
  ...
}

bicepconfig.json 的定义如下:

{
  "cloud": {
    "credentialPrecedence": [
      "AzurePowerShell",
      "AzureCLI"
    ]
  },
  "moduleAliases": {
    "br": {
      "ContosoRegistry": {
        "registry": "contosoregistry.azurecr.io"
      },
      "CoreModules": {
        "registry": "contosoregistry.azurecr.io",
        "modulePath": "bicep/modules/core"
      }
    }
  }
}

生成的合并配置将为:

{
  "cloud": {
    ...
    "credentialPrecedence": [
      "AzurePowerShell",
      "AzureCLI"
    ]
  },
  "moduleAliases": {
    "ts": {},
    "br": {
      "public": {
        "registry": "mcr.microsoft.com",
        "modulePath": "bicep"
      },
      "ContosoRegistry": {
        "registry": "contosoregistry.azurecr.io"
      },
      "CoreModules": {
        "registry": "contosoregistry.azurecr.io",
        "modulePath": "bicep/modules/core"
      }
    }
  },
  ...
}

在前面的示例中,cloud.credentialPrecedence 的值被替换,同时 cloud.moduleAliases.ContosoRegistry 和 cloud.moduleAliases.CoreModules 的值在合并配置中追加。

了解文件解析过程

bicepconfig.json 文件可以放置在 Bicep 文件的同一目录或父目录中。 如果有多个包含 bicepconfig.json 文件的父目录,Bicep 将使用最邻近的父目录中的配置文件。 例如,在给定的文件夹结构中,每个文件夹都有一个 bicepconfig.json 文件:

显示解析多个父文件夹中找到的 _bicepconfig.json_ 文件的关系图。

如果在 文件夹中编译 main.bicep,则将使用 child 文件夹中的 bicepconfig.json 文件。child 将忽略 parent 文件夹和 root 文件夹中的配置文件。 如果 child 文件夹不包含配置文件,则 Bicep 会在 parent 文件夹中搜索配置,然后在 root 文件夹中搜索。 如果未在任何文件夹中找到配置文件,则 Bicep 会默认使用默认值。

对于调用多个模块的 Bicep 文件,每个模块都会使用最近的 bicepconfig.json 进行编译。 然后,主 Bicep 文件会通过其对应的 bicepconfig.json 进行编译。 在以下方案中,modA.bicep 使用 文件夹中的 bicepconfig.json 进行编译,A 使用 modB.bicep 文件夹中的 bicepconfig.json 进行编译,最后,main.bicep 使用 文件夹中的 bicepconfig.json 进行编译。Broot

显示模块方案的多个父文件夹中找到的 _bicepconfig.json_ 文件的关系图。

如果 和 A 文件夹中没有 bicepconfig.json 文件,则所有三个 Bicep 文件都使用 B 文件夹中找到的 bicepconfig.json 进行编译。root 如果 bicepconfig.json 不存在于任何文件夹中,则编译会默认使用默认值。

配置编译器版本要求

用 bicep.version 在 bicepconfig.json 中声明精确的编译器版本或允许的范围。 Bicep 会根据该要求检查正在运行的编译器;该设置本身不会安装或切换版本。

有关支持的语法、示例、CLI 和编辑器行为以及故障排除,请参见配置 Bicep 编译器版本要求。

在 Bicep CLI 中指定配置文件

从 Bicep CLI v0.49 开始,你可以向 Bicep CLI 命令传递 --config <path> 以使用特定的配置文件,而不是通过自动发现 bicepconfig.json。 当您需要环境特定设置(例如测试和生产环境分别使用的独立模块注册表)或 CI/CD 流水线中的中央配置时,这个选项非常有用。

<path> 可以是具有任何文件名的绝对或相对本地文件路径。 当你指定 --config 时,Bicep 会为命令过程中加载的每个源文件使用该文件——包括入口文件、引用的本地模块和 .bicepparam 文件的 using 目标。 目录层级中的任何 bicepconfig.json 文件都被忽略,除非指定的配置文件通过 extends 继承这些文件。

以下示例使用 bicepconfig.prod.json 扩展基础 bicepconfig.json 文件并覆盖生产构建的模块注册表别名:

{
  "extends": "./bicepconfig.json",
  "moduleAliases": {
    "br": {
      "shared": {
        "registry": "contosoprodregistry.azurecr.io",
        "modulePath": "bicep/modules"
      }
    }
  }
}

使用 --config 运行 bicep build 或 bicep lint 以应用配置文件:

bicep build ./main.bicep --config ./bicepconfig.prod.json
bicep lint ./services/api/main.bicep --config ./eng/common/bicepconfig.json

使用 --config时请记住以下行为:

  • 支持的命令:build、format、publish、publish-extension、lint、generate-params、snapshot、build-params、restore、test、deploy、what-if、local-deploy、teardown、console和docs generate。
  • 缺少文件错误:如果 <path> 处的文件不存在,命令会立即失败并显示 Could not find configuration file "<path>".,而不是回退到目录发现。
  • 编辑器行为:--config 选项仅适用于 Bicep CLI 命令。 Visual Studio Code 的 Bicep 扩展继续使用自动发现 bicepconfig.json。
  • Azure CLI:像az bicep build这样的az bicep命令尚不支持--config。 使用az bicep run(Azure CLI 2.88.0或更高版本)直接将命令传递给Bicep CLI,例如az bicep run --command "build main.bicep --config ./bicepconfig.prod.json"。 Azure CLI 使用的 Bicep CLI 必须是 v0.49 或更高版本。 若要更新它,请运行 az bicep upgrade。

配置 Bicep 模块

使用模块时,可以为模块路径添加别名。 这些别名可简化 Bicep 文件,因为不必重复复杂的路径。 还可以配置云配置和凭据优先级,以便在 Bicep CLI 和 Visual Studio Code 中向 Azure 进行身份验证。 凭据用于将模块发布到注册表,并在使用 insert 资源函数时将外部模块还原到本地缓存。 有关详细信息,请参阅将模块设置添加到 Bicep 配置中。

配置 Linter 规则

Bicep Linter 会检查 Bicep 文件是否存在语法错误以及是否违反最佳做法。 可以修改 bicepconfig.json 文件以替代 Bicep 文件验证方式的默认设置。 有关详细信息,请参阅将 Linter 设置添加到 Bicep 配置中。

启用实验性功能

可以通过将以下部分添加到 bicepconfig.json 文件来启用试验性功能。 使用试验性功能自动启用语言版本 2.0 代码生成。

Warning

Microsoft客户支持不会为使用Bicep实验功能导致的问题提供帮助;请自行承担风险使用这些功能。

下面是启用“assertions”和“testFramework”功能的示例。

{
  "experimentalFeaturesEnabled": {
    "assertions": true,
    "testFramework": true
  }
}

有关 Bicep 实验性功能的详细信息,请参阅实验性功能。

后续步骤