Freigeben über

Bewährte Methoden für Bicep

In diesem Artikel werden Methoden für die Entwicklung Ihrer Bicep-Dateien empfohlen. Diese Praktiken erleichtern das Verständnis und die Verwendung Ihrer Bicep-Datei.

Parameter

  • Verwenden Sie eine gute Benennung für Parameterdeklarationen. Gute Namen machen Ihre Vorlagen leicht lesbar und verständlich. Stellen Sie sicher, dass Sie klare, beschreibende Namen verwenden und in Ihrer Benennung konsistent sind.

  • Machen Sie sich Gedanken zu den in Ihrer Vorlage verwendeten Parametern. Verwenden Sie nach Möglichkeit Parameter für Einstellungen, die sich zwischen Bereitstellungen ändern. Variablen und hartcodierte Werte können für Einstellungen verwendet werden, die sich zwischen Bereitstellungen nicht ändern.

  • Achten Sie auf die von Ihnen verwendeten Standardwerte. Stellen Sie sicher, dass die Standardwerte für alle Benutzer sicher sind. Ziehen Sie z. B. die Verwendung von Preisniveaus und SKUs mit niedriger Kosten in Betracht, damit eine Person, die die Vorlage in einer Testumgebung bereitstellt, nicht unnötig große Kosten verursacht.

  • Verwenden Sie das Decorator-Element @allowed sparsam. Bei zu großzügiger Verwendung dieses Decorator-Elements werden unter Umständen gültige Bereitstellungen blockiert. Da Azure-Dienste SKUs und Größen hinzufügen, ist Ihre liste möglicherweise nicht auf dem neuesten Stand. Beispielsweise kann es sinnvoll sein, nur Premium v3-SKUs in der Produktion zuzulassen, sie verhindert jedoch, dass Sie dieselbe Vorlage in Nicht-Produktionsumgebungen verwenden.

  • Es empfiehlt sich, Beschreibungen für Ihre Parameter anzugeben. Die Beschreibungen sollten hilfreich sein und alle wichtigen Informationen zu den erforderlichen Parameterwerten für die Vorlage enthalten.

    Sie können auch // Kommentare verwenden, um Notizen in Ihren Bicep-Dateien hinzuzufügen.

  • Sie können Parameterdeklarationen an einer beliebigen Stelle in der Vorlagendatei platzieren, obwohl es in der Regel eine gute Idee ist, sie am Anfang der Datei zu platzieren, damit Ihr Bicep-Code leicht zu lesen ist.

  • Es empfiehlt sich, die minimale und maximale Zeichenlänge für Parameter anzugeben, die die Benennung steuern. Diese Einschränkungen helfen, Fehler später während der Bereitstellung zu vermeiden.

Weitere Informationen zu Bicep-Parametern finden Sie unter Parameter in Bicep.

Variablen

  • Wenn Sie eine Variable definieren, ist der Datentyp nicht erforderlich. Variablen leiten den Typ vom Ergebniswert ab.

  • Sie können Bicep-Funktionen verwenden, um eine Variable zu erstellen.

  • Nachdem eine Variable in Ihrer Bicep-Datei definiert wurde, verweisen Sie mithilfe des Variablennamens auf den Wert.

Weitere Informationen zu Bicep-Variablen finden Sie unter "Variablen" in Bicep.

Namen

  • Verwenden Sie Namen mit gemischter Groß-/Kleinschreibung wie myVariableName oder myResource.

  • Die uniqueString()-Funktion ist nützlich zum Erstellen eindeutiger Ressourcennamen. Wenn Sie dieselben Parameter angeben, wird jedes Mal dieselbe Zeichenfolge zurückgegeben. Wenn Sie die Ressourcengruppen-ID übergeben, ist die Zeichenfolge bei jeder Bereitstellung für die gleiche Ressourcengruppe identisch und bei der Bereitstellung für andere Ressourcengruppen oder Abonnements unterschiedlich.

  • Es empfiehlt sich, Vorlagenausdrücke zum Erstellen von Ressourcennamen zu verwenden, z. B. in diesem Beispiel:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    Die Verwendung von Vorlagenausdrücken zum Erstellen von Ressourcennamen bietet ihnen mehrere Vorteile:

    • Zeichenfolgen, die von uniqueString() generiert werden, sind nicht aussagekräftig. Es ist hilfreich, einen Vorlagenausdruck zu verwenden, um einen Namen zu erstellen, der aussagekräftige Informationen enthält, z. B. einen kurzen Deskriptor des Projekt- oder Umgebungsnamens, sowie eine zufällige Komponente, damit der Name wahrscheinlicher eindeutig ist.

    • Die uniqueString() Funktion garantiert keine global eindeutigen Namen. Indem Sie Ihren Ressourcennamen zusätzlichen Text hinzufügen, verringern Sie die Wahrscheinlichkeit, dass sie einen vorhandenen Ressourcennamen wiederverwenden.

    • Manchmal erstellt die uniqueString() Funktion Zeichenfolgen, die mit einer Zahl beginnen. Bei einigen Azure-Ressourcen, z. B. Speicherkonten, dürfen die Namen nicht mit Zahlen beginnen. Diese Anforderung bedeutet, dass es ratsam ist, die Zeichenfolgeninterpolation zum Erstellen von Ressourcennamen zu verwenden. Sie können der eindeutigen Zeichenfolge ein Präfix hinzufügen.

    • Bei vielen Azure-Ressourcentypen gibt es Regeln bezüglich der zulässigen Zeichen und der Länge ihrer Namen. Das Einbetten der Erstellung von Ressourcennamen in die Vorlage bedeutet, dass jeder, der die Vorlage verwendet, nicht daran denken muss, diese Regeln selbst zu befolgen.

  • Vermeiden Sie die Verwendung name in einem symbolischen Namen. Der symbolische Name stellt die Ressource dar, nicht den Namen der Ressource. Anstelle der folgenden Syntax beispielsweise:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

    Verwendung:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

  • Vermeiden Sie die Unterscheidung von Variablen und Parametern durch die Verwendung von Suffixen.

Ressourcendefinitionen

  • Anstatt komplexe Ausdrücke direkt in Ressourceneigenschaften einzubetten, verwenden Sie Variablen, um die Ausdrücke zu enthalten. Dieser Ansatz erleichtert das Lesen und Verstehen Ihrer Bicep-Datei. Dadurch wird verhindert, dass die Ressourcendefinitionen mit Logik überladen werden.

  • Versuchen Sie, Ressourceneigenschaften als Ausgaben zu verwenden, anstatt Annahmen über das Verhalten von Ressourcen zu machen. Wenn Sie z. B. die URL in eine App Service-App ausgeben müssen, verwenden Sie die DefaultHostname-Eigenschaft der App, anstatt eine Zeichenfolge für die URL selbst zu erstellen. Manchmal sind diese Annahmen in verschiedenen Umgebungen nicht korrekt, oder die Ressourcen ändern die Funktionsweise. Es ist sicherer, dass die Ressource Ihnen ihre eigenen Eigenschaften mitteilen kann.

  • Es ist ratsam, eine aktuelle API-Version für jede Ressource zu verwenden. Neue Features in Azure-Diensten sind manchmal nur in neueren API-Versionen verfügbar.

  • Vermeiden Sie nach Möglichkeit die Verwendung der Funktionen reference und resourceId in Ihrer Bicep-Datei. Sie können auf jede Ressource in Bicep zugreifen, indem Sie den symbolischen Namen verwenden. Wenn Sie beispielsweise ein Speicherkonto mit dem symbolischen Namen toyDesignDocumentsStorageAccount definieren, können Sie mithilfe des Ausdrucks toyDesignDocumentsStorageAccount.idauf die Ressourcen-ID zugreifen. Mithilfe des symbolischen Namens erstellen Sie eine implizite Abhängigkeit zwischen Ressourcen.

  • Bevorzugen Sie implizite Abhängigkeiten gegenüber expliziten Abhängigkeiten. Obwohl die dependsOn Ressourceneigenschaft es Ihnen ermöglicht, eine explizite Abhängigkeit zwischen Ressourcen zu deklarieren, ist es in der Regel möglich, die Eigenschaften der anderen Ressource mithilfe des symbolischen Namens zu verwenden. Dieser Ansatz erstellt eine implizite Abhängigkeit zwischen den beiden Ressourcen und ermöglicht es Bicep, die Beziehung selbst zu verwalten.

  • Wenn die Ressource nicht in der Bicep-Datei bereitgestellt wird, können Sie mithilfe des existing Schlüsselworts dennoch einen symbolischen Verweis auf die Ressource abrufen.

Untergeordnete Ressourcen

  • Vermeiden Sie Schachtelungen mit zu vielen Ebenen. Wenn Ihr Bicep-Code zu viele Schachtelungen enthält, ist er schlechter les- und verwendbar.

  • Erstellen Sie am besten keine Ressourcennamen für untergeordnete Ressourcen. Sie verlieren die Vorteile, die Bicep bietet, wenn sie die Beziehungen zwischen Ihren Ressourcen versteht. Verwenden Sie stattdessen die Eigenschaft parent oder die Schachtelung.

Ausgaben

  • Markieren Sie vertrauliche Daten in Ausgaben mithilfe des @secure()-Dekorators, wodurch verhindert wird, dass vertrauliche Ausgaben protokolliert oder angezeigt werden. Andernfalls können von jedem, der Zugriff auf den Bereitstellungsverlauf hat, auf Ausgabewerte zugegriffen werden.

  • Anstatt Eigenschaftswerte durch Ausgaben zu übergeben, verwenden Sie das vorhandene Schlüsselwort , um Eigenschaften von Ressourcen nachzuschlagen, die bereits vorhanden sind. Es hat sich bewährt, Schlüssel aus anderen Ressourcen auf diese Weise nachzuschlagen, anstatt sie per Ausgaben zu übergeben. Sie erhalten so immer die neuesten Daten.

Weitere Informationen zu Bicep-Ausgaben finden Sie unter "Ausgaben in Bicep".

Mandantenbereiche

Sie können keine Richtlinien oder Rollenzuweisungen im Mandantenbereich erstellen. Wenn Sie jedoch Zugriff gewähren oder Richtlinien in Ihrer gesamten Organisation anwenden müssen, können Sie diese Ressourcen in der Stammverwaltungsgruppe bereitstellen.

Nächste Schritte

  • Last updated on