重构 Bicep 文件

已完成

完成从模板到 Bicep 的转换和迁移阶段后，需要改进文件。 此过程称为“重构”。 用于将 JSON ARM 模板和 Azure 资源迁移到 Bicep 的建议工作流的第三个阶段叫做重构阶段：

重构阶段侧重于提高 Bicep 代码的质量。 改进可以包括更改（如添加代码注释），让模板符合模板标准。

此重构阶段由八个步骤组成，可以按任意顺序执行这些步骤：

• 查看资源 API 版本。
• 在新的 Bicep 文件中查看 linter 建议。
• 修改参数、变量和符号名称。
• 简化表达式。
• 审阅子资源和扩展资源。
• 模块化。
• 添加注释。
• 遵循 Bicep 最佳做法。

以下示例显示了创建应用服务计划的 JSON 模板的 Bicep decompile 命令的输出：

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

如果按原样部署此 Bicep 模板，则部署将成功，但可以改进模板以使其符合模板标准。

查看资源 API 版本

使用 Bicep 与 Azure 资源交互时，指定要使用的 API 版本。 随着 Azure 产品的变化和改进，发布了更新的 API 版本以提供对新功能的访问。 导出 Azure 资源时，导出的模板可能没有资源类型的最新 API 版本。 如果需要用于未来部署的特定属性，请将 API 更新到适当的版本。 最好查看每个导出资源的 API 版本。

可使用 Azure ARM 模板参考帮助验证模板的相应 API 版本和资源属性。

在新的 Bicep 文件中查看 linter 建议

使用适用于 Visual Studio Code 的 Bicep 扩展创建 Bicep 文件时，Linter 会自动运行，并在代码中突出显示错误以及提供建议。 许多建议和错误都包含对问题应用快速修复的选项。 查看这些建议并调整 Bicep 文件。

修改参数、变量和符号名称

如果你的基础结构可支持多个环境（如生产和开发环境），请创建支持这些环境的参数。 良好的参数命名约定将可以让你轻松地根据环境自定义部署。

反编译程序生成的参数、变量名称和符号名称可能与标准命名约定不匹配。 审阅生成的名称并根据需要进行调整。

在下面的示例中，名为 appServicePlanName_var 的变量在原始变量名称的末尾追加了 _var：

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {

为清楚起见，最好从变量名称中删除 _var。 但在重命名该变量时，其新名称会与应用服务计划资源的符号名称冲突。 最好先重命名资源，然后重命名定义中使用的变量。

提示

重命名标识符时，请务必在模板的所有部分保持一致。 这对于在整个模板中引用的参数、变量和资源尤其重要。

Visual Studio Code 提供了一种简便的符号重命名方法：选择想要重命名的标识符，选择 F2，输入新名称，然后选择 Enter：

这些步骤会重命名标识符并自动更新对它的所有引用。

简化表达式

反编译过程并非总是能充分利用一些 Bicep 的功能。 查看转换中生成的任何表达式，并对其进行简化。 例如，反向编译的模板可能包含 concat() 或 format() 函数，你可以使用字符串内插来简化这些函数。 查看来自 linter 的所有建议，并根据需要进行调整。

审阅子资源和扩展资源

Bicep 提供多种方式来声明子资源和扩展资源，包括连接资源名称、使用 parent 关键字和使用嵌套资源。

请考虑在反编译后查看这些资源，以确保结构满足标准。 例如，请确保不要使用字符串串联来创建子资源名称， 而应使用 parent 属性或嵌套资源。 同样，可以将子网作为虚拟网络的属性引用，也可作为单独的资源进行引用。

模块化

如果要转换包含多个资源的模板，请考虑将各个资源类型分解为模块，以达到简化的目的。 在 Bicep 中使用模块有助于降低模板部署的复杂性。

注意

在 Bicep 部署中，可以使用 JSON 模板作为模块。 Bicep 可以识别 JSON 模块，并以类似于使用 Bicep 模块的方式引用它们。

添加注释和说明

好的 Bicep 代码是自文档化的。 在 Bicep 中，可以向代码添加注释和说明以记录基础结构。 注释和说明可帮助团队成员理解代码，并对作出的更改更有信心。 在 Visual Studio Code 中使用 Bicep 文件时，注释和说明可见，例如当你需要为模块指定参数值时。 但是，将 Bicep 文件部署到 Azure 时，注释将被忽略。

可以使用 // 字符序列添加单行注释。 对于多行注释，请以 a /* 开头并以 */ 结尾。 可以添加注释以应用于代码中的特定行或代码段。

可在文件开头添加多行注释：

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

可以将单行注释添加为代码段的标题，或添加到单独的行上以描述代码：

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

Bicep 提供 @description 修饰器，可用于记录参数、变量、资源、模块和输出的用途。 可以在要说明的项上方的行上添加说明：

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

遵循 Bicep 最佳做法

请确保 Bicep 文件遵循标准建议。 查看 Bicep 最佳做法，了解你可能遗漏的任何内容。

转换后的模板

做出适当改进后，请在部署之前查看最终模板。 更新后的模板包括修订的名称、API 版本、说明和添加的注释：

/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.