Befehle der Bicep-Befehlszeilenschnittstelle

  • Artikel

In diesem Artikel werden die Befehle beschrieben, die Sie in der Bicep-Befehlszeilenschnittstelle verwenden können. Sie haben zwei Optionen zum Ausführen dieser Befehle: entweder mithilfe der Azure CLI oder durch direktes Aufrufen der Befehle in der Bicep-Befehlszeilenschnittstelle. Jede Methode erfordert einen unterschiedlichen Installationsprozess. Weitere Informationen finden Sie unter Installieren der Azure CLI und Installieren von Azure PowerShell.

In diesem Artikel wird gezeigt, wie Sie die Befehle in der Azure CLI ausführen. Sie starten die Befehle bei der Ausführung über die Azure CLI mit az. Wenn Sie nicht die Azure CLI verwenden, lassen Sie bei der Ausführung az am Anfang des Befehls weg. Beispielsweise wird az bicep build zu bicep build, und az bicep version wird zu bicep --version.

build

Der Befehl build konvertiert eine Bicep-Datei in eine ARM-Vorlage (Azure Resource Manager). In der Regel müssen Sie diesen Befehl nicht ausführen, da er bei der Bereitstellung einer Bicep-Datei automatisch ausgeführt wird. Führen Sie ihn manuell aus, wenn Sie den JSON-Code der ARM-Vorlage sehen möchten, der auf der Grundlage Ihrer Bicep-Datei erstellt wird.

Die Verwendung eines der folgenden Bicep-Features aktiviert automatisch die Codegenerierung mit der Sprachversion 2.0:

Im folgenden Beispiel wird eine Bicep-Datei mit dem Namen main.bicep in eine ARM-Vorlage mit dem Namen main.json konvertiert. Die neue Datei wird im gleichen Verzeichnis wie die Bicep-Datei erstellt.

az bicep build --file main.bicep

Im nächsten Beispiel wird main.json in einem anderen Verzeichnis gespeichert.

az bicep build --file main.bicep --outdir c:\jsontemplates

Im nächsten Beispiel werden der Name und der Speicherort der zu erstellenden Datei angegeben.

az bicep build --file main.bicep --outfile c:\jsontemplates\azuredeploy.json

Verwenden Sie zum Ausgeben der Datei in stdout Folgendes:

az bicep build --file main.bicep --stdout

Wenn Ihre Bicep-Datei ein Modul enthält, das auf eine externe Registrierung verweist, ruft der Buildbefehl automatisch restore auf. Der restore-Befehl ruft die Datei aus der Registrierung ab und speichert sie im lokalen Cache.

Hinweis

Der Befehl „Wiederherstellen“ aktualisiert den Cache nicht. Weitere Informationen finden Sie unterWiederherstellen.

Verwenden Sie die Option --no-restore, um „restore“ nicht automatisch aufzurufen:

az bicep build --no-restore <bicep-file>

Der Buildprozess mit der Option --no-restore ist nicht erfolgreich, wenn eines der externen Module noch nicht zwischengespeichert wurde:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Wenn dieser Fehler auftritt, führen Sie entweder den Befehl build ohne Option --no-restore aus, oder führen Sie zuerst bicep restore aus.

Um einen --no-restore-Schalter zu verwenden, benötigen Sie die Bicep-CLI-Version 0.4.X oder höher.

build-params

Der Befehl „build-params“ erstellt eine .bicepparam-Datei als JSON-Parameterdatei.

az bicep build-params --file params.bicepparam

Mit diesem Befehl wird eine params.bicepparam-Parameterdatei in eine params.json-JSON-Parameterdatei konvertiert.

decompile

Der Befehl decompile konvertiert den JSON-Code der ARM-Vorlage in eine Bicep-Datei.

az bicep decompile --file main.json

Der Befehl erstellt eine Datei mit dem Namen main.bicep in dem Verzeichnis, in dem sich auch main.json befindet. Wenn sich in diesem Verzeichnis bereits eine Datei namens main.bicep befindet, verwenden Sie die Option --force, um die vorhandene Bicep-Datei zu überschreiben.

Weitere Informationen zur Verwendung dieses Befehls finden Sie unter Dekompilieren von ARM-Vorlagen-JSON-Code in Bicep.

dekompilieren-params

Der Befehl „decompile-params“ dekompilieren eine JSON-Parameterdatei in eine .bicepparam-Parameterdatei.

az bicep decompile-params --file azuredeploy.parameters.json --bicep-file ./dir/main.bicep

Mit diesem Befehl wird eine azuredeploy.parameters.json-Parameterdatei in eine azuredeploy.parameters.bicepparam-Datei dekompiliert. --bicep-file gibt den Pfad zur Bicep-Datei (relativ zur .bicepparam-Datei) an, auf die in der using-Deklaration verwiesen wird.

format

Der Befehl format formatiert eine Bicep-Datei. Er hat dieselbe Funktion wie die Verknüpfung SHIFT+ALT+F in Visual Studio Code.

az bicep format --file main.bicep

generate-params

Mit dem Befehl „generate-params“ wird die „.parameters.json“-Datei aus der vorhandenen Bicep-Datei erstellt. Sie wird aktualisiert, sofern die Parameterdatei vorhanden ist.

az bicep generate-params --file main.bicep --output-format bicepparam --include-params all

Der Befehl erstellt eine Bicep-Parameterdatei mit dem Namen main.bicepparam. Die Parameterdatei enthält alle Parameter in der Bicep-Datei, unabhängig davon, ob sie mit Standardwerten konfiguriert sind oder nicht.

az bicep generate-params --file main.bicep --outfile main.parameters.json

Mit dem Befehl wird eine Parameterdatei mit dem Namen main.parameters.json erstellt. Die Parameterdatei enthält nur die Parameter ohne in der Bicep-Datei konfigurierten Standardwerte.

Installieren

Mit dem Befehl install wird die Bicep-Befehlszeilenschnittstelle Ihrer lokalen Umgebung hinzugefügt. Weitere Informationen finden Sie unter Installieren von Bicep-Tools. Dieser Befehl ist nur über die Azure CLI verfügbar.

Verwenden Sie zur Installation der aktuellen Version Folgendes:

az bicep install

So installieren Sie eine bestimmte Version

az bicep install --version v0.3.255

jsonrpc

Mit dem jsonrpc Befehl wird die Bicep CLI mit einer JSON-RPC-Schnittstelle ausgeführt, sodass eine programmgesteuerte Interaktion mit einer strukturierten Ausgabe möglich ist und Kaltstartverzögerungen beim Kompilieren mehrerer Dateien vermieden werden. Dieses Setup unterstützt auch das Erstellen von Bibliotheken für die programmgesteuerte Interaktion mit Bicep-Dateien in non-.NET Sprachen.

Das Drahtformat für das Senden und Empfangen von Eingaben/Ausgaben ist durch Kopfzeilen getrennt, wobei die folgende Struktur verwendet wird, wobei \r Wagenrücklauf- und \n Zeilenvorschubzeichen dargestellt werden:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n
  • <length> ist die Länge der <message> Zeichenfolge, einschließlich des nachgestellten \r\n\r\n.
  • <message> ist die unformatierte JSON-Nachricht.

Zum Beispiel:

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

Die folgende Meldung zeigt ein Beispiel für die Bicep-Version.

  • Die Eingabe:

    {
  "jsonrpc": "2.0",
  "id": 0,
  "method": "bicep/version",
  "params": {}
}

  • Die Ausgabe ist:

    {
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "version": "0.24.211"
  }
}

Die verfügbaren Methoden und Anforderungs-/Antworttexte finden Sie unter ICliJsonRpcProtocol.cs. Ein Beispiel für die Einrichtung einer JSONRPC-Verbindung und die programmgesteuerte Interaktion mit Bicep-Dateien mithilfe von Node finden Sie unter jsonrpc.test.ts.

Verwendung für benannte Rohre

Verwenden Sie die folgende Syntax, um eine Verbindung mit einer vorhandenen benannten Pipe als JSONRPC-Client herzustellen.

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> ist eine vorhandene benannte Pipe, mit der der JSONRPC-Client verbunden werden soll.

So stellen Sie eine Verbindung mit einer benannten Pipe unter OSX/Linux her:

bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock

So stellen Sie eine Verbindung mit einer benannten Pipe unter Windows her:

bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`

Weitere Beispiele finden Sie unter C# und node.js.

Verwendung für TCP-Socket

Verwenden Sie die folgende Syntax, um eine Verbindung mit einem vorhandenen TCP-Socket als JSONRPC-Client herzustellen.

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> ist eine Socketnummer, mit der der JSONRPC-Client verbunden werden kann.

So stellen Sie eine Verbindung mit einem TCP-Socket her

bicep jsonrpc --socket 12345

Verwendung für Stdin und Stdout

Verwenden Sie die folgende Syntax, um die JSONRPC-Schnittstelle mit stdin & stdout für Nachrichten auszuführen.

bicep jsonrpc --stdio

lint

Der Befehl lint gibt die Fehler und die Verstöße gegen eine Linter-Regel einer Bicep-Datei zurück.

az bicep lint --file main.bicep

Wenn Ihre Bicep-Datei ein Modul enthält, das auf eine externe Registrierung verweist, ruft der lint-Befehl automatisch restore auf. Der restore-Befehl ruft die Datei aus der Registrierung ab und speichert sie im lokalen Cache.

Hinweis

Der Befehl „Wiederherstellen“ aktualisiert den Cache nicht. Weitere Informationen finden Sie unterWiederherstellen.

Verwenden Sie die Option --no-restore, um „restore“ nicht automatisch aufzurufen:

az bicep lint --no-restore <bicep-file>

Der lint-Prozess mit der Option --no-restore ist nicht erfolgreich, wenn eines der externen Module noch nicht zwischengespeichert wurde:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Wenn dieser Fehler auftritt, führen Sie entweder den Befehl lint ohne Option --no-restore aus, oder führen Sie zuerst bicep restore aus.

list-versions

Mit dem Befehl list-versions werden alle verfügbaren Versionen der Bicep-Befehlszeilenschnittstelle zurückgegeben. Verwenden Sie diesen Befehl, um zu sehen, ob Sie ein Upgrade durchführen oder eine neue Version installieren sollten. Dieser Befehl ist nur über die Azure CLI verfügbar.

az bicep list-versions

Der Befehl gibt ein Array verfügbarer Versionen zurück.

[
  "v0.28.1",
  "v0.27.1",
  "v0.26.170",
  "v0.26.54",
  "v0.25.53",
  "v0.25.3",
  "v0.24.24",
  "v0.23.1",
  "v0.22.6",
  "v0.21.1",
  "v0.20.4",
  "v0.19.5",
  "v0.18.4",
  "v0.17.1",
  "v0.16.2",
  "v0.16.1",
  "v0.15.31",
  "v0.14.85",
  "v0.14.46",
  "v0.14.6",
  "v0.13.1",
  "v0.12.40",
  "v0.12.1",
  "v0.11.1",
  "v0.10.61",
  "v0.10.13",
  "v0.9.1",
  "v0.8.9",
  "v0.8.2",
  "v0.7.4"
]

Veröffentlichen

Der Befehl publish fügt einer Registrierung ein Modul hinzu. Die Azure-Containerregistrierung muss vorhanden sein, und das in der Registrierung veröffentlichte Konto muss über die richtigen Berechtigungen verfügen. Weitere Informationen zum Einrichten einer Modulregistrierung finden Sie unter Verwenden einer privaten Registrierung für Bicep-Module. Um ein Modul zu veröffentlichen, muss das Konto über das richtige Profil und die entsprechenden Berechtigungen für den Zugriff auf die Registrierung verfügen. Sie können die Rangfolge des Profils und der Anmeldeinformationen für die Authentifizierung bei der Registrierung in der Bicep-Konfigurationsdatei konfigurieren.

Nachdem Sie die Datei in der Registrierung veröffentlicht haben, können Sie in einem Modul darauf verweisen.

Um den publish-Befehl zu verwenden, benötigen Sie die Bicep-CLI-Version 0.14.X oder höher. Um den Parameter --documentationUri/-d zu verwenden, benötigen Sie die Bicep-CLI-Version 0.14.X oder höher.

Verwenden Sie den folgenden Befehl, um ein Modul in einer Registrierung zu veröffentlichen:

az bicep publish --file <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

Beispiel:

az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

Der Befehl publish erkennt keine Aliase, die in der Datei bicepconfig.json angegeben werden. Geben Sie den vollständigen Modulpfad an.

Warnung

Durch eine Veröffentlichung im selben Ziel wird das alte Modul überschrieben. Es wird empfohlen, die Versionsnummer beim Aktualisieren zu erhöhen.

Wiederherstellen

Wenn Ihre Bicep-Datei Module verwendet, die in einer Registrierung veröffentlicht werden, ruft der Befehl restore Kopien aller benötigten Module aus der Registrierung ab. Diese Kopien werden in einem lokalen Cache gespeichert. Eine Bicep-Datei kann nur erstellt werden, wenn die externen Dateien im lokalen Cache verfügbar sind. Normalerweise ist die Ausführung der Wiederherstellung nicht erforderlich, da sie automatisch vom Buildprozess ausgelöst wird.

Um externe Module im lokalen Cache wiederherzustellen, muss das Konto über das richtige Profil und die richtigen Berechtigungen für den Zugriff auf die Registrierung verfügen. Sie können die Rangfolge des Profils und der Anmeldeinformationen für die Authentifizierung bei der Registrierung in der Bicep-Konfigurationsdatei konfigurieren.

Um den restore-Befehl zu verwenden, benötigen Sie die Bicep-CLI-Version 0.4.X oder höher. Dieser Befehl ist derzeit nur verfügbar, wenn die Bicep-CLI direkt aufgerufen wird. Er ist derzeit nicht über den Azure CLI-Befehl verfügbar.

Verwenden Sie den folgenden Befehl, um die externen Module für eine Datei manuell wiederherzustellen:

az bicep restore --file <bicep-file> [--force]

Die angegebene Bicep-Datei ist die Datei, die Sie bereitstellen möchten. Sie muss ein Modul enthalten, das mit einer Registrierung verknüpft ist. Sie können beispielsweise die folgende Datei wiederherstellen:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Der lokale Cache befindet sich hier:

  • Unter Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • Unter Linux

    /home/<username>/.bicep

  • Unter Mac

    ~/.bicep

Der restore-Befehl aktualisiert den Cache nicht, wenn ein Modul bereits zwischengespeichert ist. Um den Cache zu aktualisieren, können Sie entweder den Modulpfad aus dem Cache löschen oder den --force-Schalter mit dem restore-Befehl verwenden.

upgrade

Der Befehl upgrade aktualisiert Ihre installierte Version mit der neuesten Version. Dieser Befehl ist nur über die Azure CLI verfügbar.

az bicep upgrade

version

Der Befehl version gibt die installierte Version zurück.

az bicep version

Mit dem Befehl wird die Versionsnummer angezeigt.

Bicep CLI version 0.22.6 (d62b94db31)

Wenn Sie diesen Befehl direkt über die Bicep-CLI aufrufen möchten, verwenden Sie:

bicep --version

Wenn die Bicep-Befehlszeilenschnittstelle nicht installiert wurde, wird eine Fehlermeldung mit dem Hinweis angezeigt, dass die Bicep-Befehlszeilenschnittstelle nicht gefunden wurde.

Nächste Schritte

Informationen zum Bereitstellen einer Bicep-Datei finden Sie unter folgenden Links: