Refactoring der Bicep-Datei

  • 5 Minuten

Nach den Konvertierungs- und Migrationsphasen Ihrer Vorlagen zu Bicep müssen Sie die Datei verbessern. Dieser Vorgang wird als Umgestaltung bezeichnet. Die dritte Phase des empfohlenen Workflows für die Migration Ihrer JSON-ARM-Vorlage und Azure-Ressourcen zu Bicep ist die Umgestaltungsphase:

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

Der Hauptfokus dieser sogenannten refactor-Phase liegt auf der Verbesserung der Qualität Ihres Bicep-Codes. Die Verbesserungen können Änderungen umfassen, z. B. das Hinzufügen von Codekommentaren, die die Vorlage mit Ihren Vorlagenstandards in Einklang bringen.

Die Umgestaltungsphase besteht aus acht Schritten, die Sie in beliebiger Reihenfolge ausführen können:

  • Überprüfen der Ressourcen-API-Versionen.
  • Überprüfen der Lintervorschläge in der neuen Bicep-Datei.
  • Überarbeiten von Parametern, Variablen und symbolischen Namen.
  • Vereinfachen von Ausdrücken.
  • Überprüfen von untergeordneten und Erweiterungsressourcen.
  • Modularisieren.
  • Hinzufügen von Kommentaren
  • Befolgen bewährter Methoden für Bicep.

Das folgende Beispiel zeigt die Ausgabe des Bicep-Befehls decompile einer JSON-Vorlage, die einen App Service-Plan erstellt:

@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@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

Wenn Sie diese Bicep-Vorlage ohne Änderungen bereitstellen, ist die Bereitstellung erfolgreich, aber Sie können die Vorlage verbessern, um sie mit Ihren Vorlagenstandards in Einklang zu bringen.

Überprüfen der Ressourcen-API-Versionen

Wenn Sie Bicep für die Interaktion mit Ihren Azure-Ressourcen verwenden, geben Sie eine zu verwendende API-Version an. Wenn sich die Produkte von Azure ändern und verbessert werden, werden neuere API-Versionen veröffentlicht, die Zugriff auf neue Funktionen bieten. Beim Exportieren von Azure-Ressourcen verfügt die exportierte Vorlage möglicherweise nicht über die neueste API-Version für einen Ressourcentyp. Wenn sie bestimmte Eigenschaften für zukünftige Bereitstellungen benötigen, aktualisieren Sie die API auf die entsprechende Version. Es hat sich bewährt, die API-Versionen für jede exportierte Ressource zu überprüfen.

Verwenden Sie die Referenz zu Azure ARM-Vorlagen, um die entsprechenden API-Versionen und Ressourceneigenschaften für Ihre Vorlage zu überprüfen.

Überprüfen der Lintervorschläge in der neuen Bicep-Datei

Beim Erstellen von Bicep-Dateien mithilfe der Bicep-Erweiterung für Visual Studio Code wird der Linter automatisch ausgeführt. Er hebt Fehler in Ihrem Code hervor und zeigt Vorschläge an. Viele der Vorschläge und Fehler enthalten eine Option für eine schnelle Korrektur des Problems. Überprüfen Sie diese Empfehlungen, und passen Sie Ihre Bicep-Datei an.

Überarbeiten von Parametern, Variablen und symbolischen Namen

Wenn Ihre Infrastruktur mehrere Umgebungen unterstützt, z. B. Produktion und Entwicklung, erstellen Sie Parameter, die diese Umgebungen unterstützen. Eine gute Namenskonvention für Parameter macht es einfach, Ihre Bereitstellungen umgebungsweise anzupassen.

Es ist möglich, dass die Namen von Parametern, Variablen und symbolischen Namen, die vom Decompiler generiert werden, nicht Ihrer Standardnamenskonvention entsprechen. Überprüfen Sie die generierten Namen, und nehmen Sie bei Bedarf Anpassungen vor.

Im folgenden Beispiel wurde an die benannte Variable appServicePlanName_var am Ende des ursprünglichen Variablennamens _var angefügt:

@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@2020-12-01' = {

Aus Gründen der Übersichtlichkeit empfiehlt es sich, _var aus dem Variablennamen zu entfernen. Wenn Sie die Variable jedoch umbenennen, steht ihr neuer Name in Konflikt mit dem symbolischen Namen der App Service-Plan-Ressource. Daher empfiehlt es sich, zuerst Ressourcen und dann die in ihren Definitionen verwendeten Variablen umzubenennen.

Tipp

Wenn Sie Bezeichner umbenennen, müssen Sie sie in allen Teilen der Vorlage konsistent umbenennen. Dies gilt insbesondere für Parameter, Variablen und Ressourcen, auf die Sie in der gesamten Vorlage verweisen.

