新增註解及中繼資料以記錄程式碼

  • 4 分鐘

良好的 Bicep 程式碼能夠「自編文件」。 這表示它會使用清楚的命名和良好的結構，讓同事閱讀您的程序代碼時，可以快速了解發生的情況。 如果同事需要進行變更，其可以確信正在修改正確的位置。

不過，在某些情況下，您可能需要將額外的文件新增至 Bicep 檔案，以釐清特定程式碼。 此外，在部署範本並在 Azure 中建立資源之後，讓查看 Azure 環境的所有人都了解每個資源的內容及用途相當重要。

在本單元中，您將了解如何將註解新增至 Bicep 檔案，以及如何使用資源標籤將中繼資料新增至 Azure 資源。 此額外檔可讓您的同事深入瞭解程式代碼的用途、您用來撰寫程式代碼的邏輯，以及 Azure 資源的用途。

將註解新增至程式碼

Bicep 可讓您將批註新增至程序代碼。 註解是人類看得懂的文字，可記錄程式碼，但在檔案部署至 Azure 時，則會遭到忽略。

Bicep 支援兩種類型的註解：

  • 單行註解的開頭是雙斜線 (//) 字元序列，並會持續至該行的結尾，如下所示：

    // We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

  • 多行註解會使用 /* 與 */ 字元序列來括住註解，而且可跨越多行，如下所示：

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

提示

避免將註解用於明顯且明確的程式碼部分。 實際上，太多註解會減少程式碼的可讀性。 此外，未來當程式碼變更時，也很容易忘記更新註解。 專注於記錄唯一的邏輯與複雜運算式。

您也可以使用 Bicep 註解，在每個檔案的開頭新增結構化多行區塊。 將其視為「資訊清單」。 您的小組可能會決定每個範本與課程模組都應該有描述範本用途及其所包含內容的資訊清單，例如在此範例中：

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

將註解新增至參數檔案

參數檔案可讓您建立 JSON 檔案，為您的部署指定一組參數值。 參數值必須符合 Bicep 範本中宣告的參數。

您在參數檔案中指定的值通常也可受益於記錄。 當所使用參數值對讀取檔案的人而言可能不是那麼清楚時，建議您將註解新增至參數檔案。

例如，網站的 Bicep 範本可能包含存取您公司產品庫存 API 的 URL 參數，可讓您的網站顯示倉庫中是否有玩具庫存。 在每個環境用來存取庫存 API 的 URL 不容易理解，因此是適合註解的對象：

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

提示

當使用包含註解的參數檔案或其他 JSON 檔案時，通常需要使用 .jsonc 副檔名，而不是 .json。 這有助於 Visual Studio Code 與其他工具理解可以使用註解。

將描述新增至參數、變數和輸出

當您建立參數、變數或輸出時，可以套用 @description() 裝飾項目來協助說明其用途：

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

描述比批註功能更強，因為在有人使用 Bicep 的 Visual Studio Code 延伸模組時，每當將滑鼠停留在符號名稱上，就會顯示描述。 此外，當有人使用 Bicep 檔案作為模組時，會看到您套用至參數的描述。

新增資源的描述

將描述新增至您定義的資源也很有幫助。 您也可以將 @description() 裝飾項目套用至資源。

此外，有些資源支援對資源本身新增描述或其他一般人看得懂的資訊。 例如，許多 Azure 原則資源與 Azure 角色型存取控制 (RBAC) 角色指派都包含描述屬性，如下所示：

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

建議使用此屬性說明您建立每個角色指派的原因。 描述會和資源一同部署到 Azure，因此稽核 Azure 環境 RBAC 組態的任何人員都可立即瞭解角色指派的目的。

套用資源標籤

Bicep 檔案中的註解不會出現在已部署資源中。 其只是為了協助記錄 Bicep 檔案。 然而，在許多情況下，您需要追蹤已部署之 Azure 資源的相關資訊，包括：

  • 將您的 Azure 成本配置給特定的成本中心。
  • 了解資料庫與儲存體帳戶中包含的資料應該如何分類及保護。
  • 記錄負責管理資源的小組或人員名稱。
  • 追蹤與資源相關的環境名稱，例如生產或開發。

資源 標籤 可讓您儲存資源的相關重要元數據。 您可以在 Bicep 程式碼中定義資源標籤，而 Azure 會在部署資源時，與資源一併儲存該資訊：

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

您可以使用 Azure PowerShell 與 Azure CLI 等工具查詢資源的標籤，並且可以在 Azure 入口網站上看到標籤：

Screenshot of the Azure portal for a storage account, showing the location of tags.

您的所有資源一般都會使用同一組標籤，因此通常建議將標籤定義為參數或變數，然後對每個資源重複使用這些標籤：

param tags object = {
  CostCenter: 'Marketing'
  DataClassification: 'Public'
  Owner: 'WebsiteTeam'
  Environment: 'Production'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  tags: tags
}

resource appServiceApp 'Microsoft.Web/sites@2023-12-01' = {
  tags: tags
}