Compartir a través de

comandos de la CLI de Bicep

En este artículo se describen los comandos que puede usar en la CLI de Bicep. Puede ejecutar estos comandos mediante el CLI de Azure o invocando directamente Bicep comandos de la CLI. Cada método requiere un proceso de instalación distinto. Para obtener más información sobre las instalaciones, vea CLI de Azure y Azure PowerShell.

En esta guía se muestra cómo ejecutar los comandos en el CLI de Azure. Al ejecutar comandos en el CLI de Azure, inícielos con az. Si no usa el CLI de Azure, ejecute los comandos sin az al principio de cada uno. Por ejemplo, se convierte en y se convierte en .

build

El comando build convierte un archivo de Bicep en una plantilla de Azure Resource Manager JSON (plantilla de ARM). Normalmente, no es necesario ejecutar este comando porque se ejecuta automáticamente al implementar un archivo Bicep. Ejecútelo manualmente cuando desee ver la plantilla de ARM JSON que se crea a partir del archivo Bicep.

El uso de cualquiera de las siguientes características de Bicep habilita automáticamente la generación de código de la versión 2.0 del lenguaje:

  • tipos definidos por el usuario
  • funciones definidas por el usuario
  • importaciones en tiempo de compilación
  • características experimentales

En el ejemplo siguiente se convierte un archivo de Bicep denominado main.bicep a una plantilla de ARM denominada main.json. El nuevo archivo se crea en el mismo directorio que el archivo Bicep:

bicep build main.bicep

En el ejemplo siguiente se guarda main.json en un directorio diferente:

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

En el ejemplo siguiente se especifica el nombre y la ubicación del archivo que se va a crear:

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

Para imprimir el archivo en , use:

bicep build main.bicep --stdout

Si el archivo Bicep incluye un módulo que hace referencia a un registro externo, el comando build llama automáticamente a restore. El comando obtiene el archivo del Registro y lo almacena en la memoria caché local.

Nota:

El comando no actualiza la memoria caché. Para más información, consulte Comando restore.

Para evitar la restauración automática, use el modificador :

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

Para usar el modificador --no-restore, debe tener Bicep CLI versión 0.4.X o posterior.

Se produce un error en el proceso de compilación con el modificador si uno de los módulos externos aún no está almacenado en caché:

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

Cuando reciba este error, ejecute el comando sin el modificador o ejecute primero.

build-params

El comando compila un archivo en un archivo de parámetros JSON:

bicep build-params params.bicepparam

Este comando convierte un archivo de parámetros params.bicepparam en un archivo de parámetros JSON params.json.

decompile

El comando decompile convierte una plantilla de ARM JSON en un archivo Bicep:

bicep decompile main.json

Este comando crea un archivo llamado main.bicep en el mismo directorio que main.json. Si main. bicep existe en el mismo directorio, use el modificador --force para sobrescribir el archivo de Bicep existente.

Para obtener más información sobre el uso de este comando, consulte Decompile plantilla de ARM JSON para Bicep.

decompile-params

El comando descompila un archivo de parámetros JSON en un archivo de parámetros.

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

Este comando descompila un archivo de parámetros de azuredeploy.parameters.json en un archivo azuredeploy.parameters.bicepparam . Use para especificar la ruta de acceso al archivo Bicep (en relación con el archivo /> .

format

El comando format da formato a un archivo Bicep para que siga las convenciones de estilo recomendadas. Piense en él como formateador de código o "más bonito" para los archivos de Bicep. Tiene la misma función que el acceso directo SHIFT+ALT+F en Visual Studio Code.

bicep format main.bicep

generate-params

El comando generate-params compila un archivo de parámetros a partir del archivo de Bicep especificado y lo actualiza si hay un archivo de parámetros existente.

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

Este comando crea un archivo de parámetros de Bicep denominado main.bicepparam. El archivo de parámetros contiene todos los parámetros del archivo Bicep, independientemente de si están configurados con valores predeterminados o no.

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

Este comando crea un archivo de parámetros denominado main.parameters.json. El archivo de parámetros solo contiene los parámetros sin valores predeterminados configurados en el archivo Bicep.

install

El comando install agrega la CLI de Bicep al entorno local y solo está disponible a través del CLI de Azure. Para obtener más información, consulte Install Bicep tools.

Para instalar la versión más reciente, use:

N/A

Para instalar una versión específica, use el siguiente comando:

N/A

jsonrpc

El comando jsonrpc ejecuta la CLI de Bicep con una interfaz JSON-RPC. Con esta interfaz, puede interactuar mediante programación con la salida estructurada. También se evitan retrasos en el arranque en frío al compilar varios archivos. Esta configuración admite la creación de bibliotecas para interactuar con archivos Bicep mediante programación en idiomas que no son de .NET.

El formato de conexión para enviar y recibir entradas y salidas está delimitado por encabezados. Usa la siguiente estructura, donde y representan caracteres de retorno de carro y avance de línea:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n
  • es la longitud de la cadena, incluido el final .
  • es el mensaje JSON sin formato.

Por ejemplo:

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

Los métodos siguientes están disponibles a través de la interfaz JSON-RPC:

  • bicep/format

    Da formato a un archivo Bicep.

    • La solicitud:

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

    • La respuesta:

      {
  "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"
  }
}

      Si se ejecuta correctamente, se devuelve "success": true, con contenido que contiene el origen de Bicep con formato. En caso de error, con la descripción del error.

  • bicep/version

    Devuelve la versión de la CLI de Bicep.

    • La solicitud:

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

    • La respuesta:

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

