powershell-expert

PowerShell Expert

Develop production-quality PowerShell scripts, tools, and GUIs using Microsoft best practices and the PowerShell ecosystem.

Quick Reference

Script Structure

#Requires -Version 5.1

<#
.SYNOPSIS
    Brief description.
.DESCRIPTION
    Detailed description.
.PARAMETER Name
    Parameter description.
.EXAMPLE
    Example-Usage -Name 'Value'
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [ValidateNotNullOrEmpty()]
    [string[]]$Name,

    [switch]$Force
)

begin {
    # One-time setup
}

process {
    foreach ($item in $Name) {
        # Per-item processing
    }
}

end {
    # Cleanup
}

Function Template

function Verb-Noun {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$Name,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('CN')]
        [string]$ComputerName = $env:COMPUTERNAME,

        [switch]$PassThru
    )

    process {
        if ($PSCmdlet.ShouldProcess($Name, 'Action')) {
            # Implementation
            if ($PassThru) { Write-Output $result }
        }
    }
}

Workflow

1. Script Development

Follow naming and parameter conventions:

• Verb-Noun format with approved verbs (Get-Verb)
• Strong typing with validation attributes
• Pipeline support via ValueFromPipeline
• -WhatIf/-Confirm for destructive operations

See best-practices.md for complete guidelines.

2. GUI Development

Windows Forms for simple dialogs, WPF/XAML for complex interfaces:

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

$form = New-Object System.Windows.Forms.Form -Property @{
    Text          = 'Title'
    Size          = New-Object System.Drawing.Size(400, 300)
    StartPosition = 'CenterScreen'
}

See gui-development.md for controls, events, and templates.

3. PowerShell Gallery Integration

Search and install modules using PSResourceGet:

# Search gallery
Find-PSResource -Name 'ModuleName' -Repository PSGallery

# Install module
Install-PSResource -Name 'ModuleName' -Scope CurrentUser -TrustRepository

Use scripts/Search-Gallery.ps1 for enhanced search.

See powershellget.md for full cmdlet reference.

Key Patterns

Error Handling

try {
    $result = Get-Content -Path $Path -ErrorAction Stop
}
catch [System.IO.FileNotFoundException] {
    Write-Error "File not found: $Path"
    return
}
catch {
    throw
}

Splatting for Readability

$params = @{
    Path        = $sourcePath
    Destination = $destPath
    Recurse     = $true
    Force       = $true
}
Copy-Item @params

Pipeline Best Practices

# Stream output immediately
foreach ($item in $collection) {
    Process-Item $item | Write-Output
}

# Accept pipeline input
param(
    [Parameter(ValueFromPipeline)]
    [string[]]$InputObject
)
process {
    foreach ($obj in $InputObject) {
        # Process each
    }
}

Module Recommendations

When recommending modules, search the PowerShell Gallery. These are common starting points — always verify via Module Verification before recommending:

Category	Popular Modules
Azure	Az, Az.Compute, Az.Storage
Testing	Pester, PSScriptAnalyzer
Console	PSReadLine, Terminal-Icons
Secrets	Microsoft.PowerShell.SecretManagement
Web	Pode (web server), PoshRSJob (async)
GUI	WPFBot3000, PSGUI

Documentation Lookup

Verify cmdlet syntax and module availability against live sources rather than recalled detail. Every learn.microsoft.com PowerShell page is generated from markdown in a public MicrosoftDocs repository — fetch the markdown, not the rendered page. The source is far smaller, carries no navigation chrome or JavaScript, and preserves syntax blocks and parameter tables verbatim.

Raw Markdown Sources (WebFetch)

Use the WebFetch tool against raw.githubusercontent.com. Construct the URL directly from the templates below — do not search for it first.

Command kind	URL template
Core PowerShell Get-ChildItem, Write-Output, Invoke-Command	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/{Module}/{Cmdlet}.md
Conceptual about_Splatting, about_CommonParameters	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs/main/reference/{version}/Microsoft.PowerShell.Core/About/{about_Topic}.md
Windows-only Get-ADUser, Get-DnsServerZone, Get-MpComputerStatus	https://raw.githubusercontent.com/MicrosoftDocs/windows-powershell-docs/main/docset/winserver2025-ps/{Module}/{Cmdlet}.md
Gallery / packaging Install-PSResource, Find-PSResource	https://raw.githubusercontent.com/MicrosoftDocs/powershell-docs-psget/main/powershell-gallery/powershellget-3.x/Microsoft.PowerShell.PSResourceGet/{Cmdlet}.md
Satellite modules Invoke-ScriptAnalyzer, Get-Secret	https://raw.githubusercontent.com/MicrosoftDocs/PowerShell-Docs-Modules/main/reference/ps-modules/{Module}/{Cmdlet}.md

