PowerShell Best Practices and Style Guide

The PowerShell Best Practices and Style Guide provides a baseline for code structure, command design, programming, formatting, and style. The goal is to help developers write more reusable and readable code by following patterns that make it harder to encounter common problems (the "Pit of Success").

Note that these are guidelines and practices, not dogmatic rules. They are intended to be pragmatic; if following a guideline prevents you from accomplishing a task, the guideline should be adapted to your needs.

The PowerShell Best Practices guide provides a collection of community-driven recommendations for writing PowerShell scripts. Unlike the Style Guide, which contains strict rules, these Best Practices are guidelines that you should usually follow as a starting point, but are intended to be deviated from when appropriate for your specific context.

Key considerations:

• Not hard rules: They are suggestions, not absolute requirements.
• Perspective: The guidelines are heavily influenced by system administrator practitioners. If you are approaching PowerShell from a pure developer or 'language geek' perspective, you may need to adapt these practices to your specific needs.

Adding [CmdletBinding()] to your function or script makes it behave like a built-in PowerShell cmdlet. This provides several critical features:

• Support for common parameters like -Verbose and -ErrorAction.
• Support for -? to display help.
• Ability to define ParameterSets and a DefaultParameterSetName.
• Support for -WhatIf and -Confirm via SupportsShouldProcess.

Always specify types for parameters to provide user hints and enable early input validation. This helps prevent code injection and ensures failures occur before the command logic executes.

Key Type Guidelines:

• Avoid generic [string] or [object] when using ParameterSets or ValueFromPipeline, as PowerShell may aggressively coerce values into these types, breaking set differentiation.
• Use [pscredential] for credentials. This allows PowerShell to automatically prompt for passwords when a username is provided (e.g., -Credential Jaykul).
• Use [switch] for boolean flags.
  • Do not provide default values for switches (they default to $false).
  • Do not attempt to treat switches as having three states; treat them as boolean.
  • To pass a switch to another command, use the colon syntax: -TargetSwitch:$MySwitch or splatting.

The guide recommends the One True Brace Style variant:

1. Place the opening brace { at the end of the line of the statement.
2. Place the closing brace } at the beginning of a new line.

Exception: You may put small scriptblocks passed to parameters on a single line.

This style ensures that new lines can be inserted between any two lines without accidentally breaking the code structure.

enum Color {
    Black,
    White
}

function Test-Code {
    [CmdletBinding()]
    param (
        [int]$ParameterOne
    )
    end {
        if (10 -gt $ParameterOne) {
            "Greater"
        } else {
            "Lesser"
        }
    }
}

# An Exception case:
Get-ChildItem | Where-Object { $_.Length -gt 10mb }

To prevent broken table layouts or empty rows, avoid mixing different types of objects in the output of a single command.

Best Practices:

• Use the [OutputType()] attribute to indicate the type(s) of output your script or function produces.
• If you must combine objects, ensure they derive from a common base type (e.g., FileInfo and DirectoryInfo both derive from System.IO.FileSystemInfo) or have matching format/type files so they share the same columns.
• Never intersperse strings within your object output.

If you are building a script module, you can provide a middle ground between raw data (tools) and formatted data (controllers) using Views.

By including a .format.ps1xml file in your module manifest, you can define how your objects are displayed in the console. This allows the underlying data to remain raw and unmanipulated for pipeline processing, while providing a convenient default view for interactive users.

There are two scenarios where returning multiple object types is acceptable:

1. Internal Functions: It is acceptable to return multiple types if the function is intended for internal use and the output is being assigned to multiple variables rather than being sent to the host.

   $user, $group, $org = Get-UserGroupOrg

2. Using Out-Default: If an external command must return multiple types, ensure the function name makes it obvious that multiple items are returned. You must call Out-Default separately for each type of object to prevent the formatter from mixing them up.