Delen via

CLI-opdrachten Bicep

In dit artikel worden de opdrachten beschreven die u kunt gebruiken in de Bicep CLI. U kunt deze opdrachten uitvoeren met behulp van de Azure CLI of door rechtstreeks Bicep CLI-opdrachten aan te roepen. Voor elke methode is een afzonderlijk installatieproces vereist. Zie Azure CLI en Azure PowerShell voor meer informatie over installaties.

Deze richtlijnen laten zien hoe u de opdrachten uitvoert in de Azure CLI. Wanneer u opdrachten uitvoert in de Azure CLI, start u deze met az. Als u de Azure CLI niet gebruikt, voert u de opdrachten uit zonder az aan het begin van elk bestand. Wordt bijvoorbeeld az bicep buildbicep build, en az bicep version wordt bicep --version.

build

Met de opdracht build converteert u een Bicep-bestand naar een ARM-sjabloon (JSON Azure Resource Manager sjabloon). Normaal gesproken hoeft u deze opdracht niet uit te voeren omdat deze automatisch wordt uitgevoerd wanneer u een Bicep-bestand implementeert. Voer deze handmatig uit wanneer u de JSON ARM-sjabloon wilt zien die is gemaakt op basis van uw Bicep-bestand.

Als u een van de volgende Bicep functies gebruikt, wordt taalversie 2.0-code automatisch gegenereerd:

In het volgende voorbeeld wordt een Bicep-bestand met de naam main.bicep geconverteerd naar een ARM-sjabloon met de naam main.json. Het nieuwe bestand wordt gemaakt in dezelfde map als het Bicep-bestand:

bicep build main.bicep

In het volgende voorbeeld wordt main.json opgeslagen in een andere map:

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

In het volgende voorbeeld wordt de naam en locatie van het bestand opgegeven dat moet worden gemaakt:

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

Als u het bestand wilt stdoutafdrukken, gebruikt u:

bicep build main.bicep --stdout

Als uw Bicep bestand een module bevat die verwijst naar een extern register, roept de opdracht build automatisch restore aan. Met de restore opdracht wordt het bestand opgehaald uit het register en opgeslagen in de lokale cache.

Notitie

De restore opdracht vernieuwt de cache niet. Zie herstellen voor meer informatie.

Als u automatische herstel wilt voorkomen, gebruikt u de --no-restore schakeloptie:

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

Als u de --no-restore-switch wilt gebruiken, moet u Bicep CLI versie 0.4.X of hoger hebben.

Het buildproces met de switch mislukt als een van de externe modules nog niet in de --no-restore cache is opgeslagen:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" hasn't been restored.

Wanneer u deze fout krijgt, voert u de build opdracht uit zonder de --no-restore switch of voert u deze eerst uit bicep restore .

build-params

Met de build-params opdracht wordt een .bicepparam bestand gebouwd in een JSON-parameterbestand:

bicep build-params params.bicepparam

Met deze opdracht wordt een parameterbestand params.bicepparam geconverteerd naar een params.json JSON-parametersbestand.

decompileren

Met de opdracht decompile converteert u een JSON ARM-sjabloon naar een Bicep-bestand:

bicep decompile main.json

Met deze opdracht maakt u een bestand met de naam main.bicep in dezelfde map als main.json. Als main. bicep bestaat in dezelfde map, gebruikt u de --force om het bestaande Bicep-bestand te overschrijven.

Zie Decompile JSON ARM-sjabloon voor Bicep voor meer informatie over het gebruik van deze opdracht.

decompile-params

Met de decompile-params opdracht wordt een JSON-parameterbestand gedecompileert naar een .bicepparam parameterbestand.

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

Met deze opdracht wordt een azuredeploy.parameters.json parameterbestand gedecompileert in een bestand azuredeploy.parameters.bicepparam . Gebruik --bicep-file om het pad naar het Bicep-bestand op te geven (ten opzichte van het bestand .bicepparam) waarnaar wordt verwezen in de declaratie using.

indeling

De opdracht format formatteert een Bicep bestand, zodat het de aanbevolen stijlconventies volgt. U kunt het beschouwen als een code-formatter of 'prettier' voor uw Bicep bestanden. Het heeft dezelfde functie als de snelkoppeling SHIFT+ALT+F in Visual Studio Code.

bicep format main.bicep

generate-params

Met de opdracht generate-params wordt een parameterbestand gebouwd op basis van het opgegeven Bicep-bestand en bijgewerkt als er een bestaand parameterbestand is.

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

Met deze opdracht maakt u een Bicep parameterbestand met de naam main.bicepparam. Het parameterbestand bevat alle parameters in het Bicep-bestand, ongeacht of het is geconfigureerd met standaardwaarden of niet.

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

Met deze opdracht maakt u een parameterbestand met de naam main.parameters.json. Het parameterbestand bevat alleen de parameters zonder standaardwaarden die zijn geconfigureerd in het Bicep-bestand.

installeren

Met de opdracht install wordt de Bicep CLI aan uw lokale omgeving toegevoegd en is deze alleen beschikbaar via de Azure CLI. Zie Install Bicep tools voor meer informatie.

Als u de nieuwste versie wilt installeren, gebruikt u:

N/A

Gebruik de volgende opdracht om een specifieke versie te installeren:

N/A

jsonrpc

Met de opdracht jsonrpc wordt de Bicep CLI uitgevoerd met een JSON-RPC interface. Met behulp van deze interface kunt u programmatisch communiceren met gestructureerde uitvoer. U voorkomt ook vertragingen met koude start bij het compileren van meerdere bestanden. Deze installatie ondersteunt het bouwen van bibliotheken voor interactie met Bicep bestanden via programmacode in niet-.NET talen.

De draadindeling voor het verzenden en ontvangen van invoer en uitvoer is door headers gescheiden. Hierbij wordt de volgende structuur gebruikt, waarbij \r regelterugloop- \n en regelinvoertekens worden weergegeven:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n
  • <length> is de lengte van de <message> tekenreeks, inclusief de volgreeks \r\n\r\n.
  • <message> is het onbewerkte JSON-bericht.

Voorbeeld:

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

De volgende methoden zijn beschikbaar via de JSON-RPC-interface:

  • bicep/format

    Hiermee wordt een Bicep-bestand opgemaakt.

    • De aanvraag:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bicep/format",
  "params": {
    "path": "/path/to/file.bicep"
  }
}

    • Het antwoord:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "diagnostics": [],
    "contents": "param foo string\n\nresource storage 'Microsoft.Storage/storageAccounts@2025-01-01' = {\n  name: 'mystorageaccount'\n  location: 'East US'\n}\n"
  }
}

      Bij succes wordt "success": true geretourneerd, waarbij de inhoud de opgemaakte Bicep bron bevat. Bij een fout, "success": false met diagnostics een beschrijving van de fout.

  • bicep/version

    Retourneert de versie van de Bicep CLI.

    • De aanvraag:

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

    • Het antwoord:

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

Zie ICliJsonRpcProtocol.cs voor de beschikbare methoden en aanvraag- en antwoordteksten. Zie jsonrpc.test.ts voor een voorbeeld van het maken van een JSONRPC-verbinding en het programmatisch werken met Bicep bestanden.

Gebruik voor benoemde pijp

Gebruik de volgende syntaxis om verbinding te maken met een bestaande benoemde pijp als een JSONRPC-client:

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> is een bestaande benoemde pijp waarmee de JSONRPC-client wordt verbonden.

Verbinding maken met een benoemde pipe in macOS of Linux:

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

Verbinding maken met een benoemde pijp op Windows:

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

Zie C# en node.js voor meer voorbeelden.

Gebruik voor TCP-socket

Gebruik de volgende syntaxis om verbinding te maken met een bestaande TCP-socket als een JSONRPC-client:

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> is het socketnummer waarmee de JSONRPC-client verbinding maakt.

Verbinding maken met een TCP-socket:

bicep jsonrpc --socket 12345

Gebruik voor stdin en stdout

Gebruik de volgende syntaxis om de JSONRPC-interface uit te voeren. Gebruik stdin en stdout voor berichten:

bicep jsonrpc --stdio

pluis

De opdracht lint retourneert de fouten en linterregel schendingen van een Bicep-bestand.

