Quickstart: Use MSBuild to convert Bicep to JSON

Article
09/26/2022
8 minutes to read

This article describes how to use MSBuild to convert a Bicep file to Azure Resource Manager template (ARM template) JSON. The examples use MSBuild from the command line with C# project files that convert Bicep to JSON. The project files are examples that can be used in an MSBuild continuous integration (CI) pipeline.

Prerequisites

You'll need the latest versions of the following software:

Visual Studio. The free community version will install .NET 6.0, .NET Core 3.1, .NET SDK, MSBuild, .NET Framework 4.8, NuGet package manager, and C# compiler. From the installer, select Workloads > .NET desktop development.
Visual Studio Code with the extensions for Bicep and Azure Resource Manager (ARM) Tools.
PowerShell or a command-line shell for your operating system.

MSBuild tasks and CLI packages

If your existing continuous integration (CI) pipeline relies on MSBuild, you can use MSBuild tasks and CLI packages to convert Bicep files into ARM template JSON.

The functionality relies on the following NuGet packages. The latest NuGet package versions match the latest Bicep version.

Package Name	Description
Azure.Bicep.MSBuild	Cross-platform MSBuild task that invokes the Bicep CLI and compiles Bicep files into ARM template JSON.
Azure.Bicep.CommandLine.win-x64	Bicep CLI for Windows.
Azure.Bicep.CommandLine.linux-x64	Bicep CLI for Linux.
Azure.Bicep.CommandLine.osx-x64	Bicep CLI for macOS.

Azure.Bicep.MSBuild package

When referenced in a project file's PackageReference the Azure.Bicep.MSBuild package imports the Bicep task that's used to invoke the Bicep CLI. The package converts its output into MSBuild errors and the BicepCompile target that's used to simplify the Bicep task's usage. By default the BicepCompile runs after the Build target and compiles all @(Bicep) items and places the output in $(OutputPath) with the same file name and the .json extension.

The following example compiles one.bicep and two.bicep files in the same directory as the project file and places the compiled one.json and two.json in the $(OutputPath) directory.

<ItemGroup>
  <Bicep Include="one.bicep" />
  <Bicep Include="two.bicep" />
</ItemGroup>

You can override the output path per file using the OutputFile metadata on Bicep items. The following example will recursively find all main.bicep files and place the compiled .json files in $(OutputPath) under a subdirectory with the same name in $(OutputPath):

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

More customizations can be performed by setting one of the following properties in your project:

Property Name	Default Value	Description
`BicepCompileAfterTargets`	`Build`	Used as `AfterTargets` value for the `BicepCompile` target. Change the value to override the scheduling of the `BicepCompile` target in your project.
`BicepCompileDependsOn`	None	Used as `DependsOnTargets` value for the `BicepCompile` target. This property can be set to targets that you want `BicepCompile` target to depend on.
`BicepCompileBeforeTargets`	None	Used as `BeforeTargets` value for the `BicepCompile` target.
`BicepOutputPath`	`$(OutputPath)`	Set this property to override the default output path for the compiled ARM template. `OutputFile` metadata on `Bicep` items takes precedence over this value.

The Azure.Bicep.MSBuild requires the BicepPath property to be set either in order to function. You may set it by referencing the appropriate Azure.Bicep.CommandLine.* package for your operating system or manually by installing the Bicep CLI and setting the BicepPath environment variable or MSBuild property.

Azure.Bicep.CommandLine packages

The Azure.Bicep.CommandLine.* packages are available for Windows, Linux, and macOS. When referenced in a project file via a PackageReference, the Azure.Bicep.CommandLine.* packages set the BicepPath property to the full path of the Bicep executable for the platform. The reference to this package may be omitted if Bicep CLI is installed through other means and the BicepPath environment variable or MSBuild property are set accordingly.

SDK-based examples

The following examples contain a default Console App SDK-based C# project file that was modified to convert Bicep files into ARM templates. Replace __LATEST_VERSION__ with the latest version of the Bicep NuGet packages.

The .NET Core 3.1 and .NET 6 examples are similar. But .NET 6 uses a different format for the Program.cs file. For more information, see .NET 6 C# console app template generates top-level statements.

.NET 6

In this example, the RootNamespace property contains a placeholder value. When you create a project file, the value matches your project's name.

<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" />
  </ItemGroup>
</Project>

.NET Core 3.1

<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" />
  </ItemGroup>
</Project>

NoTargets SDK

The following example contains a project that converts Bicep files into ARM templates using Microsoft.Build.NoTargets. This SDK allows creation of standalone projects that compile only Bicep files. Replace __LATEST_VERSION__ with the latest version of the Bicep NuGet packages.

For Microsoft.Build.NoTargets, specify a version like Microsoft.Build.NoTargets/3.5.6.

