PowerShell Parameter Validation: Scripts That Fail Safely

A script that fails loudly on bad input is a minor inconvenience. A script that accepts bad input and does something plausible-looking with it is a genuine problem. Particularly if it’s deleting things, or reporting numbers someone will act on.

PowerShell has a validation system that catches most of this before your code runs at all. It’s declarative, it’s built into param(), and it’s underused.

The attributes worth knowing

What it looks like in practice

[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string[]]$ComputerName,

    [ValidateRange(1,365)]
    [int]$DaysOld = 30,

    [ValidateSet('Log','Tmp','Both')]
    [string]$FileType = 'Log',

    [ValidateScript({
        if (Test-Path $_) { $true }
        else { throw "Path not found: $_" }
    })]
    [string]$LogPath = 'C:\Logs'
)

Every one of those failures now happens before a single line of your logic executes, with a clear message naming the offending parameter.

Write real messages in ValidateScript

The default failure message from ValidateScript is close to useless. It just echoes the failing expression. Throwing your own message is worth the extra line:

# Unhelpful
[ValidateScript({ Test-Path $_ })]

# Helpful
[ValidateScript({
    if (-not (Test-Path $_)) { throw "LogPath '$_' does not exist or is not accessible." }
    $true
})]

Mandatory is not always what you want

[Parameter(Mandatory)] prompts the user when the value is missing. Interactively that’s helpful. In a scheduled task it means the script sits there forever, waiting for input that will never come, and it looks like a hang rather than an error.

For anything unattended, prefer a sensible default, or validate explicitly and exit with a clear message:

if (-not $ComputerName) {
    Write-Error 'ComputerName is required when running unattended.'
    exit 1
}

Getting -WhatIf for free

Add SupportsShouldProcess to [CmdletBinding()] and wrap destructive operations in $PSCmdlet.ShouldProcess(). You get -WhatIf and -Confirm with no further work:

[CmdletBinding(SupportsShouldProcess)]
param([string]$Path)

foreach ($file in Get-ChildItem $Path) {
    if ($PSCmdlet.ShouldProcess($file.FullName, 'Delete')) {
        Remove-Item $file.FullName
    }
}

Run it with -WhatIf and it lists exactly what it would delete without touching anything. On any script that removes, stops or overwrites, this should be non-negotiable.

A rule of thumb

• Validate at the edge. Everything entering the script gets checked once, at the parameter block.
• Don’t re-validate inside. If the parameter block did its job, trust the value.
• Prefer declarative attributes over if checks. They self-document and appear in Get-Help.
• Fail early and specifically. “ThresholdPercent must be 1-100” beats “an error occurred”.

Glossary

Frequently asked questions

Does validation slow my script down?

Not measurably. Attributes are evaluated once as parameters bind. ValidateScript runs your code, so keep it light. Checking a path is fine, querying Active Directory is not.

Can I validate one parameter against another?

Not with attributes, which see parameters individually. Cross-parameter rules go in a begin block, or use parameter sets to make invalid combinations impossible to express.

Why does my scheduled script hang instead of failing?

Almost certainly a Mandatory parameter prompting for input nobody is there to give. Use defaults or explicit checks for anything unattended.

What’s the difference between ValidateSet and an enum?

ValidateSet is simpler and gives tab completion immediately. A custom enum is worth it when the same set is reused across many scripts.

Should every script support -WhatIf?

Every script that changes something, yes. Read-only reporting scripts don’t need it, and adding it there is just noise.

Disclosure: this post may contain affiliate links. If you buy through one of them, we may earn a small commission at no extra cost to you. We only recommend products we’ve tested or genuinely rate.