Visual Studio Code bietet eine bequeme Möglichkeit zum Umbenennen von Symbolen: Wählen Sie den Bezeichner aus, den Sie umbenennen möchten, drücken Sie F2, geben Sie einen neuen Namen ein, und drücken Sie dann die EINGABETASTE:

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

Mit diesen Schritten wird der Bezeichner umbenannt und alle Verweise darauf werden automatisch aktualisiert.

Vereinfachen von Ausdrücken

Der Dekompilierungsprozess nutzt möglicherweise nicht alle Features von Bicep. Überprüfen Sie alle bei der Konvertierung generierten Ausdrücke, und vereinfachen Sie sie. Die dekompilierte Vorlage kann z. B. eine concat()- oder format()-Funktion enthalten, die mithilfe von Zeichenfolgeninterpolation vereinfacht werden kann. Überprüfen Sie alle Lintervorschläge, und nehmen Sie bei Bedarf Anpassungen vor.

Überprüfen von untergeordneten und Erweiterungsressourcen

Bicep bietet mehrere Möglichkeiten, untergeordnete und Erweiterungsressourcen zu deklarieren, einschließlich der Verkettung der Namen Ihrer Ressourcen, der Verwendung des Schlüsselworts parent und der Verwendung geschachtelter Ressourcen.

Überprüfen Sie diese Ressourcen nach der Dekompilierung, und stellen Sie sicher, dass die Struktur Ihren Standards entspricht. Stellen Sie beispielsweise sicher, dass Sie keine Zeichenfolgenverkettung verwenden, um untergeordnete Ressourcennamen zu erstellen. Verwenden Sie stattdessen die parent-Eigenschaft oder eine geschachtelte Ressource. Auf ähnliche Weise können Sie entweder als Eigenschaften eines virtuellen Netzwerks oder als separate Ressource auf Subnetze verweisen.

Modularisieren

Wenn Sie eine Vorlage konvertieren, die über viele Ressourcen verfügt, sollten Sie der Einfachheit halber erwägen, die einzelnen Ressourcentypen in Module aufzuteilen. Mit der Verwendung von Modulen in Bicep tragen Sie dazu bei, die Komplexität Ihrer Vorlagenbereitstellungen zu reduzieren.

Hinweis

Es ist möglich, Ihre JSON-Vorlagen als Module in einer Bicep-Bereitstellung zu verwenden. Bicep kann JSON-Module erkennen und auf diese auf ähnliche Weise wie bei der Verwendung von Bicep-Modulen zu verweisen.

Hinzufügen von Kommentaren und Beschreibungen

Guter Bicep-Code ist selbstdokumentierend. In Bicep können Sie Ihrem Code Kommentare und Beschreibungen hinzufügen, um Ihre Infrastruktur zu dokumentieren. Kommentare und Beschreibungen können Ihren Teamkollegen dabei helfen, den Code besser zu verstehen, und das Vertrauen erhöhen, wenn Änderungen vorgenommen werden. Kommentare und Beschreibungen sind sichtbar, wenn Sie mit einer Bicep-Datei in Visual Studio Code arbeiten, z. B. wenn Sie einen Parameterwert für ein Modul angeben. Wenn Sie jedoch eine Bicep-Datei in Azure bereitstellen, werden die Kommentare ignoriert.

Sie können einzeilige Kommentare mithilfe der Zeichenfolge // hinzufügen. Mehrzeilige Kommentaren beginnen Sie mit /* und beenden Sie mit */. Sie können Kommentare hinzufügen, die auf bestimmte Zeilen im Code oder auf Codeabschnitte angewandt werden.

Sie können einen mehrzeiligen Kommentar am Anfang der Datei hinzufügen:

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

Einzeilige Kommentare können als Überschriften für Codeabschnitte oder in einzelnen Zeilen zur Beschreibung des Codes hinzugefügt werden:

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

In Bicep kann der Zweck von Parametern, Variablen, Ressourcen, Modulen und Ausgaben mithilfe des Decorator-Elements @description dokumentiert werden. Sie können die Beschreibung in der Zeile über dem Element hinzufügen, das Sie beschreiben:

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

Befolgen bewährter Methoden für Bicep

Stellen Sie sicher, dass Ihre Bicep-Datei die Standardempfehlungen befolgt. Lesen Sie Bewährte Methoden für Bicep, um alle Informationen zu erhalten, die Sie möglicherweise noch nicht kennen.

Die konvertierte Vorlage

Nachdem Sie die entsprechenden Verbesserungen vorgenommen haben, überprüfen Sie die endgültige Vorlage vor der Bereitstellung. Die aktualisierte Vorlage enthält überarbeitete Werte für Namen, API-Versionen, Beschreibungen und Kommentare:

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