Dokumentieren Ihres Codes durch Hinzufügen von Kommentaren und Metadaten

4 Minuten

Guter Bicep-Code ist selbstdokumentierend. Dies bedeutet, dass er eine klare Benennung und eine gute Struktur aufweist, damit Kollegen, die Ihren Code lesen, schnell verstehen können, was er bewirkt. Wenn sie Änderungen vornehmen müssen, können sie darauf vertrauen, dass sie die richtigen Stellen ändern.

In manchen Situationen müssen Sie jedoch möglicherweise bestimmten Code verdeutlichen, indem Sie den Bicep-Dateien zusätzliche Dokumentation hinzufügen. Außerdem ist es nach der Bereitstellung der Vorlage und der Erstellung der Ressourcen wichtig, dass die Betrachter Ihrer Azure-Umgebung jede Ressource erkennen und ihren Zweck begreifen.

In dieser Lerneinheit erfahren Sie, wie Sie den Bicep-Dateien Kommentare und den Azure-Ressourcen mithilfe von Ressourcentags Metadaten hinzufügen. Diese zusätzliche Dokumentation erläutert Ihren Kollegen die Funktion Ihres Codes, die Logik, mit dem Sie den Code geschrieben haben, und den Zweck Ihrer Azure-Ressourcen.

Hinzufügen von Kommentaren zu Ihrem Code

Mit Bicep können Sie Ihrem Code Kommentare hinzufügen. Kommentare sind lesbarer Text, der Ihren Code dokumentiert, jedoch ignoriert wird, wenn die Datei in Azure bereitgestellt wird.

Bicep unterstützt zwei Arten von Kommentaren:

Einzeilige Kommentare beginnen mit einem doppelten Schrägstrich (//) und werden am Ende der Zeile fortgesetzt, wie im folgenden Beispiel:

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

Mehrzeilige Kommentare beginnen mit der Zeichenfolge /* und enden mit der Zeichenfolge */ und können sich über mehrere Zeilen erstrecken, wie im folgenden Beispiel:
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

Tipp

Verwenden Sie keine Kommentare für klar verständliche Teile Ihres Codes. Eine zu große Anzahl von Kommentaren reduziert die Lesbarkeit Ihres Codes. Außerdem wird häufig vergessen, Kommentare zu aktualisieren, wenn der Code geändert wurde. Konzentrieren Sie sich auf das Dokumentieren besonderer Logik und komplexer Ausdrücke.

Sie können auch Bicep-Kommentare verwenden, um am Anfang jeder Datei einen strukturierten mehrzeiligen Block hinzuzufügen. Sie können sich dies als Manifest vorstellen. Möglicherweise möchte Ihr Team, dass jede Vorlage und jedes Modul ein Manifest enthält, das den Zweck der Vorlage und ihren Inhalt beschreibt, wie in diesem Beispiel:

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

Hinzufügen von Kommentaren zu Parameterdateien

Mit Parameterdateien können Sie eine JSON-Datei erstellen, um einen Satz von Parameterwerten für Ihre Bereitstellung anzugeben. Die Parameterwerte müssen mit den Parametern übereinstimmen, die in der Bicep-Vorlage deklariert sind.

Häufig ist es von Vorteil, auch die in den Parameterdateien angegebenen Werte zu dokumentieren. Es hat sich bewährt, Parameterdateien Kommentare hinzuzufügen, wenn Sie mit Parameterwerten arbeiten, deren Bedeutung für die Leser der Datei eventuell nicht sofort verständlich ist.

Angenommen, die Bicep-Vorlage Ihrer Website enthält einen Parameter für die URL, über die der Zugriff auf die Produktbestand-API Ihres Unternehmens erfolgt, damit Ihre Website anzeigen kann, ob Ihr Spielzeug vorrätig ist. Da die URLs für den Zugriff auf die Bestands-API für die jeweilige Umgebung nicht leicht verständlich sind, empfiehlt sich ein entsprechender 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.
      }
    }
  }

Tipp

Wenn Sie mit Parameterdateien und anderen JSON-Dateien arbeiten, die Kommentare enthalten, müssen Sie in der Regel statt .json die Dateierweiterung .jsonc verwenden. So können Visual Studio Code und andere Tools erkennen, dass Kommentare zulässig sind.

Hinzufügen von Beschreibungen zu Parametern, Variablen und Ausgaben

Wenn Sie einen Parameter, eine Variable oder eine Ausgabe erstellen, können Sie den @description()-Decorator anwenden, um dessen Zweck zu erläutern:

@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

Beschreibungen sind leistungsfähiger als Kommentare. Wenn jemand die Visual Studio Code-Erweiterung für Bicep verwendet, werden die Beschreibungen angezeigt, wenn jemand auf einen symbolischen Namen zeigt. Wenn eine Person Ihre Bicep-Datei als Modul verwendet, werden außerdem die Beschreibungen angezeigt, die Sie auf Ihre Parameter anwenden.

Hinzufügen von Beschreibungen zu Ressourcen

Es kann auch hilfreich sein, den von Ihnen definierten Ressourcen Beschreibungen hinzuzufügen. Sie können den @description()-Decorator auch auf Ressourcen anwenden.

Darüber hinaus können einigen Ressourcen Beschreibungen und andere lesbare Informationen direkt hinzugefügt werden. Beispielsweise enthalten viele Azure Policy-Ressourcen und Rollenzuweisungen der rollenbasierten Zugriffssteuerung (RBAC) eine Beschreibungseigenschaft, wie im folgenden Beispiel:

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

Es empfiehlt sich, mithilfe dieser Eigenschaft die Gründe für das Erstellen der einzelnen Rollenzuweisungen zu erläutern. Die Beschreibung wird in Azure mit der Ressource bereitgestellt, sodass jeder, der die RBAC-Konfiguration Ihrer Azure-Umgebung überwacht, sofort den Zweck der Rollenzuweisung versteht.

Anwenden von Ressourcentags

Kommentare in der Bicep-Datei werden in den bereitgestellten Ressourcen nicht angezeigt. Sie dienen lediglich zur Dokumentation der Bicep-Dateien. Es gibt jedoch viele Situationen, in denen Sie Informationen zu den bereitgestellten Azure-Ressourcen nachverfolgen müssen, z. B. die folgenden:

Zuordnen der Azure-Kosten zu bestimmten Kostenstellen
Ermitteln, wie die Daten in Datenbanken und Speicherkonten klassifiziert und geschützt werden sollten
Aufzeichnen des Namens des Teams oder der Person, das bzw. die für die Verwaltung der Ressource verantwortlich ist
Nachverfolgen des Namens der Umgebung, für die die Ressource vorgesehen ist, z. B. Produktion oder Entwicklung

Mit Ressourcentags können Sie wichtige Metadaten zu Ressourcen speichern. Sie definieren Ressourcentags im Bicep-Code, und Azure speichert die Informationen mit der Ressource, wenn sie bereitgestellt wird:

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

Sie können die Tags einer Ressource mit Tools wie Azure PowerShell und der Azure CLI abfragen, und Sie können Tags im Azure-Portal anzeigen:

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

Es ist üblich, für alle Ressourcen den gleichen Satz von Tags zu verwenden. Daher empfiehlt es sich häufig, die Tags als Parameter oder Variablen zu definieren und sie dann für jede Ressource wiederzuverwenden: