functions/Assert-BicepCliVersionInPath.ps1

# <copyright file="Assert-BicepCliVersionInPath.ps1" company="Endjin Limited">
# Copyright (c) Endjin Limited. All rights reserved.
# </copyright>

function Assert-BicepCliVersionInPath
{
    <#
    .SYNOPSIS
    Checks that the specified version of the Bicep CLI is available via the PATH.
 
    .DESCRIPTION
    Checks that the specified version of the Bicep CLI is available via the PATH (as required when using Az.PowerShell to deploy Bicep templates).
 
    When not found also checks whether a suitable version if available via Azure CLI. If so, the PATH is updated to make it available; otherwise a suitable version is installed via the Azure CLI.
 
    .PARAMETER RequiredBicepVersion
    Specifies that a particular version of the Bicep CLI is available, if not, then that version is installed via Azure CLI.
    An empty string (the default) means any version, and 'latest' means the latest version.
 
    .PARAMETER MinimumBicepVersion
    Specifies that a minimum version of the Bicep CLI is available, if not, then the latest version is installed via Azure CLI.
 
    .EXAMPLE
    ```powershell
    Assert-BicepCliVersionInPath
    ```
 
    Ensures any version of the Bicep CLI is available.
 
    .EXAMPLE
    ```powershell
    Assert-BicepCliVersionInPath -RequiredBicepVersion 'latest'
    ```
 
    Ensures the latest version of the Bicep CLI is available.
 
    .EXAMPLE
    ```powershell
    Assert-BicepCliVersionInPath -MinimumBicepVersion '0.38.33'
    ```
 
    Ensures at least version 0.38.33 of the Bicep CLI is available.
 
    .NOTES
    This function requires the Azure CLI to be available.
    #>

    [CmdletBinding(DefaultParameterSetName='requiredVersion')]
    [OutputType([System.Void])]
    param (
        # '' means any version
        # 'latest' means the latest version
        # '0.38.33' means the specific version
        [Parameter(ParameterSetName='requiredVersion')]
        [string] $RequiredBicepVersion = '',

        [Parameter(Mandatory, ParameterSetName='minimumVersion')]
        [string] $MinimumBicepVersion
    )

    # Setup wrapper functions to ease mocking of az-cli
    function _getBicepVersion {
        [CmdletBinding()]
        param ()
        $toolOutput = & bicep --version
        return (_extractBicepVersionFromOutput -VersionMessage "$toolOutput")
    }
    function _getAzBicepVersion {
        [CmdletBinding()]
        param (
            # Switches added to enable distinctly mocking multiple calls
            [switch] $Before,
            [switch] $After
        )
        $PSNativeCommandUseErrorActionPreference = $true
        try {
            $toolOutput = & az bicep version
            return (_extractBicepVersionFromOutput -VersionMessage "$toolOutput")
        }
        catch {
            # Not installed
            return $null
        }
    }
    function _installAzBicep {
        [CmdletBinding()]
        param (
            [Parameter(Mandatory)]
            [string] $Version
        )
        $PSNativeCommandUseErrorActionPreference = $true
        & az config set bicep.check_version=false
        & az config set bicep.use_binary_from_path=false
        & az bicep install --version $Version
    }
    function _getLatestBicepVersion {
        [CmdletBinding()]
        param ()
        # Calls the GitHub API, so only look it up when it is needed
        return (Invoke-RestMethod -Uri https://aka.ms/BicepLatestRelease | Select-Object -ExpandProperty tag_name).TrimStart('v')
    }
    function _extractBicepVersionFromOutput {
        [CmdletBinding()]
        param (
            [Parameter(Mandatory)]
            [AllowEmptyString()]
            [string] $VersionMessage
        )
        if ($VersionMessage -match "Bicep CLI version (\d+\.\d+\.\d+)") {
            return $matches[1]
        }
        else {
            throw "Unable to parse Bicep CLI version: $VersionMessage"
        }
    }

    Write-Verbose "Bicep version specification: [RequiredVersion='$RequiredBicepVersion'] [MinimumVersion='$MinimumBicepVersion']"

    # Az.PowerShell expects to find the Bicep CLI via the PATH environment variable
    $existingBicepCommand = Get-Command bicep -ErrorAction Ignore

    $existingBicepCommandVersion = $null
    if ($existingBicepCommand) {
        # Check the version currently installed
        if ($IsWindows) {
            $existingBicepCommandVersion = "{0}.{1}.{2}" -f $existingBicepCommand.Version.Major,
            $existingBicepCommand.Version.Minor,
            $existingBicepCommand.Version.Build
        }
        else {
            $existingBicepCommandVersion = _getBicepVersion
        }

        if ($existingBicepCommandVersion) {
            Write-Host "Existing installation of Bicep is v$existingBicepCommandVersion"
        }
        else {
            Write-Host "Existing Bicep version is unexpectedly unknown!"
        }
    }
    
    # Check to see whether we should be using the latest version available
    if ($RequiredBicepVersion -eq 'latest') {
        $RequiredBicepVersion = _getLatestBicepVersion
        Write-Verbose "Bicep CLI latest version: $RequiredBicepVersion"
    }
    
    $requiresInstallOrUpdate = $false
    # Determine if installation or update is needed based on parameter set
    if (-not $existingBicepCommandVersion) {
        # No existing version found - installation required
        $requiresInstallOrUpdate = $true
        if ($PSCmdlet.ParameterSetName -eq 'minimumVersion' -or !$RequiredBicepVersion) {
            $RequiredBicepVersion = _getLatestBicepVersion
        }
    }
    elseif ($PSCmdlet.ParameterSetName -eq 'requiredVersion') {
        # Check if specific version requirement is met
        if ($RequiredBicepVersion -and $existingBicepCommandVersion -ne $RequiredBicepVersion) {
            $requiresInstallOrUpdate = $true
        }
    }
    elseif ($PSCmdlet.ParameterSetName -eq 'minimumVersion') {
        # Check if minimum version requirement is met
        if ([version]$existingBicepCommandVersion -lt [version]$MinimumBicepVersion) {
            $requiresInstallOrUpdate = $true
            $RequiredBicepVersion = _getLatestBicepVersion
        }
    }

    if ($requiresInstallOrUpdate) {
        # If the installed version is not what we need, then we:
        # 1) fallback to using the mechanism in the Azure CLI to install Bicep
        # 2) insert that path to the front the PATH environment variable, so it is used ahead of any existing version

        # Check whether Azure CLI has previously installed the required version
        $existingAzCliBicepVersion = _getAzBicepVersion -Before
        Write-Verbose "az bicep version: $existingAzCliBicepVersion"
        if (!$existingAzCliBicepVersion -or $existingAzCliBicepVersion -ne $RequiredBicepVersion) {
            Write-Host "Installing Bicep CLI tool via Azure CLI: v$RequiredBicepVersion"
            _installAzBicep -Version "v$RequiredBicepVersion" | Out-String | Write-Host
            
            $existingAzCliBicepVersion = _getAzBicepVersion -After
            if ($existingAzCliBicepVersion -ne $RequiredBicepVersion) {
                throw "Unexpected Bicep version found. Expected '$RequiredBicepVersion', found '$existingAzCliBicepVersion'"
            }
        }

        # Update the PATH to ensure the Azure CLI copy of Bicep CLI is used by Az.PowerShell
        Write-Host 'Updating PATH to make Azure CLI instance of Bicep CLI available'
        $bicepPath = [IO.Path]::Join($HOME, ".azure", "bin")
        Set-Item -Path env:/PATH -Value (@($bicepPath, $env:PATH) -join [IO.Path]::PathSeparator)
        
        # Verify the install
        Get-Command bicep | Select-Object -ExpandProperty Path | Out-String | Write-Verbose
    }
}