重構 Bicep 檔案

5 分鐘

在範本轉換為 Bicep 的轉換和移轉階段完成後，您需要改善檔案。此過程稱為「重構」。在 JSON ARM 範本和 Azure 資源遷移至 Bicep 時所建議的工作流程中，第三個階段就是重構階段：

Diagram that shows the refactor phase of the recommended workflow for migrating Azure resources to Bicep.

「重構」階段的重點是改善 Bicep 程式碼的品質。改進項目可能包括像是新增程式碼註解的變更，其可讓範本與您的範本標準保持一致。

重構階段包含八個步驟，執行可以不分先後：

檢閱資源 API 版本。
在新的 Bicep 檔案中檢閱 Linter 建議。
修訂參數、變數和符號名稱。
簡化運算式。
檢閱子資源和擴充資源。
模組化。
新增留言。
遵循 Bicep 最佳做法。

下列範例顯示建立 App Service 方案的 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@2024-04-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@2024-04-01' = {

為了清楚起見，最好從變數名稱中移除 _var。但重新命名變數時，新名稱與 App Service 方案資源的符號名稱會衝突。因此，最好先重新命名資源，再重新命名其定義中使用的變數。

提示

當重新命名識別碼時，請務必確認重新命名後的識別碼在範本內全都保持一致。這對您在整個範本中參考的參數、變數與資源而言特別重要。

Visual Studio Code 提供便利的方式來重新命名符號：依序選取想要重新命名的識別碼和 F2、輸入新名稱，然後選取 Enter：

Screenshot from Visual Studio Code that shows how to rename a symbol.

這些步驟重新命名識別碼，並自動更新其所有參考。

簡化運算式

反向組譯流程不見得會用到某些 Bicep 功能。檢閱轉換中產生的所有運算式並加以簡化。例如，反向組譯的範本可能包含 concat() 和 format() 函式，利用字串插補即可簡化。檢閱 Linter 的任何建議，並視需要進行調整。

檢閱子資源和擴充資源

Bicep 提供多種方法來宣告子資源和擴充資源，包括串連資源的名稱、使用 parent 屬性及使用巢狀資源。

反向組譯之後，請考慮檢閱這些資源，以確定結構符合您的標準。例如，請確定您未使用字串串連來建立子資源名稱。請改為使用 parent 屬性或巢狀資源。同樣地，您可以將子網路視為虛擬網路的屬性或個別資源來參考。

模組化

如果您要轉換的範本有許多資源，為求簡化，請考慮將個別資源類型細分為模組。在 Bicep 中使用模組有助於降低範本部署的複雜度。

注意

在 Bicep 部署中，JSON 範本可以作為模組。 Bicep 可以辨識 JSON 模組，並如同使用 Bicep 模組一樣加以參考。

新增註解和描述

良好的 Bicep 程式碼能夠「自編文件」。在 Bicep 中，您可以新增程式碼的註解和描述，以記錄基礎結構。註解和描述可協助小組成員了解程式碼，在做變更時更有信心。當您在 Visual Studio Code 中使用 Bicep 檔案 (例如當您需要指定模組的參數值時) 時，會顯示註解和描述。但是當您將 Bicep 檔案部署至 Azure 時，則會忽略註解。

您可以使用 // 字元序列來新增單行註解。針對多行註解，以 /* 開頭，並以 */ 結尾。您可以為程式碼中的特定行或程式碼區段新增註解。

您可以在檔案開頭新增多行註解：

/*
  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.