Best Practices and Production

The Script That Broke Production

Three years into my PowerShell journey, I considered myself proficient. I'd written hundreds of scripts. Then I wrote one that brought down a production service.

The script worked perfectly in dev and test. But in production, it:

• Had no error handling for a specific edge case

• Used hardcoded credentials (from a test account that didn't exist in prod)

• Didn't log what it was doing

• Had no rollback mechanism

• Wasn't tested with production-sized data

The outage lasted 2 hours. The post-mortem was uncomfortable. But I learned more from that failure than from 100 successful scripts. This article is every lesson I learned the hard way, so you don't have to.

Code Organization and Structure

Script Template

Use this template for production scripts:

<#
.SYNOPSIS
    Brief description of what the script does.

.DESCRIPTION
    Detailed description including prerequisites, dependencies, and expected behavior.

.PARAMETER ParameterName
    Description of what this parameter does.

.EXAMPLE
    .\Script-Name.ps1 -Parameter "Value"
    Description of what this example does.

.NOTES
    Author: Your Name
    Date: 2024-01-15
    Version: 1.0.0
    
.LINK
    https://docs.yourcompany.com/scripts/script-name
#>

#Requires -Version 7.0
#Requires -Modules Az.Compute

[CmdletBinding(SupportsShouldProcess=$true)]
param(
    [Parameter(Mandatory=$true, HelpMessage="Enter the resource name")]
    [ValidateNotNullOrEmpty()]
    [string]$ResourceName,
    
    [Parameter(Mandatory=$false)]
    [ValidateSet("Development", "Staging", "Production")]
    [string]$Environment = "Development"
)

#region Configuration
$ErrorActionPreference = "Stop"
$ProgressPreference = "SilentlyContinue"  # Faster execution

$logPath = "C:\Logs\$(Split-Path -Leaf $PSCommandPath)-$(Get-Date -Format 'yyyy-MM-dd').log"
$configPath = "C:\Config\config.json"
#endregion

#region Functions
function Write-ScriptLog {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Message,
        
        [Parameter(Mandatory=$false)]
        [ValidateSet("INFO", "WARNING", "ERROR")]
        [string]$Level = "INFO"
    )
    
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $logMessage = "$timestamp [$Level] $Message"
    
    # Write to file
    $logMessage | Out-File -FilePath $logPath -Append
    
    # Write to console
    switch ($Level) {
        "ERROR"   { Write-Error $Message }
        "WARNING" { Write-Warning $Message }
        default   { Write-Verbose $Message }
    }
}

function Test-Prerequisites {
    [CmdletBinding()]
    param()
    
    Write-ScriptLog "Checking prerequisites..."
    
    # Check required modules
    $requiredModules = @("Az.Compute", "Az.Storage")
    foreach ($module in $requiredModules) {
        if (-not (Get-Module -Name $module -ListAvailable)) {
            throw "Required module not found: $module"
        }
    }
    
    # Check configuration file
    if (-not (Test-Path $configPath)) {
        throw "Configuration file not found: $configPath"
    }
    
    Write-ScriptLog "Prerequisites validated successfully"
}
#endregion

#region Main Script
try {
    Write-ScriptLog "Script started: $PSCommandPath"
    Write-ScriptLog "Parameters: ResourceName=$ResourceName, Environment=$Environment"
    
    # Validate prerequisites
    Test-Prerequisites
    
    # Load configuration
    $config = Get-Content $configPath | ConvertFrom-Json
    Write-ScriptLog "Configuration loaded"
    
    # Main logic here
    if ($PSCmdlet.ShouldProcess($ResourceName, "Process resource")) {
        # Your code here
        Write-ScriptLog "Processing $ResourceName in $Environment environment"
    }
    
    Write-ScriptLog "Script completed successfully"
    exit 0
}
catch {
    Write-ScriptLog "Script failed: $_" -Level "ERROR"
    Write-ScriptLog $_.ScriptStackTrace -Level "ERROR"
    exit 1
}
finally {
    Write-ScriptLog "Script execution ended"
}
#endregion

Naming Conventions

PowerShell Style Guide

# Functions: Verb-Noun with PascalCase
function Get-UserInformation { }
function Set-DatabaseConfiguration { }

# Variables: PascalCase for readability
$ServerName = "WEB01"
$ConfigurationPath = "C:\Config"
$UserList = @()

# Parameters: PascalCase, descriptive
param(
    [string]$ServerName,
    [int]$RetryCount,
    [switch]$Force
)

# Constants: UPPERCASE
$MAX_RETRIES = 5
$DEFAULT_TIMEOUT = 30

# Use full cmdlet names in scripts (not aliases)
Get-ChildItem  # Not 'ls' or 'dir'
Where-Object   # Not '?'
ForEach-Object # Not '%'

PSScriptAnalyzer

Static code analysis tool for PowerShell.

Installation

Install-Module -Name PSScriptAnalyzer -Scope CurrentUser

Usage

# Analyze a script
Invoke-ScriptAnalyzer -Path .\MyScript.ps1

# Analyze and show only errors
Invoke-ScriptAnalyzer -Path .\MyScript.ps1 -Severity Error

# Analyze entire directory
Invoke-ScriptAnalyzer -Path C:\Scripts -Recurse

# Fix issues automatically (where possible)
Invoke-ScriptAnalyzer -Path .\MyScript.ps1 -Fix

Custom Rules

Create .vscode/PSScriptAnalyzerSettings.psd1:

@{
    Severity = @('Error', 'Warning')
    ExcludeRules = @(
        'PSAvoidUsingWriteHost'  # If you need Write-Host
    )
    Rules = @{
        PSUseConsistentIndentation = @{
            Enable = $true
            IndentationSize = 4
        }
        PSPlaceCloseBrace = @{
            Enable = $true
            NewLineAfter = $false
        }
    }
}

Testing with Pester

Pester is PowerShell's testing framework.

Installation

Install-Module -Name Pester -Force -Scope CurrentUser

Basic Test

# Save as: Get-ServerInfo.Tests.ps1

BeforeAll {
    . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
}

Describe "Get-ServerInfo" {
    Context "When server is reachable" {
        It "Should return server information" {
            $result = Get-ServerInfo -ComputerName "localhost"
            $result | Should -Not -BeNullOrEmpty
            $result.ComputerName | Should -Be $env:COMPUTERNAME
        }
    }
    
    Context "When server is unreachable" {
        It "Should throw an error" {
            { Get-ServerInfo -ComputerName "invalid-server-xyz" } | 
                Should -Throw
        }
    }
    
    Context "Parameter validation" {
        It "Should require ComputerName parameter" {
            { Get-ServerInfo } | Should -Throw
        }
    }
}

Running Tests

# Run all tests in file
Invoke-Pester -Path .\Get-ServerInfo.Tests.ps1

# Run all tests in directory
Invoke-Pester -Path C:\Scripts\Tests

# With code coverage
Invoke-Pester -Path .\Tests -CodeCoverage .\Functions\*.ps1

Secrets Management

Never hardcode credentials or secrets!

Using Environment Variables

# Set environment variable (user scope)
[Environment]::SetEnvironmentVariable("API_KEY", "your-key", "User")

# Use in script
$apiKey = $env:API_KEY

if (-not $apiKey) {
    throw "API_KEY environment variable not set"
}

Using Azure Key Vault

# Store secret in Key Vault
$secretValue = ConvertTo-SecureString "my-secret" -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName "my-vault" -Name "DatabasePassword" -SecretValue $secretValue

# Retrieve secret in script
$secret = Get-AzKeyVaultSecret -VaultName "my-vault" -Name "DatabasePassword" -AsPlainText

# Use the secret
$credential = New-Object System.Management.Automation.PSCredential("username", (ConvertTo-SecureString $secret -AsPlainText -Force))

Using Secret Management Module

# Install module
Install-Module -Name Microsoft.PowerShell.SecretManagement
Install-Module -Name Microsoft.PowerShell.SecretStore

# Register vault
Register-SecretVault -Name "LocalVault" -ModuleName Microsoft.PowerShell.SecretStore

# Store secret
Set-Secret -Name "APIKey" -Secret "your-api-key"

# Retrieve secret
$apiKey = Get-Secret -Name "APIKey" -AsPlainText

CI/CD Integration

GitHub Actions Example

# .github/workflows/powershell-ci.yml
name: PowerShell CI

on: [push, pull_request]

jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install Pester
        shell: powershell
        run: Install-Module -Name Pester -Force -Scope CurrentUser
      
      - name: Run Tests
        shell: powershell
        run: Invoke-Pester -Path ./Tests -OutputFormat NUnitXml -OutputFile ./TestResults.xml
      
      - name: Publish Test Results
        uses: EnricoMi/publish-unit-test-result-action@v1
        if: always()
        with:
          files: TestResults.xml
      
      - name: Run PSScriptAnalyzer
        shell: powershell
        run: |
          Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
          Invoke-ScriptAnalyzer -Path ./Scripts -Recurse -ReportSummary

Azure DevOps Example

# azure-pipelines.yml
trigger:
  - main

pool:
  vmImage: 'windows-latest'

steps:
- task: PowerShell@2
  displayName: 'Install Pester'
  inputs:
    targetType: 'inline'
    script: 'Install-Module -Name Pester -Force -Scope CurrentUser'

- task: PowerShell@2
  displayName: 'Run Tests'
  inputs:
    targetType: 'inline'
    script: 'Invoke-Pester -Path ./Tests -OutputFormat NUnitXml -OutputFile $(Build.ArtifactStagingDirectory)/TestResults.xml'

- task: PublishTestResults@2
  displayName: 'Publish Test Results'
  inputs:
    testResultsFormat: 'NUnit'
    testResultsFiles: '$(Build.ArtifactStagingDirectory)/TestResults.xml'

Performance Optimization

Measure Performance

# Measure script execution time
Measure-Command {
    # Your code here
}

# Measure specific operation
$start = Get-Date
# Operation
$duration = (Get-Date) - $start
Write-Host "Operation took: $($duration.TotalSeconds) seconds"

Optimization Tips

# Use ArrayList instead of array for large collections (faster append)
$arrayList = New-Object System.Collections.ArrayList
$null = $arrayList.Add("item")  # Suppress output

# Filter early
Get-ChildItem -Filter "*.txt" | Where-Object {$_.Length -gt 1MB}  # Good
Get-ChildItem | Where-Object {$_.Name -like "*.txt" -and $_.Length -gt 1MB}  # Slower

# Use foreach instead of ForEach-Object for large collections
$collection = 1..10000
# Faster
foreach ($item in $collection) { $item * 2 }
# Slower
$collection | ForEach-Object { $_ * 2 }

# Disable progress bar for speed
$ProgressPreference = "SilentlyContinue"

# Use -NoEnumeration to avoid pipeline overhead
Write-Output -NoEnumerate $largeArray

Documentation

Comment Your Code

# Good comments explain WHY, not WHAT
# Bad: Get the server name
$server = $config.server

# Good: Use specific server for compliance requirements
$server = $config.server

# Complex logic deserves explanation
# Process servers in batches to avoid overwhelming the API (rate limit: 10 req/min)
for ($i = 0; $i -lt $servers.Count; $i += 10) {
    # Batch processing code
}

README.md for Script Repositories

# Project Name

## Description
What this script/module does and why it exists.

## Prerequisites
- PowerShell 7.0 or higher
- Az.Compute module version 4.0+
- Azure subscription with contributor access

## Installation
```powershell
Install-Module -Name MyModule

Usage

.\Deploy-Environment.ps1 -Environment "Production"

Configuration

Location and format of configuration files.

Troubleshooting

Common issues and solutions.

Contributing

How to contribute to the project.

License

MIT License

## Key Takeaways

- **Use templates** for consistent script structure
- **PSScriptAnalyzer** catches issues before production
- **Pester tests** ensure code works as expected
- **Never hardcode secrets** - use secure storage
- **CI/CD integration** automates testing
- **Document everything** - future you will thank you
- **Performance matters** for production workloads

## Production Checklist

Before deploying scripts to production:

- [ ] Code follows naming conventions
- [ ] PSScriptAnalyzer shows no errors
- [ ] Pester tests pass with >80% coverage
- [ ] No hardcoded credentials or secrets
- [ ] Error handling for all failure scenarios
- [ ] Comprehensive logging
- [ ] Comment-based help documentation
- [ ] README.md with usage examples
- [ ] Tested with production-sized data
- [ ] Rollback plan documented
- [ ] Code reviewed by team member
- [ ] CI/CD pipeline configured

## What You've Learned

✅ Production-ready script templates  
✅ Code organization and naming conventions  
✅ Static analysis with PSScriptAnalyzer  
✅ Testing with Pester  
✅ Secure secrets management  
✅ CI/CD integration patterns  
✅ Performance optimization techniques  
✅ Documentation best practices  

## Your PowerShell Journey

Congratulations! You've completed PowerShell 101. You've learned:

1. **Fundamentals**: PowerShell basics, cmdlets, pipeline
2. **Data Handling**: Objects, variables, files
3. **Scripting**: Scripts, control flow, error handling, functions
4. **Advanced**: Remoting, APIs, Azure, production practices

You're now equipped to:
- Automate repetitive tasks
- Manage infrastructure at scale
- Integrate with APIs and cloud services
- Write production-ready automation

## Continue Learning

- **Practice**: Automate real tasks you face daily
- **Contribute**: Share your scripts with the community
- **Explore**: PowerShell Gallery has thousands of modules
- **Stay Updated**: Follow PowerShell team blog and GitHub

## Resources

- [PowerShell Documentation](https://docs.microsoft.com/powershell/)
- [PowerShell Gallery](https://www.powershellgallery.com/)
- [PowerShell GitHub](https://github.com/PowerShell/PowerShell)
- [r/PowerShell Community](https://reddit.com/r/PowerShell)

---

**You've completed PowerShell 101!** 🎉

Keep automating, keep learning, and remember: every expert was once a beginner who didn't give up.