Planen der Struktur Ihrer Bicep-Datei
Bicep bietet Ihnen Flexibilität beim Strukturieren Ihres Codes. In dieser Lerneinheit lernen Sie die Möglichkeiten zum Strukturieren des Bicep-Codes kennen, und Sie erfahren, wie wichtig ein konsistentes Format und ein klar verständlicher Bicep-Code sind.
Welche Reihenfolge sollte Ihr Bicep-Code aufweisen?
Bicep-Vorlagen können viele Elemente enthalten, einschließlich Parametern, Variablen, Ressourcen, Modulen, Ausgaben und eines targetScope für die gesamte Vorlage. Bicep erzwingt keine Reihenfolge der Elemente. Die Reihenfolge der Elemente muss jedoch berücksichtigt werden, damit die Vorlage übersichtlich und verständlich ist.
Es gibt zwei Hauptansätze für die Reihenfolge im Code:
- Gruppieren von Elementen nach Elementtyp
- Gruppieren von Elementen nach Ressource
Sie und Ihr Team sollten sich auf einen dieser Ansätze einigen und ihn konsistent anwenden.
Gruppieren von Elementen nach Elementtyp
Sie können alle Elemente desselben Typs in einer Gruppe anordnen. Alle Parameter befinden sich an einer einzigen Stelle, in der Regel am Anfang der Datei. Als Nächstes folgen Variablen, dann Ressourcen und Module, und die Ausgaben befinden sich am Ende der Datei. Angenommen, Sie verfügen über eine Bicep-Datei, die eine Azure SQL-Datenbank und ein Speicherkonto bereitstellt.
Wenn Sie die Elemente nach Typ gruppieren, können sie wie folgt aussehen:
Tipp
Wenn Sie diese Konvention befolgen, sollten Sie möglicherweise den targetScope am Anfang der Datei anordnen.
Diese Reihenfolge ist sinnvoll, wenn Sie bisher andere Infrastrucure-as-Code-Sprachen (z. B. die Sprache in Azure Resource Manager-Vorlagen) verwendet haben. So kann die Vorlage auch leichter verständlich werden, da klar ersichtlich ist, wo sich bestimmte Elementtypen befinden. In umfangreicheren Vorlagen können jedoch die Navigation und das Wechseln zwischen den Elementen schwierig sein.
Sie müssen weiterhin bestimmen, wie die Elemente innerhalb dieser Kategorien angeordnet werden sollen. Es empfiehlt sich, verwandte Parameter gemeinsam zu gruppieren. Beispielsweise gehören alle Parameter für ein Speicherkonto zu derselben Gruppe, und innerhalb dieser Gruppe bilden die SKU-Parameter des Speicherkontos eine eigene Gruppe.
Ebenso können Sie verwandte Ressourcen gemeinsam gruppieren. Auf diese Weise können alle, die Ihre Vorlage verwenden, schnell in ihr navigieren und ihre wichtigen Teile verstehen.
Manchmal erstellen Sie eine Vorlage, die eine primäre Ressource mit mehreren sekundären unterstützenden Ressourcen bereitstellt. Beispielsweise können Sie eine Vorlage erstellen, um eine Website bereitzustellen, die in Azure App Service gehostet wird. Die primäre Ressource ist die App Service-App. Sekundäre Ressourcen in derselben Vorlage können den App Service Plan, das Speicherkonto, die Application Insights-Instanz und weitere Ressourcen umfassen. Wenn Sie über eine solche Vorlage verfügen, empfiehlt es sich, die primären Ressourcen an den Anfang des Ressourcenabschnitts der Vorlage zu stellen, damit alle, die die Vorlage öffnen, schnell den Zweck der Vorlage erkennen und die wichtigen Ressourcen finden.
Gruppieren von Elementen nach Ressource
Alternativ können Sie die Elemente nach dem Typ der bereitgestellten Ressourcen gruppieren. Im vorherigen Beispiel können Sie alle Parameter, Variablen, Ressourcen und Ausgaben gruppieren, die sich auf die Azure SQL-Datenbankressourcen beziehen. Anschließend können Sie die Parameter, Variablen, Ressourcen und Ausgaben für das Speicherkonto hinzufügen, wie hier gezeigt:
Die Gruppierung nach Ressource kann das Lesen der Vorlage vereinfachen, da sich alle Elemente, die Sie für eine bestimmte Ressource benötigen, an einer einzigen Stelle befinden. Dadurch wird es jedoch erschwert, schnell zu überprüfen, wie bestimmte Elementtypen deklariert sind, wenn Sie z. B. alle Parameter überprüfen möchten.
Wenn Sie eine Konfigurationszuordnung verwenden, müssen Sie auch überlegen, wie Sie Parameter und Variablen behandeln, die für mehrere Ressourcen gemeinsam gelten, z. B. einen environmentType-Parameter. Gemeinsame Parameter und Variablen sollten zusammen angeordnet werden, normalerweise am Anfang der Bicep-Datei.
Tipp
Überlegen Sie, ob es sinnvoller sein kann, Module für Gruppen verwandter Ressourcen zu erstellen, und die Module dann mithilfe einer einfacheren Vorlage zu kombinieren. In den Bicep-Lernpfaden werden Bicep-Module ausführlicher behandelt.
Wie kann Leerraum beim Erstellen von Strukturen helfen?
Leere Zeilen oder Leerraum können Sie bei der visuellen Strukturierung Ihrer Vorlage unterstützen. Durch umsichtiges Verwenden von Leerraum können Sie die Abschnitte Ihres Bicep-Codes logisch gruppieren. Dies wiederum kann dazu beitragen, die Beziehungen zwischen Ressourcen zu verdeutlichen. Hierfür können Sie unabhängig vom bevorzugten Gruppierungsstil eine leere Zeile zwischen Hauptabschnitten hinzufügen.
Wie definieren Sie mehrere ähnliche Ressourcen?
In Bicep können Sie mithilfe von Schleifen ähnliche Ressourcen aus einer einzelnen Definition bereitstellen. Mithilfe des for-Schlüsselworts zum Definieren von Ressourcenschleifen können Sie den Bicep-Code übersichtlicher gestalten und die unnötige Duplizierung von Ressourcendefinitionen reduzieren. Wenn Sie in Zukunft die Definition der Ressourcen ändern müssen, aktualisieren Sie nur eine Instanz. Wenn Azure Resource Manager die Ressourcen bereitstellt, werden standardmäßig alle Ressourcen in der Schleife gleichzeitig bereitgestellt, sodass Ihre Bereitstellung so effizient wie möglich ist.
Suchen Sie nach Positionen, an denen mehrere identische Ressourcen oder Ressourcen definiert sind, deren Eigenschaften sich nur geringfügig unterscheiden. Fügen Sie dann eine Variable hinzu, um die zu erstellenden Ressourcen zusammen mit den Eigenschaften aufzulisten, die sich von den Eigenschaften der anderen Ressourcen unterscheiden. Im folgenden Beispiel wird mithilfe einer Schleife ein Satz von Azure Cosmos DB-Containern definiert, von denen jeder über einen eigenen Namen und Partitionsschlüssel verfügt:
var cosmosDBContainerDefinitions = [
{
name: 'customers'
partitionKey: '/customerId'
}
{
name: 'orders'
partitionKey: '/orderId'
}
{
name: 'products'
partitionKey: '/productId'
}
]
resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
parent: cosmosDBDatabase
name: cosmosDBContainerDefinition.name
properties: {
resource: {
id: cosmosDBContainerDefinition.name
partitionKey: {
kind: 'Hash'
paths: [
cosmosDBContainerDefinition.partitionKey
]
}
}
options: {}
}
}]
Wie stellen Sie Ressourcen nur in bestimmten Umgebungen bereit?
Manchmal definieren Sie Ressourcen, die nur in bestimmten Umgebungen oder unter bestimmten Bedingungen bereitgestellt werden sollen. Mithilfe des if-Schlüsselworts können Sie Ressourcen basierend auf einem Parameterwert, einer Konfigurationszuordnungsvariablen oder einer anderen Bedingung selektiv bereitstellen. Im folgenden Beispiel wird eine Konfigurationszuordnung verwendet, um Protokollierungsressourcen für Produktionsumgebungen, jedoch nicht für Testumgebungen bereitzustellen:
var environmentConfigurationMap = {
Production: {
enableLogging: true
}
Test: {
enableLogging: false
}
}
resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
name: logAnalyticsWorkspaceName
location: location
}
resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
scope: cosmosDBAccount
name: cosmosDBAccountDiagnosticSettingsName
properties: {
workspaceId: logAnalyticsWorkspace.id
// ...
}
}
Wie können Sie Abhängigkeiten zwischen den Ressourcen ausdrücken?
In jeder komplexen Bicep-Vorlage müssen Sie Abhängigkeiten zwischen den Ressourcen angeben. Wenn Bicep die Abhängigkeiten zwischen den Ressourcen kennt, werden sie in der richtigen Reihenfolge bereitgestellt.
Bicep ermöglicht mithilfe der dependsOn-Eigenschaft das explizite Angeben von Abhängigkeiten. In den meisten Fällen ist es jedoch möglich, Bicep Abhängigkeiten automatisch erkennen zu lassen. Wenn Sie den symbolischen Namen einer Ressource innerhalb einer Eigenschaft einer anderen Ressource verwenden, erkennt Bicep die Beziehung. Sie sollten Bicep Abhängigkeiten selbst verwalten lassen, wann immer dies möglich ist. Auf diese Weise stellt Bicep beim Ändern einer Vorlage sicher, dass die Abhängigkeiten immer korrekt sind, und Sie fügen keinen unnötigen Code hinzu, der die Vorlage umständlicher und schwieriger zu lesen macht.
Wie drücken Sie Beziehungen zwischen über- und untergeordneten Elementen aus?
Das Konzept der untergeordneten Ressourcen in Azure Resource Manager und Bicep ist nur sinnvoll, wenn die untergeordneten Ressourcen im Kontext der übergeordneten Ressource bereitgestellt werden. Beispielsweise ist eine Azure SQL-Datenbank eine untergeordnete Ressource einer SQL Server-Instanz. Es gibt mehrere Möglichkeiten, untergeordnete Ressourcen zu definieren, in den meisten Fällen empfiehlt sich jedoch die Verwendung der parent-Eigenschaft. Dies hilft Bicep, die Beziehung zu verstehen, um eine Überprüfung in Visual Studio Code bereitzustellen. Zudem wird die Beziehung für alle anderen Personen, die die Vorlage lesen, deutlich.
Wie legen Sie Ressourceneigenschaften fest?
Sie müssen in den Bicep-Dateien die Werte für Ressourceneigenschaften angeben. Sie sollten umsichtig vorgehen, wenn Sie Werte in den Ressourcendefinitionen hartcodieren. Wenn Sie wissen, dass sich die Werte nicht ändern, ist die Hartcodierung möglicherweise der Verwendung eines anderen Parameters vorzuziehen, der das Testen und Verwenden der Vorlage erschwert. Wenn sich die Werte jedoch ändern können, sollten Sie sie als Parameter oder Variablen definieren, um die Dynamik und Wiederverwendbarkeit des Bicep-Codes zu verbessern.
Falls Sie Werte hartcodieren, sollten Sie sicherstellen, dass sie für andere verständlich sind. Wenn beispielsweise eine Eigenschaft auf einen bestimmten Wert festgelegt werden muss, damit sich die der Ressource für die Lösung richtig verhält, sollten Sie eine ordnungsgemäß benannte Variable erstellen, die eine Erklärung bietet, und dann den Wert mithilfe der Variablen zuweisen. In Situationen, in denen ein Variablenname keine ausreichende Erklärung liefert, sollten Sie einen Kommentar hinzufügen. Weitere Informationen zu Kommentaren erhalten Sie später in diesem Modul.
Für einige Ressourceneigenschaften müssen Sie zum automatischen Erzeugen von Werten komplexe Ausdrücke erstellen, die Funktionen und Zeichenfolgeninterpolation enthalten. Bicep-Code ist in der Regel besser verständlich, wenn Sie Variablen deklarieren und in den Ressourcencodeblöcken auf sie verweisen.
Tipp
Versuchen Sie beim Erstellen von Ausgaben nach Möglichkeit entsprechende Ressourceneigenschaften zu verwenden. Vermeiden Sie es, Ihre eigenen Annahmen zur Funktionsweise von Ressourcen zu integrieren, da sich diese Annahmen im Laufe der Zeit ändern können.
Wenn Sie z. B. die URL einer App Service-App ausgeben müssen, vermeiden Sie es, eine URL zu konstruieren:
output hostname string = '${app.name}.azurewebsites.net'
Der oben beschriebene Ansatz funktioniert nicht mehr, wenn App Service die Zuweisung von Hostnamen für Apps ändert oder wenn Sie die Bereitstellung in Azure-Umgebungen durchführen, die andere URLs verwenden.
Verwenden Sie stattdessen die defaultHostname-Eigenschaft der App-Ressource:
output hostname string = app.properties.defaultHostname
Wie verwenden Sie die Versionskontrolle effektiv?
Versionskontrollsysteme wie Git können Ihnen das Umgestalten von Code erleichtern.
Da Versionskontrollsysteme Änderungen an den Dateien nachverfolgen, können Sie sie verwenden, um im Falle eines Fehlers einfach zu einer älteren Version Ihres Codes zurückzukehren. Es empfiehlt sich, häufig Commits Ihrer Arbeit auszuführen, damit Sie genau zu dem Zeitpunkt zurückkehren können, den Sie benötigen.
Mithilfe der Versionskontrolle können Sie auch alten Code aus den Bicep-Dateien entfernen. Wie gehen Sie vor, wenn Ihr Bicep-Code eine Ressourcendefinition enthält, die Sie nicht mehr benötigen? Möglicherweise benötigen Sie die Definition in Zukunft erneut, und es ist verlockend, sie einfach auszukommentieren und in der Datei zu belassen. Dies macht Ihre Bicep-Datei jedoch nur unübersichtlich, und für andere ist nicht ersichtlich, warum die auskommentierten Ressourcen noch vorhanden sind.
Außerdem kann es geschehen, dass jemand die Auskommentierung der Definition versehentlich aufhebt, mit unvorhersehbaren oder potenziell schädlichen Ergebnissen. In einem Versionskontrollsystem können Sie einfach die alte Ressourcendefinition entfernen. Wenn Sie die Definition in Zukunft erneut benötigen, können Sie sie aus dem Dateiverlauf abrufen.