powershell

PowerShell Scripting Skill

Quick Reference

Need	Pattern
Script header	#Requires -Version 7.0 + Set-StrictMode -Version Latest + $ErrorActionPreference = 'Stop'
Pipeline data output	Write-Output (never Write-Host for data the caller may consume)
User-facing status	Write-Host or Write-Information
State-changing function	[CmdletBinding(SupportsShouldProcess)] + $PSCmdlet.ShouldProcess()
Native command errors	$ErrorActionPreference = 'Stop' → throws automatically
Secrets / credentials	SecretManagement + SecretStore or env vars — never hardcode; avoid SecureString
Path construction	Join-Path — never string concatenation
Wildcard-safe paths	-LiteralPath instead of -Path
Platform detection	$IsWindows / $IsLinux / $IsMacOS
Parallel processing	ForEach-Object -Parallel
Null-conditional	?? and ?. operators
Office/Word COM	Avoid by default; for Word tasks prefer nong word .... If COM is explicitly required, read word/references/com-automation.md first
Module import	Import-Module -MinimumVersion X.Y -ErrorAction Stop
Verb-noun naming	Use approved verbs from Get-Verb; run PSScriptAnalyzer UseApprovedVerbs
Comment-based help	Required for public functions/scripts: .SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE

Scope

PowerShell 7+ only. No 5.1 support.

Environment & Execution

• Windows: pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ./script.ps1
• WSL: pwsh.exe ... (same flags), use wslpath -w for path conversion
• Linux / macOS: pwsh (same flags)

-ExecutionPolicy Bypass is acceptable in dev/CI. In production, prefer RemoteSigned or signing. ExecutionPolicy is Windows-only — on Linux/macOS it is effectively Unrestricted.

Script Header

#Requires -Version 7.0
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

Plus comment-based help for every public script/function:

<#
.SYNOPSIS
    Short description.
.DESCRIPTION
    More detailed description.
.PARAMETER Param1
    Explanation of Param1.
.EXAMPLE
    .\script.ps1 -Param1 value
.NOTES
    Author  : Your Name
    Version : 1.0.0
#>

Cmdlet / Function Conventions

function Invoke-Deployment {
    [CmdletBinding(SupportsShouldProcess, ConfirmImpact='High')]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [string]$TargetPath,
        [Parameter()]
        [ValidateSet('dev','staging','prod')]
        [string]$Environment = 'dev',
        [switch]$Force
    )
    process {
        if ($PSCmdlet.ShouldProcess($TargetPath, "Deploy to $Environment")) {
            # actual work
        }
    }
}

• Verb-Noun naming using approved verbs.
• Always add [CmdletBinding()] when the function needs -Verbose/-WhatIf or pipeline input.
• Use [Parameter(Mandatory)] over manual if (-not $Param) checks.
• Add [ValidateSet], [ValidateNotNullOrEmpty], [ValidateRange] where applicable.

Dry-Run (WhatIf)

function Remove-OldFiles {
    [CmdletBinding(SupportsShouldProcess)]
    param([string]$Path)
    Get-ChildItem $Path | ForEach-Object {
        if ($PSCmdlet.ShouldProcess($_.FullName, 'Remove')) {
            Remove-Item $_.FullName -Force
        }
    }
}

Always add SupportsShouldProcess on functions that modify state.

Security Checklist

• No hardcoded credentials, tokens, or connection strings.
• All user input validated via [ValidateSet], [ValidateRange], or explicit guards.
• No Invoke-Expression with untrusted input.
• SupportsShouldProcess on any function that modifies state.
• Secrets from environment variables, SecretManagement vaults, or credential stores — not literals.
• SecureString avoided for new development.
• Scripts pass PSScriptAnalyzer default rules with no warnings.

Behavioral Conventions

• Always save .ps1 files as UTF-8 with BOM. Always specify -Encoding UTF8 for file I/O.
• Run [CmdletBinding()] functions with -WhatIf first to preview changes.
• Prefer -LiteralPath over -Path when paths may contain wildcard characters.
• Keep scripts idempotent — re-running should be safe.
• Include comment-based help for all public functions and scripts.
• Use Get-Verb and PSScriptAnalyzer UseApprovedVerbs to validate verb naming.
• Include Pester tests when publishing modules.

Reference Index

Topic	File	Read when
File encoding (UTF-8, BOM, 中文乱码)	references/file-encoding.md	Chinese/non-ASCII characters appear garbled; setting up encoding defaults
Error handling (try/catch, retry, logging)	references/error-handling.md	Need retry logic, logging patterns, or error propagation rules
Modules & testing (psd1, Pester, PSScriptAnalyzer)	references/modules.md	Building a module, setting up tests, or running PSScriptAnalyzer
Output & pipeline patterns	references/output-pipeline.md	Choosing Write-Output vs Write-Host, building pipelines, parallel processing
Credential & secret handling	references/credentials.md	Handling tokens, API keys, or credentials securely
Path handling & Join-Path	references/path-handling.md	Building cross-platform paths, dealing with wildcard characters