Powershell-Copilot-Standards: Instructions file for GitHub Copilot

PowerShell Community Standards Integration

Integrate established PowerShell community best practices and style guidelines into all code generation and analysis.

Best Practices Implementation

Tool Design Patterns

# Tools (reusable functions) - accept input via parameters, output to pipeline
function Get-ServerInfo {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
        [string[]]$ComputerName
    )

    process {
        foreach ($computer in $ComputerName) {
            # Return raw data for maximum reusability
            [PSCustomObject]@{
                ComputerName = $computer
                Status = Test-Connection $computer -Count 1 -Quiet
                LastBootTime = (Get-CimInstance Win32_OperatingSystem -ComputerName $computer).LastBootUpTime
                # Raw data, no formatting
            }
        }
    }
}

# Controllers (automation scripts) - can format data for specific purpose
$servers = Get-Content servers.txt
$results = $servers | Get-ServerInfo | Where-Object Status -eq $true
$results | Format-Table -AutoSize  # Controller can format for display

Error Handling Patterns

# Use -ErrorAction Stop for trappable exceptions
try {
    $result = Get-Something -Parameter $value -ErrorAction Stop

    # Put entire transaction in try block, not just the risky part
    Process-Result $result
    Update-Database $result
    Send-Notification "Success"

} catch {
    # Copy error immediately to avoid $Error[0] changes
    $currentError = $Error[0]

    Write-Error "Operation failed: $($currentError.Exception.Message)"
    # Include correlation ID for traceability
    throw
}

Performance Patterns

# Prefer language features over cmdlets for performance
# Instead of: Get-Service | Where-Object Status -eq 'Running'
# Use: Get-Service | Where Status -eq Running

# Use StringBuilder for string concatenation
$sb = [System.Text.StringBuilder]::new()
foreach ($item in $collection) {
    [void]$sb.AppendLine("Processing: $item")
}
$result = $sb.ToString()

# Avoid appending to arrays in loops
$results = foreach ($item in $collection) {
    Process-Item $item  # Output to pipeline instead
}