Bicep Tip: Check for Outdated API Versions in Your Bicep Files

Bicep makes infrastructure-as-code simpler, but Azure’s evolving API versions can still trip you up. Microsoft frequently introduces new versions of resource providers, and while the latest version isn’t always the best fit, it’s useful to be aware of what you’re currently using.

In this post, you’ll learn how to scan your Bicep files for resource definitions that aren’t using the latest available API version—so you can review and decide if it’s time to update.

Why This Matters

• Keep your deployments aligned with the latest Azure features
• Detect inconsistent or outdated definitions across environments
• Build confidence in code modernization and audit compliance

What the Script Does

Accepts a single resource type as input, like Microsoft.Storage/storageAccounts
Uses Azure CLI to fetch the latest API version for that resource type
Recursively searches all .bicep files under the current directory
Reports which files (and lines) use older or hard-coded API versions

Usage Example

.\Test-BicepApiVersion.ps1 -resourceType "Microsoft.Storage/storageAccounts"

This will show all *.bicep files that reference the Microsoft.Storage/storageAccounts resource type, along with the API version in use.

param (
    [string]$resourceType  # Example: 'Microsoft.Storage/storageAccounts'
)

if (-not $resourceType) {
    Write-Error "Please provide a valid resource type (e.g., Microsoft.Storage/storageAccounts)."
    exit
}

# Split resourceType into namespace and resource type
$namespace = $resourceType.Split('/')[0]
$resource = $resourceType.Split('/')[1]

# Get all API versions for the specified resource type
$apiVersions = az provider show --namespace $namespace --query "resourceTypes[?resourceType=='$resource'].apiVersions" | ConvertFrom-Json

if (-not $apiVersions) {
    Write-Error "Could not retrieve API versions for $resourceType."
    exit
}

# Sort API versions in descending order and select the latest one
$apiVersionList = $apiVersions | Sort-Object -Descending
$latestApiVersion = $apiVersionList[0]

if (-not $latestApiVersion) {
    Write-Error "Could not determine the latest API version for $resourceType."
    exit
}

Write-Host "Latest API version for $resourceType : $latestApiVersion"

# Get all *.bicep files in the current directory and subdirectories
$files = Get-ChildItem -Path . -Recurse -Filter "*.bicep"

# Initialize an array to store the results for Out-GridView
$results = @()

# Loop through each Bicep file
foreach ($file in $files) {
    $fileContent = Get-Content $file.FullName

    # Track line number for better reference in the output
    $lineNumber = 0

    # Look for the resource definition that matches the provided resourceType
    foreach ($line in $fileContent) {
        $lineNumber++

        if ($line -match $resourceType) {
            # Extract the API version from the resource definition
            if ($line -match "@(\d{4}-\d{2}-\d{2})(\S*)") {
                $foundApiVersion = $matches[1]

                # Store the file, line, and found API version in an object
                $result = [pscustomobject]@{
                    FileName       = $file.FullName
                    LineNumber     = $lineNumber
                    ApiVersionUsed = $foundApiVersion
                    LineContent    = $line
                }

                # Add result to the array
                $results += $result
            }
        }
    }
}

# Output to GridView if any outdated API versions are found
if ($results.Count -eq 0) {
    Write-Host "No API versions found in the Bicep files matching $resourceType." -ForegroundColor Yellow
} else {
    if ($IsWindows) {
        $results | Out-GridView -Title "API Versions Used for $resourceType (Latest: $latestApiVersion)"
    } else {
        $results | Format-Table -AutoSize
    }
}

Maintained Version

This script is part of the pws-helpers library, publicly maintained on GitHub.

• Library: https://github.com/Jiihaa/pws-helpers/
• Script Path: scripts/Test-BicepApiVersion.ps1

What to Do With the Output

Once you identify older API versions:

• Check the Azure Bicep Resource Reference for breaking changes
• Update with caution—newest APIs may introduce changes in required fields
• Test changes in non-production environments before rollout

Conclusion

Automating your API version checks helps you maintain better control over infrastructure code. While newer versions don’t always mean better, this tool ensures you know where and why you’re using a specific version.

Pair this with CI/CD validations or PR checks for improved DevOps practices.