Documenteer uw code door opmerkingen en metagegevens toe te voegen

4 minuten

Goede Bicep-code is zelfdocumenterend. Dit betekent dat het duidelijke naamgeving en een goede structuur gebruikt, zodat wanneer collega's uw code lezen, ze snel kunnen begrijpen wat er gebeurt. Als ze wijzigingen moeten aanbrengen, kunnen ze er zeker van zijn dat ze de juiste plaatsen wijzigen.

In sommige situaties moet u echter bepaalde code misschien verduidelijken door extra documentatie toe te voegen aan uw Bicep-bestanden. Nadat uw sjabloon is geïmplementeerd en resources zijn gemaakt in Azure, is het ook belangrijk dat iedereen die uw Azure-omgeving bekijkt begrijpt wat elke resource is en waarvoor deze is bedoeld.

In deze les leert u hoe u opmerkingen toevoegt aan uw Bicep-bestanden en hoe u resourcetags gebruikt om metagegevens toe te voegen aan uw Azure-resources. Deze aanvullende documentatie geeft uw collega's inzicht in wat uw code doet, de logica die u hebt gebruikt om de code te schrijven en het doel van uw Azure-resources.

Opmerkingen toevoegen aan uw code

Met Bicep kunt u opmerkingen toevoegen aan uw code. Opmerkingen zijn door mensen leesbare tekst die uw code documenteert, maar wordt genegeerd wanneer het bestand wordt geïmplementeerd in Azure.

Bicep ondersteunt twee soorten opmerkingen:

Opmerkingen met één regel beginnen met een tekenreeks met dubbele slash (//) en doorgaan naar het einde van de regel, zoals hier wordt weergegeven:

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

Opmerkingen met meerdere regels gebruiken de /* en */ tekenreeksen om de opmerking te plaatsen en kunnen meerdere regels omvatten, zoals hier wordt weergegeven:
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

Tip

Vermijd het gebruik van opmerkingen voor duidelijke en duidelijke onderdelen van uw code. Als u te veel opmerkingen hebt, vermindert u de leesbaarheid van uw code. Het is ook gemakkelijk om opmerkingen bij te werken wanneer uw code in de toekomst verandert. Richt u op het documenteren van unieke logica en complexe expressies.

U kunt bicep-opmerkingen ook gebruiken om aan het begin van elk bestand een gestructureerd blok met meerdere regels toe te voegen. Beschouw het als een manifest. Uw team kan besluiten dat elke sjabloon en module een manifest moeten hebben dat het doel van de sjabloon beschrijft en wat deze bevat, zoals in dit voorbeeld:

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

Opmerkingen toevoegen aan parameterbestanden

Met parameterbestanden kunt u een JSON-bestand maken om een set parameterwaarden voor uw implementatie op te geven. De parameterwaarden moeten overeenkomen met de parameters die zijn gedeclareerd in de Bicep-sjabloon.

De waarden die u in parameterbestanden opgeeft, profiteren vaak ook van het documenteren. Het is raadzaam opmerkingen toe te voegen aan parameterbestanden wanneer u werkt met parameterwaarden die mogelijk niet onmiddellijk duidelijk zijn voor iemand die het bestand leest.

De Bicep-sjabloon van uw website kan bijvoorbeeld een parameter voor de URL bevatten voor toegang tot de productvoorraad-API van uw bedrijf, zodat uw website kan weergeven of uw speelgoed op voorraad is in uw magazijn. De URL's voor toegang tot de stock-API voor elke omgeving zijn niet gemakkelijk te begrijpen, dus ze zijn een goede kandidaat voor een opmerking:

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

Tip

Wanneer u werkt met parameterbestanden en andere JSON-bestanden die opmerkingen bevatten, moet u meestal de bestandsextensie .jsonc gebruiken in plaats van .json. Dit helpt Visual Studio Code en andere hulpprogramma's te begrijpen dat opmerkingen zijn toegestaan.

Beschrijvingen toevoegen aan parameters, variabelen en uitvoer

Wanneer u een parameter, variabele of uitvoer maakt, kunt u de decorator toepassen om het @description() doel ervan uit te leggen:

@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

Beschrijvingen zijn krachtiger dan opmerkingen omdat wanneer iemand de Visual Studio Code-extensie voor Bicep gebruikt, de beschrijvingen worden weergegeven wanneer iemand een symbolische naam aanwijst. Wanneer iemand uw Bicep-bestand als module gebruikt, zien ze ook de beschrijvingen die u op uw parameters toepast.

Beschrijvingen toevoegen aan resources

Het kan ook handig zijn om beschrijvingen toe te voegen aan de resources die u definieert. U kunt de @description() decorator ook toepassen op resources.

Daarnaast bieden sommige resources ondersteuning voor het toevoegen van beschrijvingen of andere door mensen leesbare informatie aan de resource zelf. Veel Azure Policy-resources en RBAC-roltoewijzingen (op rollen gebaseerd toegangsbeheer) van Azure bevatten bijvoorbeeld een beschrijvingseigenschap, zoals:

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

Het is een goed idee om deze eigenschap te gebruiken om uit te leggen waarom u elke roltoewijzing hebt gemaakt. De beschrijving wordt geïmplementeerd in Azure met de resource, zodat iedereen die de RBAC-configuratie van uw Azure-omgeving controleert, onmiddellijk inzicht krijgt in het doel van de roltoewijzing.

Resourcetags toepassen

Opmerkingen in uw Bicep-bestand worden nergens in uw geïmplementeerde resources weergegeven. Ze zijn er alleen om u te helpen uw Bicep-bestanden te documenteren. Er zijn echter veel situaties waarin u informatie over uw geïmplementeerde Azure-resources moet bijhouden, waaronder:

Uw Azure-kosten toewijzen aan specifieke kostenplaatsen.
Informatie over hoe de gegevens in databases en opslagaccounts moeten worden geclassificeerd en beveiligd.
De naam van het team of de persoon die verantwoordelijk is voor het beheer van de resource opnemen.
De naam bijhouden van de omgeving waarmee de resource betrekking heeft, zoals productie of ontwikkeling.

Met resourcetags kunt u belangrijke metagegevens over resources opslaan. U definieert resourcetags in uw Bicep-code en Azure slaat de informatie op met de resource wanneer deze wordt geïmplementeerd:

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

U kunt query's uitvoeren op de tags van een resource met behulp van hulpprogramma's zoals Azure PowerShell en de Azure CLI, en u kunt tags bekijken in Azure Portal:

Schermopname van Azure Portal voor een opslagaccount met de locatie van tags.

Het is gebruikelijk om dezelfde set tags voor al uw resources te gebruiken, dus het is vaak een goed idee om uw tags te definiëren als parameters of variabelen en deze vervolgens opnieuw te gebruiken voor elke resource: