plan-forge powershell.instructions.md

PowerShell Best Practices for Azure IaC

Script Structure

#Requires -Modules Az.Accounts, Az.Resources
#Requires -Version 7.6

<#
.SYNOPSIS
    Short one-line description.
.DESCRIPTION
    Longer description of what the script does.
.PARAMETER EnvironmentName
    The target environment (dev, test, staging, prod).
.EXAMPLE
    .\Deploy-Infrastructure.ps1 -EnvironmentName prod
#>
[CmdletBinding(SupportsShouldProcess)]
param (
    [Parameter(Mandatory)]
    [ValidateSet('dev', 'test', 'staging', 'prod')]
    [string]$EnvironmentName,

    [Parameter()]
    [string]$Location = 'eastus'
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

Functions

# ✅ Approved verbs, CmdletBinding, typed parameters
function New-ResourceGroupIfNotExists {
    [CmdletBinding(SupportsShouldProcess)]
    param (
        [Parameter(Mandatory)]
        [string]$Name,

        [Parameter(Mandatory)]
        [string]$Location,

        [Parameter()]
        [hashtable]$Tags = @{}
    )

    $existing = Get-AzResourceGroup -Name $Name -ErrorAction SilentlyContinue

    if ($null -eq $existing) {
        if ($PSCmdlet.ShouldProcess($Name, 'Create resource group')) {
            Write-Verbose "Creating resource group '$Name' in '$Location'"
            New-AzResourceGroup -Name $Name -Location $Location -Tag $Tags
        }
    } else {
        Write-Verbose "Resource group '$Name' already exists. Skipping."
        $existing
    }
}

Error Handling

# ✅ Try/catch with specific error types and meaningful messages
try {
    $deployment = New-AzResourceGroupDeployment @deployParams
    Write-Verbose "Deployment succeeded: $($deployment.DeploymentName)"
}
catch [Microsoft.Azure.Commands.ResourceManager.Cmdlets.SdkModels.PSInvalidOperationException] {
    Write-Error "Deployment validation failed: $($_.Exception.Message)"
    throw
}
catch {
    Write-Error "Unexpected error during deployment: $($_.Exception.Message)"
    throw
}