bicep lint main.bicep

Als uw Bicep bestand een module bevat die verwijst naar een extern register, roept de opdracht lint automatisch restore aan. Met de restore opdracht wordt het bestand opgehaald uit het register en opgeslagen in de lokale cache.

Notitie

De restore opdracht vernieuwt de cache niet. Zie herstellen voor meer informatie.

Als u automatische herstel wilt voorkomen, gebruikt u de --no-restore schakeloptie:

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

Het lintproces met de switch mislukt als een van de externe modules nog niet in de --no-restore cache is opgeslagen:

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

Wanneer u deze fout krijgt, voert u de lint opdracht uit zonder de --no-restore switch of voert u deze eerst uit bicep restore .

list-versions

De opdracht list-versions retourneert alle beschikbare versies van de Bicep CLI. Gebruik deze opdracht om te zien of u een nieuwe versie wilt upgraden of installeren . Deze opdracht is alleen beschikbaar via de Azure CLI.

N/A

publish

Met de publish opdracht wordt een module toegevoegd aan een register. Het Azure containerregister moet bestaan en het account dat naar het register wordt gepubliceerd, moet over de juiste machtigingen beschikken. Zie Gebruik privéregister voor Bicep modules voor meer informatie over het instellen van een moduleregister. Als u een module wilt publiceren, moet het account over het juiste profiel en de juiste machtigingen beschikken om toegang te krijgen tot het register. U kunt het profiel en de referentieprioriteit configureren voor verificatie bij het register in het Bicep configuratiebestand.

Nadat u het bestand naar het register hebt gepubliceerd, kunt u ernaar verwijzen in een module.

U moet Bicep CLI versie 0.14.X of hoger hebben om de opdracht publish en de parameter --documentationUri/-d te gebruiken.

Als u een module naar een register wilt publiceren, gebruikt u:

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

Voorbeeld:

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

De publish opdracht herkent geen aliassen die zijn opgegeven in een bicepconfig.json-bestand. Geef het volledige modulepad op.

Waarschuwing

Als u naar hetzelfde doel publiceert, wordt de oude module overschreven. Verhoog de versie bij het bijwerken.

De pagina Restore

Wanneer uw Bicep-bestand modules gebruikt die u naar een register publiceert, worden met de opdracht restore kopieën van alle vereiste modules uit het register opgehaald. Deze kopieën worden opgeslagen in een lokale cache. Een Bicep-bestand kan alleen worden gebouwd wanneer de externe bestanden beschikbaar zijn in de lokale cache. Normaal gesproken is het uitvoeren van herstel niet nodig omdat deze automatisch wordt geactiveerd door het buildproces.

Als u externe modules wilt herstellen naar de lokale cache, moet het account over het juiste profiel en de juiste machtigingen beschikken om toegang te krijgen tot het register. U kunt de profile en referentieprioriteit configureren voor verificatie bij het register in het configuratiebestand Bicep.

Als u de opdracht restore wilt gebruiken, moet u Bicep CLI versie 0.14.X of hoger hebben.

Als u de externe modules voor een bestand handmatig wilt herstellen, gebruikt u:

bicep restore <bicep-file>

Het Bicep bestand dat u opgeeft, is het bestand dat u wilt implementeren. Deze moet een module bevatten die is gekoppeld aan een register. U kunt bijvoorbeeld het volgende bestand herstellen:

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

U vindt de lokale cache in:

  • Op Windows

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

  • In Linux

    /home/<username>/.bicep

  • Op Mac

    ~/.bicep

De restore opdracht vernieuwt de cache niet als een module al in de cache is opgeslagen. Als u de cache wilt vernieuwen, kunt u het modulepad uit de cache verwijderen of de --force schakeloptie gebruiken met de restore opdracht.

snapshot