{version} is one of 5.1, 7.4, 7.5, 7.6, 7.7. Pin it from context — #Requires, pwsh, ISE, or a stated platform. With no signal, fetch both 7.5 and 5.1 and state any parameter difference, since the wrong edition yields syntax that looks authentic but fails on the user's shell.

WebFetch prompt: Extract the complete syntax blocks, the full parameter table with types and defaults, and the examples.

Three rules govern URL construction:

1. Case matters. Raw paths are case-sensitive where learn.microsoft.com is not. .../activedirectory/Get-ADUser.md returns 404; .../ActiveDirectory/Get-ADUser.md returns 200. Preserve the module's own casing.
2. Never point at a folder. Raw serves blobs only — any URL ending in / returns 404. There is no directory-listing endpoint.
3. Convert page URLs. Rewrite github.com/{owner}/{repo}/blob/{branch}/{path} to raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}.

Routing a cmdlet to the right repository, module, and version folder is covered in doc-sources.md, along with complete module inventories and a 404 troubleshooting table. Consult it whenever the correct path is not obvious.

Fallback Chain

Escalate only on failure, one step at a time:

Step	Tool	Use when
1	WebFetch raw markdown	Default — always attempt first
2	WebFetch contents API https://api.github.com/repos/{owner}/{repo}/contents/{path}	A folder name is unknown. Returns plain JSON that parses cleanly; 60 requests/hour unauthenticated
3	WebFetch learn.microsoft.com	No raw source exists (third-party modules, Learn-only articles)
4	WebSearch	Path cannot be derived. Query: {Cmdlet-Name} site:learn.microsoft.com/en-us/powershell — then convert the result back to a raw URL and return to step 1
5	Local execution	Tools unavailable. Ask the user to run Get-Help {Cmdlet} -Full or Get-Command {Cmdlet} -Syntax

If every step fails, state the uncertainty explicitly rather than guessing:

"I wasn't able to verify this against live documentation. Please confirm by running: Get-Command Cmdlet-Name -Syntax"

Module Verification

Gallery packages have no markdown source. WebFetch the listing page directly:

• URL: https://www.powershellgallery.com/packages/{ModuleName}
• Prompt: Extract: module name, latest version, last updated date, total downloads, and whether it shows any deprecation warning or 'unlisted' status

A 404 means the module likely does not exist — confirm with WebSearch for {ModuleName} PowerShell module site:powershellgallery.com. If both tools are unavailable, execute scripts/Search-Gallery.ps1 -Name 'ModuleName'.

Scenario	Requirement
User asks whether module X exists	MUST verify on the Gallery
Recommending a specific module	MUST verify it exists and is not deprecated
Stating a module version requirement	MUST check the Gallery for the current version
Providing exact cmdlet syntax	SHOULD verify against raw markdown
General best practices	Static references suffice

Good (verified against live data):

"ImportExcel (v7.8.10, updated Oct 2024, 17M+ downloads) provides Export-Excel for creating spreadsheets without Excel installed."

Bad (unverified):

"Use the Excel-Tools module to export data." ← may not exist

Rendered Documentation

Browse these manually; prefer the raw sources above when fetching.

Resource	URL
PowerShell documentation	https://learn.microsoft.com/en-us/powershell/
Module browser	https://learn.microsoft.com/en-us/powershell/module/
PowerShell Gallery	https://www.powershellgallery.com

Reference Files

Topic	File
Documentation routing, raw URL maps, 404 troubleshooting	references/doc-sources.md
Naming, parameters, pipeline, error handling, code style	references/best-practices.md
Windows Forms, WPF, controls, events, templates	references/gui-development.md
Find, install, update, publish modules	references/powershellget.md

Included Scripts

Script	Purpose
scripts/Search-Gallery.ps1	Formatted PowerShell Gallery search with legacy Find-Module fallback