Leer en inglés

Compartir a través de


Inicio rápido: uso de tareas de MSBuild para convertir archivos y parámetros de Bicep en JSON

En este inicio rápido, aprenderá a usar el sistema de compilación en Visual Studio, MSBuild, para convertir archivos de Bicep en plantillas JSON de Azure Resource Manager (plantillas de ARM). También es posible usar MSBuild con la versión 0.23.x o posterior del paquete NuGet para convertir archivos de parámetros de Bicep a archivos de parámetros de Azure Resource Manager. En los ejemplos de este artículo se muestra cómo usar la línea de comandos con los archivos de proyecto de MSBuild y C# para la conversión, y con estos archivos se muestra cómo usar los archivos de proyecto en una canalización de integración continua de MSBuild.

Requisitos previos

  • Instalación de Visual Studio o Visual Studio Code. La versión de Visual Studio Community es gratis e instala .NET 6.0, .NET Core 3.1, el SDK de .NET, MSBuild, .NET Framework 4.8, el administrador de paquetes NuGet y el compilador de C#. En el instalador, seleccione Cargas de trabajo>Desarrollo de escritorio de .NET. Con Visual Studio Code, es necesario instalar las extensiones de Bicep y Herramientas de Azure Resource Manager (ARM).
  • Instale Azure PowerShell o un shell de línea de comandos para el sistema operativo.

En función de cómo se configure nuget.config en su entorno y si nuget.org no se configura como fuente de paquetes, es posible que tenga que ejecutar el siguiente comando:

PowerShell
dotnet nuget add source  https://api.nuget.org/v3/index.json -n nuget.org

En determinados entornos, el uso de una sola fuente de paquetes ayuda a evitar conflictos entre paquetes con el mismo identificador y versión, pero con contenido diferente en fuentes diferentes. Para los usuarios de Azure Artifacts, los orígenes ascendentes pueden almacenar paquetes de diferentes orígenes en una fuente.

Tareas de MSBuild y paquetes de Bicep

Use paquetes de la CLI y tareas de MSBuild a lo largo de la canalización de integración continua para convertir archivos de Bicep y archivos de parámetros Bicep en JSON. Esta funcionalidad se basa en los siguientes paquetes de NuGet:

Nombre del paquete Descripción
Azure.Bicep.MSBuild Tarea de MSBuild multiplataforma que invoca a la CLI de Bicep y compila archivos de Bicep en plantillas de ARM de JSON
Azure.Bicep.CommandLine.win-x64 CLI de Bicep para Windows
Azure.Bicep.CommandLine.linux-x64 CLI de Bicep para Linux
Azure.Bicep.CommandLine.osx-x64 CLI de Bicep para macOS

Estos vínculos muestran la última versión del paquete NuGet. En la captura de pantalla siguiente, se muestra la última versión del paquete NuGet que coincide con la versión de la CLI de Bicep:

Captura de pantalla en la que se muestra la última versión del paquete NuGet que coincide con la última versión de la CLI de Bicep.

  • Azure.Bicep.MSBuild

    Cuando el paquete Azure.Bicep.MSBuild se incluye en la propiedad PackageReference de un archivo de proyecto, importa la tarea de Bicep para invocar la CLI de Bicep:

    XML
    <ItemGroup>
      <PackageReference Include="Azure.Bicep.MSBuild" Version="0.24.24" />
      ...
    </ItemGroup>
    
    

    El paquete transforma la salida de la CLI de Bicep en errores de MSBuild e importa el destino BicepCompile para simplificar cómo se usa la tarea de Bicep. De manera predeterminada, BicepCompile se ejecuta después del destino Build, compilando todos los elementos de @(Bicep) y @(BicepParam). A continuación, deposita la salida en $(OutputPath) con el mismo nombre de archivo y una extensión .json.

    En el ejemplo siguiente, se muestra la configuración del archivo de proyecto para compilar los archivos main.bicep y main.bicepparam en el mismo directorio que el archivo del proyecto y colocando los archivos main.json y main.parameters.json en el directorio $(OutputPath).

    XML
    <ItemGroup>
      <Bicep Include="main.bicep" />
      <BicepParam Include="main.bicepparam" />
    </ItemGroup>
    

    Puede invalidad la ruta de acceso de salida por archivo mediante los metadatos de OutputFile en elementos Bicep. En el ejemplo siguiente, se buscan de forma recursiva todos los archivos main.bicep y se colocan los archivos .json compilados en $(OutputPath) en un subdirectorio con el mismo nombre en $(OutputPath):

    XML
    <ItemGroup>
      <Bicep Include="**\main.bicep" OutputFile="$(OutputPath)\%(RecursiveDir)\%(FileName).json" />
      <BicepParam Include="**\main.bicepparam" OutputFile="$(OutputPath)\%(RecursiveDir)\%(FileName).parameters.json" />
    </ItemGroup>
    

    Se pueden crear más personalizaciones estableciendo una de las siguientes propiedades en PropertyGroup en el proyecto:

    Nombre de propiedad Valor predeterminado Descripción
    BicepCompileAfterTargets Build Se usa como valor AfterTargets para el destino de BicepCompile. Cambie el valor para invalidar la programación del destino de BicepCompile en el proyecto.
    BicepCompileDependsOn Ninguna Se usa como valor DependsOnTargets para el destino de BicepCompile. Esta propiedad se puede establecer en destinos de los que quiera que el destino de BicepCompile dependa.
    BicepCompileBeforeTargets Ninguno Se usa como valor BeforeTargets para el destino de BicepCompile.
    BicepOutputPath $(OutputPath) Establezca esta propiedad para invalidar la ruta de acceso de salida predeterminada para la plantilla de ARM compilada. Los metadatos de OutputFile en los elementos Bicep tienen prioridad sobre este valor.

    Para que Azure.Bicep.MSBuild funcione, es necesario establecer una variable de entorno BicepPath. Consulte el siguiente elemento de viñeta para configurar BicepPath.

  • Azure.Bicep.CommandLine

    Los paquetes Azure.Bicep.CommandLine.* están disponibles para Windows, Linux y macOS. En el ejemplo siguiente, se hace referencia al paquete para Windows:

    XML
    <ItemGroup>
      <PackageReference Include="Azure.Bicep.CommandLine.win-x64" Version="__LATEST_VERSION__" />
      ...
    </ItemGroup>  
    

    Cuando se hace referencia a ellos en un archivo de proyecto, los paquetes Azure.Bicep.CommandLine.* establecen automáticamente la propiedad BicepPath en la ruta de acceso completa del archivo ejecutable Bicep para la plataforma. La referencia a este paquete se puede omitir si la CLI de Bicep se instala de otras maneras. En este caso, en lugar de hacer referencia a un paquete Azure.Bicep.Commandline, configure una variable de entorno denominada BicepPath o agregue BicepPath a PropertyGroup. Por ejemplo:

    En Windows:

    XML
    <PropertyGroup>
      <BicepPath>c:\users\john\.Azure\bin\bicep.exe</BicepPath>
      ...
    </PropertyGroup>
    

    En Linux:

    XML
    <PropertyGroup>
      <BicepPath>/usr/local/bin/bicep</BicepPath>
      ...
    </PropertyGroup>
    

Ejemplos de archivos de proyecto

En los ejemplos siguientes, se muestra cómo configurar archivos de proyecto de aplicación de consola de C# para convertir archivos de Bicep y archivos de parámetros de Bicep en JSON. En los siguientes ejemplos, reemplace __LATEST_VERSION__ por la última versión de los paquetes NuGet de Bicep. Consulte tareas de MSBuild y paquetes de Bicep para obtener más información sobre cómo encontrar el último paquete.

Ejemplos basados en SDK

Los ejemplos de .NET Core 3.1 y .NET 6 son similares. Sin embargo, .NET 6 usa un formato diferente para el archivo Program.cs. Para más información, vea Plantilla de aplicación de consola de C# de .NET 6 que genera instrucciones de nivel superior.

  • .NET 6

    XML
    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
        <RootNamespace>net6-sdk-project-name</RootNamespace>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
      </PropertyGroup>
    
      <ItemGroup>
        <PackageReference Include="Azure.Bicep.CommandLine.win-x64" Version="__LATEST_VERSION__" />
        <PackageReference Include="Azure.Bicep.MSBuild" Version="__LATEST_VERSION__" />
      </ItemGroup>
    
      <ItemGroup>
        <Bicep Include="**\main.bicep" OutputFile="$(OutputPath)\%(RecursiveDir)\%(FileName).json" />
        <BicepParam Include="**\main.bicepparam" OutputFile="$(OutputPath)\%(RecursiveDir)\%(FileName).parameters.json" />
      </ItemGroup>
    </Project>
    

    La propiedad RootNamespace contiene un valor de marcador de posición. Al crear un archivo de proyecto, el valor coincide con el nombre del proyecto.

  • .NET Core 3.1

    XML
    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.1</TargetFramework>
      </PropertyGroup>
    
      <ItemGroup>
        <PackageReference Include="Azure.Bicep.CommandLine.win-x64" Version="__LATEST_VERSION__" />
        <PackageReference Include="Azure.Bicep.MSBuild" Version="__LATEST_VERSION__" />
      </ItemGroup>
    
      <ItemGroup>
        <Bicep Include="**\main.bicep" OutputFile="$(OutputPath)\%(RecursiveDir)\%(FileName).json" />
        <BicepParam Include="**\main.bicepparam" OutputFile="$(OutputPath)\%(RecursiveDir)\%(FileName).parameters.json" />
      </ItemGroup>
    </Project>
    

Ejemplo del SDK NoTargets

El SDK de proyecto de MSBuild Microsoft.Build.NoTargets permite a los propietarios del árbol de proyecto definir proyectos que no compilen un ensamblado. Este SDK permite la creación de proyectos independientes que compilan solo archivos de Bicep.

XML
<Project Sdk="Microsoft.Build.NoTargets/__LATEST_MICROSOFT.BUILD.NOTARGETS.VERSION__">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Azure.Bicep.CommandLine.win-x64" Version="__LATEST_VERSION__" />
    <PackageReference Include="Azure.Bicep.MSBuild" Version="__LATEST_VERSION__" />
  </ItemGroup>

  <ItemGroup>
    <Bicep Include="main.bicep"/>
    <BicepParam Include="main.bicepparam"/>
  </ItemGroup>
</Project>

La última versión de Microsoft.Build.NoTargets se puede encontrar en Microsoft.Build.NoTargets. Para Microsoft.Build.NoTargets, especifique una versión como Microsoft.Build.NoTargets/3.7.56.

XML
<Project Sdk="Microsoft.Build.NoTargets/3.7.56">
  ...
</Project>

Ejemplo de marco clásico

Use solo el ejemplo clásico si los ejemplos anteriores no le funcionasen. En este ejemplo, las propiedades ProjectGuid, RootNamespace y AssemblyName contienen valores de marcador de posición. Al crear un archivo de proyecto, se crea un GUID único y los valores de nombre coinciden con el nombre del proyecto.

XML
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <ProjectGuid>{11111111-1111-1111-1111-111111111111}</ProjectGuid>
    <OutputType>Exe</OutputType>
    <RootNamespace>ClassicFramework</RootNamespace>
    <AssemblyName>ClassicFramework</AssemblyName>
    <TargetFrameworkVersion>v4.8</TargetFrameworkVersion>
    <FileAlignment>512</FileAlignment>
    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
    <Deterministic>true</Deterministic>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <PlatformTarget>AnyCPU</PlatformTarget>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <OutputPath>bin\Debug\</OutputPath>
    <DefineConstants>DEBUG;TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <PlatformTarget>AnyCPU</PlatformTarget>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <OutputPath>bin\Release\</OutputPath>
    <DefineConstants>TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <ItemGroup>
    <Reference Include="System" />
    <Reference Include="System.Core" />
    <Reference Include="System.Xml.Linq" />
    <Reference Include="System.Data.DataSetExtensions" />
    <Reference Include="Microsoft.CSharp" />
    <Reference Include="System.Data" />
    <Reference Include="System.Net.Http" />
    <Reference Include="System.Xml" />
  </ItemGroup>
  <ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.config" />
    <Bicep Include="main.bicep" />
    <BicepParam Include="main.bicepparam" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Azure.Bicep.CommandLine.win-x64">
      <Version>__LATEST_VERSION__</Version>
    </PackageReference>
    <PackageReference Include="Azure.Bicep.MSBuild">
      <Version>__LATEST_VERSION__</Version>
    </PackageReference>
  </ItemGroup>
  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
</Project>

Conversión de Bicep en JSON

En estos ejemplos se muestra cómo usar MSBuild para convertir un archivo de Bicep y un archivo de parámetros de Bicep en JSON. Empiece por crear un archivo de proyecto para .NET, .NET Core 3.1 o el marco clásico. A continuación, genere un archivo de Bicep y un archivo de parámetros de Bicep antes de ejecutar MSBuild para convertirlos a JSON.

Crear proyecto

Para usar la CLI de .NET para compilar un proyecto en .NET:

  1. Abra Visual Studio Code y seleccione Terminal>Nuevo terminal para iniciar una sesión de PowerShell.

  2. Cree un directorio denominado msBuildDemo y vaya al directorio. En este ejemplo se usa C:\msBuildDemo:

    PowerShell
    Set-Location -Path C:\
    New-Item -Name .\msBuildDemo -ItemType Directory
    Set-Location -Path .\msBuildDemo
    
  3. Ejecute el comando dotnet para crear una consola nueva con el marco .NET 6:

    PowerShell
    dotnet new console --framework net6.0
    

    Este comando crea un archivo de proyecto con el mismo nombre que el directorio, msBuildDemo.csproj. Consulte este tutorial denominado Creación de una aplicación de consola de .NET con Visual Studio Code para obtener más información sobre cómo crear una aplicación de consola desde Visual Studio Code.

  4. Abra msBuildDemo.csproj por un editor y reemplace el contenido por el ejemplo de .NET 6 o el SDK de NoTargets. Además, reemplace __LATEST_VERSION__ por la última versión del paquete NuGet de Bicep.

  5. Guarde el archivo.