<Project Sdk="Microsoft.Build.NoTargets/__LATEST_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"/>
  </ItemGroup>
</Project>

Classic framework

The following example converts Bicep to JSON inside a classic project file that's not SDK-based. Only use the classic example if the previous examples don't work for you. Replace __LATEST_VERSION__ with the latest version of the Bicep NuGet packages.

In this example, the ProjectGuid, RootNamespace and AssemblyName properties contain placeholder values. When you create a project file, a unique GUID is created, and the name values match your project's name.

<?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" />
  </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>

Convert Bicep to JSON

The following examples show how MSBuild converts a Bicep file to JSON. Follow the instructions to create one of the project files for .NET, .NET Core 3.1, or Classic framework. Then continue to create the Bicep file and run MSBuild.

Build a project in .NET with the dotnet CLI.

Open Visual Studio code and select Terminal > New Terminal to start a PowerShell session.
Create a directory named bicep-msbuild-demo and go to the directory. This example uses C:\bicep-msbuild-demo.
```
New-Item -Name .\bicep-msbuild-demo -ItemType Directory
Set-Location -Path .\bicep-msbuild-demo
```
Run the dotnet command to create a new console with the .NET 6 framework.
```
dotnet new console --framework net6.0
```
The project file uses the same name as your directory, bicep-msbuild-demo.csproj. For more information about how to create a console application from Visual Studio Code, see the tutorial.
Replace the contents of bicep-msbuild-demo.csproj with the .NET 6 or NoTargets SDK examples.
Replace __LATEST_VERSION__ with the latest version of the Bicep NuGet packages.
Save the file.

Build a project in .NET Core 3.1 using the dotnet CLI.

Open Visual Studio code and select Terminal > New Terminal to start a PowerShell session.
Create a directory named bicep-msbuild-demo and go to the directory. This example uses C:\bicep-msbuild-demo.
```
New-Item -Name .\bicep-msbuild-demo -ItemType Directory
Set-Location -Path .\bicep-msbuild-demo
```
Run the dotnet command to create a new console with the .NET 6 framework.
```
dotnet new console --framework netcoreapp3.1
```
The project file is named the same as your directory, bicep-msbuild-demo.csproj. For more information about how to create a console application from Visual Studio Code, see the tutorial.
Replace the contents of bicep-msbuild-demo.csproj with the .NET Core 3.1 or NoTargets SDK examples.
Replace __LATEST_VERSION__ with the latest version of the Bicep NuGet packages.
Save the file.

Build a project using the classic framework.

To create the project file and dependencies, use Visual Studio.

Open Visual Studio.
Select Create a new project.
For the C# language, select Console App (.NET Framework) and select Next.
Enter a project name. For this example, use bicep-msbuild-demo for the project.
Select Place solution and project in same directory.
Select .NET Framework 4.8.
Select Create.

If you know how to unload a project and reload a project, you can edit bicep-msbuild-demo.csproj in Visual Studio.

Otherwise, edit the project file in Visual Studio Code.

Open Visual Studio Code and go to the bicep-msbuild-demo directory.
Replace bicep-msbuild-demo.csproj with the Classic framework code sample.
Replace __LATEST_VERSION__ with the latest version of the Bicep NuGet packages.
Save the file.

Create Bicep file

You'll need a Bicep file that will be converted to JSON.

Use Visual Studio Code and create a new file.
Copy the following sample and save it as main.bicep in the C:\bicep-msbuild-demo directory.

@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@2022-05-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
}

output storageAccountNameOutput string = storageAccount.name

Run MSBuild

Run MSBuild to convert the Bicep file to JSON.

Open a Visual Studio Code terminal session.
In the PowerShell session, go to the C:\bicep-msbuild-demo directory.
Run MSBuild.
```
MSBuild.exe -restore .\bicep-msbuild-demo.csproj
```
The restore parameter creates dependencies needed to compile the Bicep file during the initial build. The parameter is optional after the initial build.

Go to the output directory and open the main.json file that should look like the sample.

MSBuild creates an output directory based on the SDK or framework version:

.NET 6: \bin\Debug\net6.0
.NET Core 3.1: \bin\Debug\netcoreapp3.1
NoTargets SDK: \bin\Debug\net48
Classic framework: \bin\Debug

{
  "$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": "2022-05-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2"
    }
  ],
  "outputs": {
    "storageAccountNameOutput": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    }
  }
}

If you make changes or want to rerun the build, delete the output directory so new files can be created.

Clean up resources

When you're finished with the files, delete the directory. For this example, delete C:\bicep-msbuild-demo.

Remove-Item -Path "C:\bicep-msbuild-demo" -Recurse

Next steps

For more information about MSBuild, see MSBuild reference and .NET project files.
To learn more about MSBuild properties, items, targets, and tasks, see MSBuild concepts.
For more information about the .NET CLI, see .NET CLI overview.