对 Bicep 代码执行 Lint 分析和验证

  • 5 分钟

现在你已了解管道各阶段的用途后，接下来请考虑可添加到 Bicep 部署管道的第一组验证步骤。 本单元将介绍如何验证 Bicep 模板。 你还将了解验证阶段通常执行的两个活动：Lint 分析和预检验证。

什么是有效的 Bicep 文件？

有效的 Bicep 文件是不包含任何语法错误的文件。 此外，你计划部署的 Azure 资源的定义也有效。 在部署文件中定义的资源时，这些资源保持在 Azure 订阅中存在的配额和限制范围内。

有些检查是单独对 Bicep 文件执行的，例如语法错误检查、Azure 资源定义有效性检查以及代码质量检查。 这些步骤是 Lint 分析过程的一部分。 若要检查其他问题，需要请求 Azure 资源管理器服务验证你的模板并将你的 Azure 环境纳入考虑范围。

有效的 Bicep 模板更有可能部署成功。 无需部署 Bicep 模板即可获得反馈。 验证一个很好的做法，因为如果部署了一个无效的 Bicep 文件，Azure 可能只会部署或更改模板中所述的一部分资源。 结果可能是环境状态将不一致，并且可能不会按预期方式运行。

生成和 lint Bicep 代码

部署 Bicep 文件时，Bicep 工具首先运行一些基本验证步骤。 这些步骤与使用 Visual Studio Code 修改文件时运行的步骤相同。 它们会检查你是否正确使用了 Bicep 的语言关键字，以及是否根据每种资源类型的要求定义了 Azure 资源。

此外，Bicep 还会对文件运行 Linter。 Lint 分析是根据一组建议检查代码的过程。 Bicep Linter 会查看你的文件，并验证你是否遵循了有关可维护性、正确性、灵活性和可扩展性的最佳做法。

对于其中每个类别，Linter 都包含一组预定义的规则。 Linter 规则示例包括：

  • 未使用的参数：Linter 会扫描在 Bicep 文件中任何位置都未使用的任何参数。 通过消除未使用的参数，可以更轻松地部署模板，因为无需提供不必要的值。 这还可在有人尝试使用你的 Bicep 文件时减少混淆。
  • 字符串内插：Linter 检查文件是否使用 concat() 函数而不是 Bicep 字符串内插。 字符串内插使 Bicep 文件更具可读性。
  • 安全参数的默认值：如果为标有 @secure() 修饰器的参数设置默认值，Linter 会发出警告。 对安全参数使用默认值是一种错误做法，因为它为安全参数提供一个人工可读值，并且用户在部署之前可能不会更改它。

使用 Bicep 工具时，Bicep Linter 会自动运行。 每次生成 Bicep 文件时，Linter 都会根据最佳做法对其进行检查。 将 Bicep 文件部署到 Azure 时，会自动发生 Lint 分析。

但在管道中，通常需要在部署文件之前运行验证和 Lint 分析步骤。 可使用 Bicep CLI 手动生成 Bicep 文件来告知 Bicep 验证文件：

az bicep build --file main.bicep

bicep build main.bicep

注意

运行 build 命令时，Bicep 还会将 Bicep 代码转译为 JSON ARM 模板。 你通常不需要它输出的文件，因此可忽略它。

因为你希望 Linter 在每次有人向你的存储库签入代码时检查 Bicep 模板，因此可向管道添加 Lint 分析阶段和作业：

示意图显示了一个管道，它具有一个“Lint 分析”阶段，其中有一个作业，它对文件运行 Linter。

可以在管道 YAML 文件中表达增加的该项内容，如下所示：

stages:

- stage: Lint
  jobs: 
  - job: Lint
    steps:
      - script: |
          az bicep build --file deploy/main.bicep

Linter 警告和错误

默认情况下，Linter 在发现 Bicep 文件违反规则时将发出警告。 Bicep Linter 发出的警告不会被视为错误，因此它们不会使管道或后续阶段停止运行。

可以通过配置 Bicep，将 Linter 规则冲突视为错误而不是警告，来更改此行为。 可通过将“bicepconfig.json”文件添加到包含你的 Bicep 文件的文件夹来执行此配置。 可以决定哪些 Linter 问题应被视为错误，哪些问题应保留为警告。 在本模块的后面，你将了解如何更新 Linter 规则。

提示

bicepconfig.json 文件还可控制 Visual Studio Code 在编辑器中显示错误和警告的方式。 它在 Bicep 模板中错误配置的部分下显示红色和黄色波浪线。 这些指标可让你在编写 Bicep 代码时更快获得反馈，进一步降低出错的可能性。

重新配置 Linter 以发出错误后，每当 Linter 检测到问题时，管道就会停止运行，后续作业或阶段也不会运行。 此设置有助于确保不会部署有问题的 Bicep 代码。

预检验证

还应检查 Bicep 模板是否可能成功部署到 Azure 环境。 这项检查称为“预检验证”，它还会运行更多检查，这些检查需要 Azure 提供相关信息。 这些类型的检查包括：

  • 为 Bicep 资源指定的名称是否有效？
  • 为 Bicep 资源指定的名称是否已被占用？
  • 要部署资源的区域是否有效？

预检验证需要与 Azure 通信，但它实际上不会部署任何资源。

示意图显示了一个管道，它包含 Lint 分析和验证阶段，其中每个阶段包含一个作业。验证阶段与 Azure 通信。

可以使用 AzureResourceManagerTemplateDeployment 任务提交 Bicep 文件进行预检验证，并将 deploymentMode 配置为 Validation：

- stage: Validate
  jobs:
  - job: Validate
    steps:
      - task: AzureResourceManagerTemplateDeployment@3
        inputs:
          connectedServiceName: 'MyServiceConnection'
          location: $(deploymentDefaultLocation)
          deploymentMode: Validation
          resourceGroupName: $(ResourceGroupName)
          csmFile: deploy/main.bicep

此命令与已使用的部署任务相似，但它实际上不会部署任何资源。 它会对模板中使用的资源执行额外检查。

例如，假设 Bicep 文件包含存储帐户。 预检验证将检查其他存储帐户是否已采用你选择的名称。 它还会检查为存储帐户选择的名称是否符合命名约定。

预检验证命令也会运行 Bicep Linter。 但通常建议单独运行 Linter。 这样，如果存在任何 Linter 错误，可以快速检测它们，而无需等待验证过程完成。 验证需要更长的时间。

重要

运行预检验证时，每个 Azure 资源提供程序都执行其自己的检查。 某些资源提供程序不会运行许多检查（而其他资源提供程序会运行许多检查），因此不能依赖预检验证来确定文件是否有效。 尽管如此，它还是一个很有用的工具，值得包含在管道中。

通过向管道添加验证阶段以运行 Linter 并执行预检验证，你将在部署 Bicep 文件之前更有信心。