Met behulp van Bicep CLI v0.41.2 of hoger kunt u de opdracht snapshot gebruiken om een genormaliseerde, deterministische weergave van een Bicep-implementatie te maken vanuit een .bicepparam-bestand. U kunt deze momentopname vergelijken met latere momentopnamen om te begrijpen welke wijzigingen een herstructurering zou veroorzaken, zonder iets te implementeren op Azure. Deze opdracht is met name handig voor:

  • Visuele verschillen: Als u precies ziet hoe een herstructurering (zoals het verplaatsen van code naar een module) de onderliggende resourcedefinities wijzigt.
  • Complexe expressies: inzicht in wat een complexe tekenreeks of variabele daadwerkelijk evalueert vóór de implementatie.
  • CI/CD-validatie: automatisch onbedoelde wijzigingen in infrastructuurlogica detecteren tijdens pull-aanvragen.

Een momentopname maken

Met deze opdracht wordt een .snapshot.json bestand gegenereerd. Dit bestand is genormaliseerd, wat betekent dat ruis zoals modulegrenzen worden verwijderd, zodat u zich kunt richten op de resources zelf.

bicep snapshot --mode overwrite <bicep-param-file>

In het volgende JSON-bestand ziet u een voorbeeld van een momentopname:

{
  "predictedResources": [
    {
      "id": "[format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "stmyappstorage001",
      "apiVersion": "2025-01-01",
      "location": "eastus",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2"
    }
  ],
  "diagnostics": []
}

Wijzigingen valideren

Nadat u een momentopname hebt gemaakt, voert u de opdracht uit in de validatiemodus. Uw huidige Bicep code wordt vergeleken met de opgeslagen momentopname en toont een visuele diff, net zoals de opdracht wat-if maar volledig lokaal.

bicep snapshot --mode validate <bicep-param-file>

Een voorbeelduitvoer ziet er als volgt uit:

PS C:\bicep> bicep snapshot --mode validate main.bicepparam
Snapshot validation failed. Expected no changes, but found the following:

Scope: <unknown>

  ~ [format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]
    ~ apiVersion: "2025-01-01" => "2025-06-01"
    ~ sku.name:   "Standard_LRS" => "Standard_GRS"

'Validatie van momentopname is mislukt' geeft verschillen aan tussen de twee momentopnamen.

Bicep CLI-momentopname en wat-als deze verschillen hebben:

Functie bicep snapshot az deployment group what-if
Uitvoering Alleen lokaal (offline) Cloudgebaseerde (online)
Vergelijking Vergelijkt code versus een opgeslagen bestand Vergelijkt code versus live Azure status
Snelheid Zeer snel Trager (vereist API-aanroepen)
Gebruikssituatie Herstructureren en logica testen Laatste controle vóór implementatie

Context opgeven

Wanneer Bicep momentopname wordt uitgevoerd, voert de CLI een lokale evaluatie van uw code uit. Omdat deze niet met Azure praat, kan deze de cloud niet 'vragen' voor uw abonnements-id of de naam van de huidige resourcegroep.

Als uw code gebruikmaakt van omgevingsfuncties (zoals subscription().id), mislukt de momentopname of retourneert de tijdelijke aanduidingen, tenzij u specifieke context opgeeft via CLI-argumenten.

Als u een echte implementatieomgeving wilt simuleren, kunt u de volgende vlaggen doorgeven:

Argument Doel Voorbeeldwaarde
--subscription-id Vervangt de waarde die wordt geretourneerd door subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group Vervangt de waarde die wordt geretourneerd door resourceGroup().name my-production-rg
--location Hiermee stelt u de standaardlocatie in voor deployment().location westeurope
--tenant-id Vervangt de waarde die wordt geretourneerd door tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Vervangt de waarde die wordt geretourneerd door managementGroup().name my-corp-mg 
bicep snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

upgrade

Met upgrade de opdracht wordt uw geïnstalleerde versie bijgewerkt met de nieuwste versie. Deze opdracht is alleen beschikbaar via de Azure CLI.

N/A

version

De version opdracht retourneert de geïnstalleerde versie:

bicep --version

Als u de Bicep CLI niet hebt geïnstalleerd, ziet u een foutbericht waarin wordt aangegeven dat de Bicep CLI niet is gevonden.

Met de opdracht wordt het versienummer weergegeven:

Bicep CLI version 0.29.45 (57a44c0230)

Volgende stappen

Zie voor meer informatie over het implementeren van een Bicep-bestand:

  • Last updated on