Azure PowerShell – Best Practices

Effective PowerShell scripting is essential for managing Azure resources at scale. This guide consolidates industry‑proven best practices to help you write clear, secure, and performant scripts.

Naming Conventions

Consistent naming improves readability and reduces errors.

Use Verb-Noun pattern (Get-AzVm, Set-AzResourceGroup)
Prefer approved verbs (Microsoft list)
Variables: camelCase for locals, PascalCase for parameters
Constants: UPPER_SNAKE_CASE

Error Handling

Gracefully handling failures prevents partial deployments.

try {
    New-AzResourceGroup -Name $rgName -Location $location -ErrorAction Stop
} catch {
    Write-Error "Failed to create resource group: $_"
    exit 1
}

Output Formatting

Return objects, not formatted strings, to enable pipeline usage.

# Bad
Write-Host "Created VM $($vm.Name) in $($vm.Location)"

# Good
[pscustomobject]@{
    Name     = $vm.Name
    Location = $vm.Location
    Id       = $vm.Id
}

Secure Credential Management

Never store plain‑text passwords in scripts.

$securePwd = Read-Host -AsSecureString "Enter password"
$credential = New-Object System.Management.Automation.PSCredential($user,$securePwd)

Leverage Azure Key Vault for production secret storage.

Module Structure

Encapsulate reusable functions in modules.

# Module folder layout
MyAzModule/
│─ MyAzModule.psd1
│─ MyAzModule.psm1
│─ Public/
│   └─ Get-MyAzResource.ps1
│─ Private/
│   └─ Invoke-AzApi.ps1

Export only public functions via Export-ModuleMember.

Performance Tuning

Batch commands: use -BatchSize when available.
Parallel execution: ForEach-Object -Parallel (PowerShell 7+).
Avoid unnecessary Select-Object / Where-Object in large pipelines.

Testing & Validation

Integrate Pester tests into CI pipelines.

Describe "Azure VM provisioning" {
    It "Creates a VM with the expected name" {
        $vm = New-AzVm -Name $expectedName -ResourceGroup $rg
        $vm.Name | Should -Be $expectedName
    }
}

Documentation Standards

Use comment‑based help (.SYNOPSIS, .DESCRIPTION, .EXAMPLE).
Provide Parameter metadata for each parameter.
Generate external docs with platyPS for markdown output.

Azure PowerShell Documentation