Para conocer los métodos disponibles y los cuerpos de solicitud y respuesta, consulte ICliJsonRpcProtocol.cs. Para obtener un ejemplo de establecimiento de una conexión JSONRPC e interactuar con archivos de Bicep mediante programación mediante node, consulte jsonrpc.test.ts.

Uso de canalización con nombre

Use la siguiente sintaxis para conectarse a una canalización con nombre existente como un cliente JSONRPC:

bicep jsonrpc --pipe <named_pipe>`

es una canalización con nombre existente a la que conectar el cliente JSONRPC.

Para conectarse a una canalización con nombre en macOS o Linux:

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

Para conectarse a una canalización con nombre en Windows:

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

Para obtener más ejemplos, vea C# y node.js.

Uso del socket TCP

Use la siguiente sintaxis para conectarse a un socket TCP existente como cliente JSONRPC:

bicep jsonrpc --socket <tcp_socket>

es el número de socket al que se conecta el cliente JSONRPC.

Para conectarse a un socket TCP:

bicep jsonrpc --socket 12345

Uso de stdin y stdout

Para ejecutar la interfaz JSONRPC, use la sintaxis siguiente. Use y para mensajes:

bicep jsonrpc --stdio

lint

El comando lint devuelve los errores y linter rule infracciones de un archivo Bicep.

bicep lint main.bicep

Si el archivo Bicep incluye un módulo que hace referencia a un registro externo, el comando lint llama automáticamente a restore. El comando obtiene el archivo del Registro y lo almacena en la memoria caché local.

Nota:

El comando no actualiza la memoria caché. Para más información, consulte Comando restore.

Para evitar la restauración automática, use el modificador :

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

Se produce un error en el proceso de lint con el modificador si uno de los módulos externos aún no está almacenado en caché:

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

Cuando reciba este error, ejecute el comando sin el modificador o ejecute primero.

list-versions

El comando list-versions devuelve todas las versiones disponibles de la CLI de Bicep. Use este comando para ver si quiere actualizar o instalar una nueva versión. Este comando solo está disponible a través del CLI de Azure.

N/A

Publicar:

El comando agrega un módulo a un registro. El Azure registro de contenedor debe existir y la publicación de la cuenta en el registro debe tener los permisos correctos. Para obtener más información sobre cómo configurar un registro de módulos, consulte Use el registro privado para Bicep módulos. Para publicar un módulo, la cuenta debe tener el perfil y los permisos correctos para acceder al registro. Puede configurar el perfil y la precedencia de credenciales para autenticarse en el registro en el archivo de configuración Bicep.

Después de publicar el archivo en el registro, puede hacer referencia a él en un módulo.

Debe tener Bicep CLI versión 0.14.X o posterior para usar el comando publish y el parámetro --documentationUri/-d.

Para publicar un módulo en un registro, use:

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

Por ejemplo:

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

El comando no reconoce los alias especificados en un archivo bicepconfig.json. Proporcione la ruta de acceso completa del módulo.

Advertencia

La publicación en el mismo destino sobrescribe el módulo anterior. Incremente la versión al actualizar.

Restauración

Cuando el archivo Bicep usa módulos que publica en un registro, el comando restore obtiene copias de todos los módulos necesarios del registro. Almacena esas copias en una caché local. Un archivo Bicep solo se puede compilar cuando los archivos externos están disponibles en la caché local. Normalmente, la ejecución de la restauración no es necesaria, ya que el proceso de compilación la desencadena automáticamente.

Para restaurar módulos externos en la caché local, la cuenta debe tener el perfil y los permisos correctos para acceder al registro. Puede configurar la profile y precedencia de credenciales para autenticarse en el registro en el archivo de configuración de Bicep.

Para usar el comando restore, debe tener Bicep CLI versión 0.14.X o posterior.

Para restaurar manualmente los módulos externos de un archivo, use:

bicep restore <bicep-file>

El archivo Bicep que proporcione es el archivo que desea implementar. Debe contener un módulo que se vincula a un registro. Por ejemplo, puede restaurar el siguiente archivo:

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

Encontrará la memoria caché local en:

  • En Windows

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

  • En Linux

    /home/<username>/.bicep

  • En Mac

    ~/.bicep

El comando no actualiza la caché si un módulo ya está almacenado en caché. Para actualizar la memoria caché, puede eliminar la ruta de acceso del módulo de la memoria caché o usar el modificador con el comando .

snapshot

Mediante Bicep CLI v0.41.2 o posterior, puede usar el comando para crear una representación normalizada y determinista de una implementación de Bicep desde un archivo />

  • Diferencias visuales: ver exactamente cómo cambia una refactorización (como mover código a un módulo) las definiciones de recursos subyacentes.
  • Expresiones complejas: descripción de lo que una cadena o variable compleja se evalúa realmente antes de la implementación.
  • Validación de CI/CD: detecta automáticamente los cambios no deseados en la lógica de infraestructura durante las solicitudes de incorporación de cambios.

Creación de una instantánea

Este comando genera un archivo. Este archivo está "normalizado", lo que significa que elimina el ruido como los límites del módulo para que pueda centrarse en los propios recursos.

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

El siguiente archivo JSON muestra un ejemplo de instantánea:

{
  "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": []
}

Validar los cambios

Después de crear una instantánea, ejecute el comando en modo de validación. Compara el código de Bicep actual con la instantánea guardada y muestra una diferencia visual, similar al comando what-if pero completamente local.

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

Una salida de ejemplo tiene el siguiente aspecto:

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"

"Error de validación de instantáneas" indica diferencias entre las dos instantáneas.

Bicep instantánea de la CLI y What-if tienen estas diferencias:

Característica bicep snapshot az deployment group what-if
Ejecución Solo local (sin conexión) Basado en la nube (en línea)
Comparación Compara el código frente a un archivo guardado. Compara el código frente al estado de Azure activo.
Velocidad Extremadamente rápido Más lento (requiere llamadas API)
Caso de uso Refactorización y pruebas lógicas Comprobación de implementación previa final

Proporciona contexto

Al ejecutar Bicep instantánea, la CLI realiza una evaluación local del código. Puesto que no habla con Azure, no puede "preguntar" a la nube por el identificador de suscripción ni por el nombre del grupo de recursos actual.

Si el código usa funciones de entorno (como ), la instantánea producirá un error o devolverá marcadores de posición a menos que proporcione contexto específico a través de argumentos de la CLI.

Para simular un entorno de implementación real, puede pasar las marcas siguientes:

Argumento Propósito Valor de ejemplo
--subscription-id Reemplaza el valor devuelto por 00000000-1111-2222-3333-444444444444
--resource-group Reemplaza el valor devuelto por my-production-rg
--location Establece la ubicación predeterminada para westeurope
--tenant-id Reemplaza el valor devuelto por 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Reemplaza el valor devuelto por my-corp-mg 
bicep snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

upgrade

El comando actualiza la versión instalada a la versión más reciente. Este comando solo está disponible a través del CLI de Azure.

N/A

version

El comando devuelve la versión instalada:

bicep --version

Si no instaló la CLI de Bicep, verá un mensaje de error que indica que no se encontró la CLI de Bicep.

El comando muestra el número de versión:

Bicep CLI version 0.29.45 (57a44c0230)

Pasos siguientes

Para obtener más información sobre la implementación de un archivo de Bicep, consulte:

  • Last updated on