Befehle der Bicep-Befehlszeilenschnittstelle
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 einer der folgenden Bicep-Features ermöglicht automatisch die Sprachversion 2.0-Codegenerierung:
- benutzerdefinierte Typen
- benutzerdefinierte Funktionen
- Kompilierungszeitimporte
- Experimentelle Features
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
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: