Introduction

When deploying Azure resources using Bicep, parameter files can be used for separating environment-specific configurations from your infrastructure templates. Originally Bicep supported JSON parameter files, but in recent years Microsoft also introduced Bicep Parameters files (.bicepparam) as an alternative.

What are Bicep Parameters Files?

Bicep Parameters files are Bicep’s native parameter file format, introduced to provide a more intuitive and type-safe way to define parameters for Bicep deployments. Unlike JSON parameter files, which are verbose and error-prone, Bicep Parameters files use the same Bicep syntax you’re already familiar with, making them easier to read, write, and maintain.

A Bicep Parameters file uses the .bicepparam extension and directly references the Bicep template it’s designed to work with, enabling IntelliSense, validation, and type checking during development.

Benefits of Bicep Parameters Files Over JSON

1. Strong Typing and IntelliSense Support

One of the most significant advantages of Bicep Parameters files is strong typing. When you reference a Bicep template in your .bicepparam file, your IDE (e.g. VS Code) provides IntelliSense support. This means you get:

• Auto-completion for parameter names
• Type validation to ensure you’re passing the correct data types
• Immediate feedback on required vs. optional parameters
• Inline documentation from the Bicep template’s parameter descriptions

2. Simplified Syntax

Bicep Parameters files use Bicep’s clean, readable syntax instead of JSON’s verbose structure. Compare these examples:

JSON Parameter File:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "value": "mystorageaccount"
    },
    "location": {
      "value": "eastus"
    },
    "skuName": {
      "value": "Standard_LRS"
    }
  }
}

Bicep Parameters File:

using './storage.bicep'

param storageAccountName = 'mystorageaccount'
param location = 'eastus'
param skuName = 'Standard_LRS'

The Bicep Parameters version is significantly cleaner, with less boilerplate and improved readability.

3. Direct Template Reference

The using statement at the top of a Bicep Parameters file creates a direct link to your Bicep template. This provides several benefits:

• The parameter file is validated against the actual template during authoring
• Changes to the template are immediately reflected in parameter file validation
• No risk of using a parameter file with the wrong template
• Refactoring becomes safer as tooling understands the relationship

Integrating with Azure Verified Modules (AVM)

Azure Verified Modules (AVM) are open-source Bicep modules maintained by Microsoft and the community. Below is an example of how to use them with Bicep Parameters files. These param files use the modules directly, but in most cases you would be creating your own main.bicep that calls various AVM modules for final deployment.

Example: Deploying a Storage Account with AVM

dev.bicepparam:

using 'br/public:avm/res/storage/storage-account:0.31.0'

param name = 'mystoragedev001'
param location = 'eastus'
param skuName = 'Standard_LRS'
param enableHierarchicalNamespace = false
param networkAcls = {
  defaultAction: 'Allow'
  bypass: 'AzureServices'
}
param tags = {
  Environment: 'Development'
  CostCenter: 'Engineering'
  ManagedBy: 'Bicep'
}

prod.bicepparam:

using 'br/public:avm/res/storage/storage-account:0.31.0'

param name = 'mystorageprod001'
param location = 'eastus2'
param skuName = 'Standard_GRS'
param enableHierarchicalNamespace = true
param networkAcls = {
  defaultAction: 'Deny'
  bypass: 'AzureServices'
  ipRules: [
    {
      value: '203.0.113.0/24'
      action: 'Allow'
    }
  ]
  virtualNetworkRules: [
    {
      id: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/network-rg/providers/Microsoft.Network/virtualNetworks/prod-vnet/subnets/storage-subnet'
      action: 'Allow'
    }
  ]
}
param tags = {
  Environment: 'Production'
  CostCenter: 'Operations'
  ManagedBy: 'Bicep'
  Criticality: 'High'
}

Best Practices for Bicep Parameters Files

1. One Parameter File Per Environment

Create separate parameter files for each environment (dev, test, prod) with the same base name as your Bicep template:

infrastructure/
  main.bicep
  dev.bicepparam
  test.bicepparam
  prod.bicepparam

2. Use Meaningful Parameter Values

Take advantage of Bicep Parameter file’s expression support to create self-documenting parameter files:

using './main.bicep'

param environment = 'production'
param region = 'eastus2'
param appName = 'myapplication'

// Computed values
param storageAccountName = '${appName}${environment}storage'
param keyVaultName = '${appName}-${environment}-kv'

3. Document Complex Parameters

While Bicep Parameters files inherit parameter descriptions from the Bicep template, add comments for complex configurations:

using './main.bicep'

// Network ACLs configured for production security requirements
// Only allowing traffic from approved subnets and IP ranges
param networkAcls = {
  defaultAction: 'Deny'
  bypass: 'AzureServices'
  ipRules: [
    { value: '203.0.113.0/24', action: 'Allow' }  // Office network
    { value: '198.51.100.0/24', action: 'Allow' } // VPN range
  ]
}

4. Version Control Strategy

Store Bicep Parameters files alongside your Bicep templates in version control. Use clear naming conventions and directory structures:

infrastructure/
  modules/
    storage/
      main.bicep
      dev.bicepparam
      prod.bicepparam
    networking/
      main.bicep
      dev.bicepparam
      prod.bicepparam
  main.bicep
  dev.bicepparam
  prod.bicepparam

Migration from JSON to BicepParam

If you have existing JSON parameter files, migration is straightforward. The Azure CLI and Bicep tooling support both formats, so you can migrate incrementally.

Migration Steps:

1. Create a .bicepparam file with the same base name as your JSON file
2. Add the using statement pointing to your Bicep template
3. Convert each parameter from JSON format to Bicep parameter syntax
4. Test the Bicep Parameters file with az deployment group validate
5. Update your pipelines to use the new file
6. Remove the old JSON parameter file

You can also use the built-in decompile command to convert existing JSON parameter files:

az bicep decompile-params --file parameters.json

Further Reading

• Bicep Parameter Files Documentation
• Azure Verified Modules
• Bicep Best Practices
• Azure DevOps Bicep Deployment
• Bicep Module Registry