Creación de un archivo de Bicep

Creación de un archivo de Bicep y un archivo BicepParam antes de convertirlos en JSON:

  1. Cree un archivo main.bicep en la misma carpeta que el archivo del proyecto (por ejemplo: el directorio C:\msBuildDemo), además del siguiente contenido:

    Bicep
    @allowed([
      'Premium_LRS'
      'Premium_ZRS'
      'Standard_GRS'
      'Standard_GZRS'
      'Standard_LRS'
      'Standard_RAGRS'
      'Standard_RAGZRS'
      'Standard_ZRS'
    ])
    @description('Storage account type.')
    param storageAccountType string = 'Standard_LRS'
    
    @description('Location for all resources.')
    param location string = resourceGroup().location
    
    var storageAccountName = 'storage${uniqueString(resourceGroup().id)}'
    
    resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
      name: storageAccountName
      location: location
      sku: {
        name: storageAccountType
      }
      kind: 'StorageV2'
    }
    
    output storageAccountNameOutput string = storageAccount.name
    
  2. Cree un archivo main.bicepparam en el directorio C:\msBuildDemo con el siguiente contenido:

    Bicep
    using './main.bicep'
    
    param prefix = '{prefix}'
    

    Reemplace {prefix} por un valor de cadena usado como prefijo para el nombre de la cuenta de almacenamiento.

Ejecución de MSBuild

Ejecute MSBuild para convertir el archivo de Bicep y el archivo de parámetros de Bicep en el JSON:

  1. Abra una sesión de terminal de Visual Studio Code.

  2. En la sesión de PowerShell, vaya a la carpeta que contiene el archivo del proyecto. Por ejemplo, el directorio C:\msBuildDemo.

  3. Ejecutar MSBuild.

    PowerShell
    MSBuild.exe -restore .\msBuildDemo.csproj
    

    El parámetro restore crea las dependencias necesarias para compilar el archivo Bicep durante la compilación inicial. El parámetro es opcional después de la compilación inicial.

    Para usar .NET Core, ejecute:

    PowerShell
    dotnet build .\msBuildDemo.csproj
    

    o

    PowerShell
    dotnet restore .\msBuildDemo.csproj
    
  4. Vaya al directorio de salida y abra el archivo main.json, que debería ser similar al ejemplo siguiente.

    MSBuild crea un directorio de salida basado en la versión del SDK o del marco:

    • .NET 6: \bin\Debug\net6.0
    • .NET Core 3.1: \bin\Debug\netcoreapp3.1
    • SDK de NoTargets: \bin\Debug\net48
    • Marco clásico: \bin\Debug
    JSON
    {
      "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
      "contentVersion": "1.0.0.0",
      "metadata": {
        "_generator": {
          "name": "bicep",
          "version": "0.8.9.13224",
          "templateHash": "12345678901234567890"
        }
      },
      "parameters": {
        "storageAccountType": {
          "type": "string",
          "defaultValue": "Standard_LRS",
          "metadata": {
            "description": "Storage account type."
          },
          "allowedValues": [
            "Premium_LRS",
            "Premium_ZRS",
            "Standard_GRS",
            "Standard_GZRS",
            "Standard_LRS",
            "Standard_RAGRS",
            "Standard_RAGZRS",
            "Standard_ZRS"
          ]
        },
        "location": {
          "type": "string",
          "defaultValue": "[resourceGroup().location]",
          "metadata": {
            "description": "Location for all resources."
          }
        }
      },
      "variables": {
        "storageAccountName": "[format('storage{0}', uniqueString(resourceGroup().id))]"
      },
      "resources": [
        {
          "type": "Microsoft.Storage/storageAccounts",
          "apiVersion": "2023-04-01",
          "name": "[variables('storageAccountName')]",
          "location": "[parameters('location')]",
          "sku": {
            "name": "[parameters('storageAccountType')]"
          },
          "kind": "StorageV2"
        }
      ],
      "outputs": {
        "storageAccountNameOutput": {
          "type": "string",
          "value": "[variables('storageAccountName')]"
        }
      }
    }
    
  5. El archivo main.parameters.json debe ser similar al siguiente:

JSON
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "value": "mystore"
    }
  }
}

Si realiza cambios o quiere volver a ejecutar la compilación, elimine el directorio de salida para que se puedan crear nuevos archivos.

Limpieza de recursos

Cuando haya terminado con los archivos, elimine el directorio. En este ejemplo, elimine C:\msBuildDemo.

PowerShell
Remove-Item -Path "C:\msBuildDemo" -Recurse

Pasos siguientes