Dokumentera koden genom att lägga till kommentarer och metadata

4 minuter

Bra Bicep-kod är självdokumentering. Det innebär att den använder tydlig namngivning och en bra struktur så att kollegorna snabbt kan förstå vad som händer när kollegor läser din kod. Om de behöver göra ändringar kan de vara säkra på att de ändrar rätt platser.

I vissa situationer kan du dock behöva förtydliga viss kod genom att lägga till extra dokumentation i dina Bicep-filer. När mallen har distribuerats och resurser har skapats i Azure är det också viktigt att alla som tittar på din Azure-miljö förstår vad varje resurs är och vad den är till för.

I den här lektionen får du lära dig hur du lägger till kommentarer i dina Bicep-filer och hur du använder resurstaggar för att lägga till metadata i dina Azure-resurser. Den här ytterligare dokumentationen ger dina kollegor insikter om vad din kod gör, logiken du använde för att skriva koden och syftet med dina Azure-resurser.

Lägga till kommentarer i koden

Med Bicep kan du lägga till kommentarer i koden. Kommentarer är text som kan läsas av människor och som dokumenterar koden men ignoreras när filen distribueras till Azure.

Bicep stöder två typer av kommentarer:

Enradskommentarer börjar med en dubbel snedstreckssekvens (//) och fortsätter till slutet av raden, som du ser här:

// 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'
  }
}

Flerradskommentarer använder /* teckensekvenserna och */ för att omge kommentaren och kan sträcka sig över flera rader, som du ser här:
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

Dricks

Undvik att använda kommentarer för uppenbara och tydliga delar av koden. Att ha för många kommentarer minskar faktiskt kodens läsbarhet. Dessutom är det lätt att glömma att uppdatera kommentarer när koden ändras i framtiden. Fokusera på att dokumentera unik logik och komplexa uttryck.

Du kan också använda Bicep-kommentarer för att lägga till ett strukturerat flerradsblock i början av varje fil. Se det som ett manifest. Ditt team kan besluta att varje mall och modul ska ha ett manifest som beskriver syftet med mallen och vad den innehåller, till exempel i det här exemplet:

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

Lägga till kommentarer i parameterfiler

Med parameterfiler kan du skapa en JSON-fil för att ange en uppsättning parametervärden för distributionen. Parametervärdena måste matcha de parametrar som deklareras i Bicep-mallen.

De värden som du anger i parameterfiler har också ofta nytta av att dokumenteras. Det är en bra idé att lägga till kommentarer i parameterfiler när du arbetar med parametervärden som kanske inte är direkt tydliga för någon som läser filen.

Webbplatsens Bicep-mall kan till exempel innehålla en parameter för URL:en för åtkomst till företagets produktlager-API så att webbplatsen kan visa om dina leksaker finns i lager i ditt lager. URL:erna för åtkomst till lager-API:et för varje miljö är inte lätta att förstå, så de är en bra kandidat för en kommentar:

{
    "$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.
      }
    }
  }

Dricks

När du arbetar med parameterfiler och andra JSON-filer som innehåller kommentarer måste du vanligtvis använda filnamnstillägget .jsonc i stället för .json. Detta hjälper Visual Studio Code och andra verktyg att förstå att kommentarer tillåts.

Lägga till beskrivningar i parametrar, variabler och utdata

När du skapar en parameter, variabel eller utdata kan du använda dekoratören @description() för att förklara dess syfte:

@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

Beskrivningar är kraftfullare än kommentarer eftersom beskrivningarna visas när någon hovrar över ett symboliskt namn när någon använder Visual Studio Code-tillägget för Bicep. När någon använder din Bicep-fil som en modul ser de även de beskrivningar som du tillämpar på dina parametrar.

Lägga till beskrivningar i resurser

Det kan också vara bra att lägga till beskrivningar i de resurser som du definierar. Du kan också använda dekoratören @description() på resurser.

Dessutom har vissa resurser stöd för att lägga till beskrivningar eller annan läsbar information i själva resursen. Till exempel innehåller många Azure Policy-resurser och rolltilldelningar för rollbaserad åtkomstkontroll (RBAC) i Azure en beskrivningsegenskap, så här:

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.'
  }
}

Det är en bra idé att använda den här egenskapen för att förklara varför du har skapat varje rolltilldelning. Beskrivningen distribueras till Azure med resursen, så alla som granskar din Azure-miljös RBAC-konfiguration kommer omedelbart att förstå syftet med rolltilldelningen.

Använda resurstaggar

Kommentarer i Bicep-filen visas inte någonstans i dina distribuerade resurser. De finns bara där för att hjälpa dig att dokumentera dina Bicep-filer. Det finns dock många situationer där du behöver spåra information om dina distribuerade Azure-resurser, inklusive:

Allokera dina Azure-kostnader till specifika kostnadsställen.
Förstå hur data som finns i databaser och lagringskonton ska klassificeras och skyddas.
Registrera namnet på det team eller den person som ansvarar för hanteringen av resursen.
Spåra namnet på miljön som resursen relaterar till, till exempel produktion eller utveckling.

Med resurstaggar kan du lagra viktiga metadata om resurser. Du definierar resurstaggar i din Bicep-kod och Azure lagrar informationen med resursen när den distribueras:

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'
  }
}

Du kan köra frågor mot en resurstaggar med hjälp av verktyg som Azure PowerShell och Azure CLI, och du kan se taggar på Azure Portal:

Skärmbild av Azure Portal för ett lagringskonto som visar platsen för taggar.

Det är vanligt att använda samma uppsättning taggar för alla dina resurser, så det är ofta en bra idé att definiera taggarna som parametrar eller variabler och sedan återanvända dem på varje resurs: