TL;DR

PSScriptAnalyzer’s PSPossibleIncorrectComparisonWithNull rule is right for most code. When the left side of -ne is an array, PowerShell filters the array instead of returning true or false. These two tests ask different questions:

# Does $items hold at least one item that is not null?
if ($items -ne $null) { 'has items' }

# Is the variable itself something other than null?
if ($null -ne $items) { 'not null' }

An empty array fails the first test and passes the second. If the code you are cleaning up relies on the first, state that meaning in a form the analyzer accepts. It differs in one case: when the filter leaves exactly one item and that item is falsy, such as 0, '', $false or an empty array. That case is covered below:

function Test-HasItem {
    param($Value)
    @($Value | Where-Object { $null -ne $_ }).Count -gt 0
}

if (Test-HasItem $items) { 'has items' }

I ran into this cleaning up old PowerShell that someone else wrote. The plan was mechanical: run PSScriptAnalyzer and take its suggestions one at a time. One of them came from the rule PSPossibleIncorrectComparisonWithNull:

$null should be on the left side of equality comparisons.

I flipped the comparisons, and the warning went away. So did part of what the function did. The original author had written $array -ne $null on purpose, and the function depended on the behavior that the rule exists to warn about.

That’s why I wanted to write it up. Nothing here is a PowerShell bug, and the rule gives good advice for most code. This code was the exception: the author meant what they wrote, and fixing it broke it.

Reproduce the difference

In Windows PowerShell 5.1 or PowerShell 7, run:

PS> $values = @()
PS> if ($values -ne $null) { 'has values' } else { 'nothing to add' }

nothing to add

PS> if ($null -ne $values) { 'has values' } else { 'nothing to add' }

has values

The same variable, compared with the same operator, gives opposite answers.

Why the two comparisons disagree

An equality or matching operator with a collection on its left filters the collection. It returns every item for which the comparison is true, as an array. about_Comparison_Operators (opens in a new tab) documents this for every equality and matching operator.

So @() -ne $null returns an empty array, and if converts an empty array to $false. $null -ne @() has a scalar on the left, so it compares once and returns $true, because an empty array isn’t $null.

That’s why the analyzer asks for $null on the left: most code that writes $x -ne $null means “is $x null?”, and gets a filter instead when $x happens to be an array. The rule’s own documentation (opens in a new tab) says the same. The rule is correct about that code. It can’t tell that somebody’s code wanted the filter.

The filter has a second property, which matters later. if treats an array that holds exactly one item as that item. @(0) -ne $null returns @(0), and if (@(0)) is $false because 0 is.

What the original code meant

The function built combinations. Each call took the rows built so far and a set of values, and appended every value to every row. The two comparisons that the analyzer flagged are highlighted:

function Add-ToAll {
    param(
        [Parameter(Mandatory)] $currentResult,
        [Parameter(Mandatory)] $valuesToAdd
    )

    $returnValue = @()
    if ($valuesToAdd -ne $null) {
        foreach ($value in $valuesToAdd) {
            if ($currentResult -ne $null) {
                foreach ($result in $currentResult) {
                    $newResult = @($result)
                    $newResult += ,$value
                    $returnValue += ,$newResult
                }
            }
            else {
                $returnValue += ,@(,$value)
            }
        }
    }
    else {
        $returnValue = $currentResult
    }
    return ,$returnValue
}

Both comparisons use the filter on purpose:

• $valuesToAdd -ne $null is false for an empty array, so there’s nothing to add and the rows come back unchanged.
• $currentResult -ne $null is false for an empty array, so there are no rows yet and each value starts one.

The first call passes @() as $currentResult to start the chain. With the operands flipped, $null -ne @() is true, the inner loop runs over nothing, and the first call returns an empty array. Every later call appends to no rows and also returns nothing.

Each version, run on the same inputs, with its result as JSON:

Two rows still agree: both inputs empty, and the ordinary case, a real value added to rows that exist. A test suite built from typical inputs passes, and the change surfaces in production, on the first empty input.

Pin the current behavior in a Pester test

The analyzer’s fix looked safe because nothing checked what the function returned. Before you change inherited code, write a characterization test: run the current code on chosen inputs and assert what it returns now, whether or not that looks right. A refactor then has to keep every answer or change one on purpose.

This test for Pester 5, the PowerShell test framework, turns the earlier table into cases. Save the function as Add-ToAll.ps1 in the same folder:

BeforeAll {
    . $PSScriptRoot/Add-ToAll.ps1
}

Describe 'Add-ToAll' {
    It '<Name>' -TestCases @(
        @{ Name = 'both empty'; Json = '[]'
           Rows = @(); Values = @() }
        @{ Name = 'start from empty'; Json = '[["A"],["B"]]'
           Rows = @(); Values = @('A', 'B') }
        @{ Name = 'nothing to add'; Json = '[["X"],["Y"]]'
           Rows = @(@('X'), @('Y')); Values = @() }
        @{ Name = 'add null'; Json = '[["X"],["Y"]]'
           Rows = @(@('X'), @('Y')); Values = @($null) }
        @{ Name = 'one value'; Json = '[["X","A"]]'
           Rows = @(,@('X')); Values = 'A' }
        @{ Name = 'a single zero'; Json = '[["X"],["Y"]]'
           Rows = @(@('X'), @('Y')); Values = @(0) }
    ) {
        $result = Add-ToAll -currentResult $Rows -valuesToAdd $Values
        ConvertTo-Json -InputObject $result -Compress | Should -Be $Json
    }
}

The cases that matter are the ones the old comparison treated specially: an empty array, an array of nulls and a single falsy value. They are where a flipped comparison changes the result, and they are the inputs a typical test suite leaves out.

Run Invoke-Pester ./Add-ToAll.Tests.ps1 before you touch the function. Every case passes, because each expected value was copied from the original’s output. Flip the two comparisons and four cases fail: start from empty, nothing to add, add null and a single zero.

Each case compares JSON text instead of the array itself. Pass the result to ConvertTo-Json with -InputObject, not through the pipeline:

PS> @(,@('X','A')) | ConvertTo-Json -Compress

["X","A"]

PS> @('X','A') | ConvertTo-Json -Compress

["X","A"]

PS> ConvertTo-Json -InputObject @(,@('X','A')) -Compress

[["X","A"]]

PS> ConvertTo-Json -InputObject @('X','A') -Compress

["X","A"]

That output is PowerShell 7. Windows PowerShell 5.1 prints the first line as {"value":["X","A"],"Count":2}, which is one more reason to use -InputObject.

The pipeline sends the items of an array, not the array, and that loses information in two ways:

• A result with one row loses a level of nesting. One row, [["X","A"]], and a flat row, ["X","A"], serialize to the same text, so a refactor that returned the wrong shape would pass.
• An empty result sends nothing, so ConvertTo-Json writes nothing. With -InputObject, the same result is written as [].

When you write the cases, two inputs look different and are not:

• @(@()) is an empty array, not an array that holds one empty array. The array subexpression operator does not nest. Write ,@() for the nested one.
• @(@('X')) is @('X'), for the same reason. Write @(,@('X')).

Make the intent explicit

Replace each filtering comparison with a test that says what it checks. Keep the function’s structure and change only the two conditions:

# True when $Value holds at least one item that is not null. An empty array
# and an array of nulls hold none, which is what `$Value -ne $null` tested.
function Test-HasItem {
    param($Value)
    @($Value | Where-Object { $null -ne $_ }).Count -gt 0
}

if (Test-HasItem $valuesToAdd) {
    foreach ($value in $valuesToAdd) {
        if (Test-HasItem $currentResult) {

PSScriptAnalyzer reports nothing for this version. Run the test again and one case fails: a single zero. Given @(0), the explicit version returns [["X",0],["Y",0]], and the original returned the rows unchanged.

The original treated @(0) as nothing to add, because an array with one item converts to that item and 0 is false. The same is true of @(''), @($false) and @(,@()), an array holding one empty array, and of any input the filter reduces to one such item, such as @($null, 0). That is the one-item rule from earlier, not a decision anyone made, and the explicit version drops it. If your data can contain a single zero, empty string, $false or empty array, decide which behavior is correct. Change that case’s expected value only if the new behavior is the one you want.

Common failures

The warning is on -eq, not -ne. The same filter applies. @($null, $null) -eq $null returns two nulls, and an array with two items is true in an if, even though both items are null.

The left side is never an array. Then flipping the comparison changes nothing, and it guards against the day it becomes one. Check where the value comes from: a cmdlet that returns one object returns it bare, and one that returns several returns an array.

You want to keep the old line and silence the rule. Suppress it on that function with a reason, so the next person reads why:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
    'PSPossibleIncorrectComparisonWithNull', '',
    Justification = 'Empty array means nothing to add.')]

The attribute goes above the function’s param() block. The explicit test is still the better fix, because the reason then lives in the code rather than in a comment about it.

TL;DR

Add a validation attribute to each parameter: ValidateSet for a fixed list, ValidatePattern for a format, ValidateRange for a number and ValidateScript for anything else. PowerShell checks every value a caller passes before the script’s first line runs, and stops with an error naming the parameter. It never checks a default, so keep each default inside its own rule:

#Requires -Version 7
param(
    [Parameter(Mandatory)]
    [ValidateSet('dev', 'staging', 'prod', IgnoreCase = $false)]
    [string]$Environment,

    [Parameter(Mandatory)]
    [ValidatePattern('^app-[a-z0-9-]+\z', Options = 'None',
        ErrorMessage = '{0} is not a service name. Use app- and lowercase letters, digits or hyphens.')]
    [string]$ServiceName,

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

    [Parameter(Mandatory)]
    [ValidateScript({ Test-Path -Path $_ -PathType Container },
        ErrorMessage = 'Folder {0} does not exist.')]
    [string]$LogRoot
)

ValidateSet and ValidatePattern ignore case by default, so Prod passes a set of prod. IgnoreCase = $false and Options = 'None' make them exact. Windows PowerShell 5.1 can’t parse this param block, because ErrorMessage exists from PowerShell 6 on; drop that argument to run it there.

A script that deletes, deploys or overwrites is only as safe as the values it’s given. A -DaysToKeep of 0 on a log cleanup removes every log; an environment typed Prod instead of prod can slip past a later if ($Environment -ceq 'prod') and take the wrong branch. Validation attributes move those checks to the parameter itself, where PowerShell enforces them on every value passed in, before anything runs, and reports which parameter was wrong.

The example is a log cleanup script, Remove-OldLog.ps1, with four parameters. Each section adds the rule for one of them.

Make the required parameters mandatory

[Parameter(Mandatory)] makes PowerShell refuse to run without a value. Run interactively, it prompts for the missing value; run with -NonInteractive, it stops with an error instead. It also rejects an empty string, so -ServiceName '' fails before any other rule sees it.

[Parameter(Mandatory)]
[string]$ServiceName

Limit a value to a list with ValidateSet

ValidateSet accepts only the values it names, and tab completion offers them. It compares without case unless IgnoreCase is $false; with the default, Prod passes and reaches the script with its capital P.

[ValidateSet('dev', 'staging', 'prod', IgnoreCase = $false)]
[string]$Environment

Check a format with ValidatePattern

ValidatePattern matches the value against a regular expression. Like ValidateSet, it ignores case by default; Options = 'None' turns that off. Its default error message repeats the regular expression back at the reader, so give it an ErrorMessage that says what a valid value looks like. {0} is the value that failed.

[ValidatePattern('^app-[a-z0-9-]+\z', Options = 'None',
    ErrorMessage = '{0} is not a service name. Use app- and lowercase letters, digits or hyphens.')]
[string]$ServiceName

Anchor the pattern with ^ and \z. Without anchors, app-api; Remove-Item passes because it contains a match. Use \z rather than $: in .NET, $ also matches before a trailing newline, so app-api followed by a newline passes ^app-[a-z0-9-]+$ and reaches the script with the newline still in it.

Bound a number with ValidateRange

ValidateRange sets an inclusive minimum and maximum. For a cleanup script, the minimum is the safety rule: a 0 here would delete every log up to now.

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

Check anything else with ValidateScript

ValidateScript runs a script block with the value in $_ and accepts it when the block’s result is truthy. A result of 0, an empty string, $null or no output fails it as surely as $false, so end the block on a test that returns $true. Use it for checks no other attribute makes, such as whether a folder exists.

[ValidateScript({ Test-Path -Path $_ -PathType Container },
    ErrorMessage = 'Folder {0} does not exist.')]
[string]$LogRoot

Expected result

Valid input runs the script. Anything else stops it before the first line, with the parameter named:

PS> ./Remove-OldLog.ps1 -Environment prod -ServiceName app-api -DaysToKeep 0 -LogRoot ./logs

Remove-OldLog.ps1: Cannot validate argument on parameter 'DaysToKeep'. The 0 argument is less than the minimum allowed range of 1. Supply an argument that is greater than or equal to 1 and then try the command again.

The error is terminating, so a caller’s try/catch sees it, and nothing in the script body has run.

Common failures

ValidateSet and ValidatePattern ignore case by default

ValidateSet and ValidatePattern compare without case unless told otherwise, and the value reaches the script exactly as typed. Add IgnoreCase = $false to ValidateSet and Options = 'None' to ValidatePattern. With them, the mistyped value stops at the boundary:

Remove-OldLog.ps1: Cannot validate argument on parameter 'Environment'. The argument "Prod" does not belong to the set "dev,staging,prod" specified by the ValidateSet attribute. Supply an argument that is in the set and then try the command again.

Default values are never validated

PowerShell validates the values a caller passes, never the default. A [ValidateRange(1, 365)] parameter with a default of 0 runs with 0. Check each default against its own rule when you write it.

Invalid assignment inside the script doesn’t stop it

The attribute stays on the variable, so a later assignment is checked too. A failed check on an assignment ends only that statement: PowerShell prints the error, keeps the old value and runs the next line.

MetadataError: <folder>/Remove-OldLog.ps1:7
Line |
   7 |  $DaysToKeep = 0
     |  ~~~~~~~~~~~~~~~
     | The variable cannot be validated because the value 0 is not a valid
     | value for the DaysToKeep variable.

Treat that message as a bug in the script. try/catch catches it, and $ErrorActionPreference = 'Stop' at the top makes it end the run.

ValidatePattern’s default error shows the regular expression

Without an ErrorMessage, a failed pattern reports the pattern itself:

Remove-OldLog.ps1: Cannot validate argument on parameter 'ServiceName'. The argument "API" does not match the "^app-[a-z0-9-]+\z" pattern. Supply an argument that matches "^app-[a-z0-9-]+\z" and try the command again.

Add ErrorMessage to ValidatePattern and ValidateScript, as in the earlier steps. It exists from PowerShell 6 on, so Windows PowerShell 5.1 can’t run a param block that uses it; the #Requires -Version 7 line at the top of the script states that requirement before anything else. I tested only PowerShell 7.6.6. about_Functions_Advanced_Parameters on Microsoft Learn (opens in a new tab) lists every validation attribute.

Scheduled run stops on a missing value

A mandatory parameter prompts when someone is at the console. Started with -NonInteractive, the script stops instead:

Remove-OldLog.ps1: Cannot process command because of one or more missing mandatory parameters: LogRoot.

Start the task with pwsh -NonInteractive -File and pass every mandatory parameter on its command line.

Here is a line it exists to fix. It opens an incident on a status page through a REST API, with the token and the JSON body already in variables:

Invoke-RestMethod -Uri 'https://status.example.com/api/incidents' -Method Post -Headers @{Authorization="Bearer $token";Accept='application/json'} -ContentType 'application/json' -Body $body -TimeoutSec 30

It works. It’s also a line you have to read three times, and not because it’s wrong. It doesn’t scale — not in execution time, in comprehension time. The computer parses it in microseconds. A person parses it in minutes, even the person who wrote it.

Splatting turns that line into a block you can read at a glance, and it’s worth using less as a convenience than as a discipline.

Six months later

A script like this is usually written in one sitting, for a job that needs doing that evening, by someone who knows exactly what every argument is for. Commands run across several lines on backtick continuations, parameters stack one after another, a hashtable sits inline.

Six months later the person reading it doesn’t know, even when it’s the same person.

The failure isn’t correctness. The script still runs. The failure is that a one-line change, a different endpoint, means re-deriving what the whole line does before anyone dares touch it.

A script its own author can’t debug after six months has a problem, and so does every script written the same way.

What makes a line hard to read

Cognitive load is the effort it takes to hold something in your head long enough to understand it. In a command line it comes from a few places at once.

Syntax you have to parse while reading. Where does the list of extensions end? Is that parenthesis inside the script block or after it?

Get-ChildItem -Path D:\Exports -Include *.csv,*.json -Exclude *-keep.* -Recurse -File | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-14) } | Remove-Item -Force

Density. One line means one chunk. The brain can’t break it into pieces and check them separately.

Missing context. Why D:\Exports? Why fourteen days? What makes a file worth keeping? None of that is in the code; it’s in the head of whoever wrote it, or in a document somewhere else.

Any one of these is manageable. The one-liner stacks all three.

What splatting forces

Splatting takes two steps: put the command’s parameters in a hashtable, then hand the whole table to the command with @ in place of $:

$incident = @{
    Uri         = 'https://status.example.com/api/incidents'
    Method      = 'Post'
    Headers     = @{
        Authorization = "Bearer $token"
        Accept        = 'application/json'
    }
    ContentType = 'application/json'
    Body        = $body
    TimeoutSec  = 30
}

Invoke-RestMethod @incident

Same call. More lines. Far less to hold in your head, for four reasons.

Every parameter is named and on its own line. Nothing is positional; nothing depends on order.

The structure is visible. The headers are a nested block, not a run of braces in the middle of a line. You can see that the call posts JSON, with a bearer token, to one endpoint.

Changing it is safe. Adding a header is adding a line. Deleting a parameter is deleting a line. There’s no adjacent argument to break.

Comments fit.

$incident = @{
    Uri         = 'https://status.example.com/api/incidents'
    Method      = 'Post'
    Headers     = @{
        # Read the token from the vault, never from the script.
        Authorization = "Bearer $token"
        Accept        = 'application/json'
    }
    ContentType = 'application/json'
    Body        = $body
    # Fail fast; the caller retries.
    TimeoutSec  = 30
}

None of this is for the computer. It’s for the person reading the script later — probably you, and if not you, someone who can’t ask you.

People first, computers second

There’s an old Unix principle: write programs for people first, computers second. Not because the computer doesn’t matter, but because the human is the slow part. The machine executes the dense one-liner in the same time as the splatted block. The human pays for the density every single time they read it.

Splatting is a forcing function for that principle. To splat, you have to name every parameter, arrange them in a structure, and decide what you’re passing. You can’t throw arguments at a cmdlet and hope.

Rules that are not obvious

Splatting is simple until it isn’t. These are the parts that trip people up.

It’s @params at the call and $params everywhere else. The hashtable is a normal variable; only the call site uses @. Writing Invoke-RestMethod $incident passes the whole table as the first positional argument, and the error message will be about a type conversion, not about splatting.

Switch parameters take a boolean. Recurse = $true, not Recurse = 'yes' and not a bare Recurse. A hashtable value has to be a value.

You can mix splatted and explicit parameters. This is the pattern for a common base with a per-call difference:

$common = @{
    Headers    = @{ Authorization = "Bearer $token" }
    TimeoutSec = 30
}

Invoke-RestMethod @common -Uri "$api/components"
Invoke-RestMethod @common -Uri "$api/incidents"

PowerShell merges them. Naming the same parameter in both places is an error, which is what you want — a silent override would be worse.

You can build the table conditionally. A one-liner can’t express “add this parameter only if the variable is set”; a hashtable can:

$copy = @{
    Path        = $source
    Destination = $target
    Recurse     = $true
}
if ($DryRun) {
    $copy['WhatIf'] = $true
}

Copy-Item @copy

A function can pass its own parameters straight through. Inside a function, $PSBoundParameters is a hashtable of the parameters the caller supplied, and it splats:

function Get-RecentLog {
    param ([string]$Path, [switch]$Recurse)
    Get-ChildItem @PSBoundParameters -Filter *.log -File |
        Sort-Object LastWriteTime -Descending |
        Select-Object -First 10
}

Whatever the caller passed goes through unchanged, and whatever they didn’t pass isn’t mentioned at all. It’s the cleanest way to write a wrapper, and it only exists because splatting does.

Arrays splat positionally. @('a', 'b') splatted fills parameters by position, not by name. It’s legal and almost never what you want in a script you intend to read later.

Bigger commands, bigger differences

The gap between the two forms grows with the command. Here is the incident call once it runs from a server. It goes through a proxy, sends a user agent the status page can identify, and retries when the status page answers with an error.

Invoke-RestMethod -Uri 'https://status.example.com/api/incidents' -Method Post -Headers @{Authorization="Bearer $token";Accept='application/json';'X-Request-Id'=$requestId} -ContentType 'application/json' -Body $body -TimeoutSec 30 -UserAgent 'deploy-bot/2.1' -Proxy 'http://proxy.corp.example:8080' -ProxyUseDefaultCredentials -MaximumRetryCount 3 -RetryIntervalSec 5

One command, eleven parameters, one of them a table. Now the same call, splatted:

$incident = @{
    Uri                        = 'https://status.example.com/api/incidents'
    Method                     = 'Post'
    Headers                    = @{
        Authorization  = "Bearer $token"
        Accept         = 'application/json'
        'X-Request-Id' = $requestId
    }
    ContentType                = 'application/json'
    Body                       = $body
    TimeoutSec                 = 30
    UserAgent                  = 'deploy-bot/2.1'
    Proxy                      = 'http://proxy.corp.example:8080'
    ProxyUseDefaultCredentials = $true
    MaximumRetryCount          = 3
    RetryIntervalSec           = 5
}

Invoke-RestMethod @incident

Longer, and easier to understand, modify and debug. When the proxy changes, the proxy is one line you can find. MaximumRetryCount and RetryIntervalSec need PowerShell 7. To run the same call on Windows PowerShell 5.1, you delete those two lines; nothing around them changes.

When not to splat

Splatting is a tool for commands that are hard to read. Applying it to commands that aren’t adds lines and nothing else.

One or two parameters. Get-Content 'settings.json' doesn’t improve with a hashtable.

Interactive use. At the prompt you’re the only reader, and you’re reading it right now.

Idioms everyone knows. Get-ChildItem | Where-Object Name -like '*.log' is a pattern PowerShell users recognize on sight; splatting it hides the idiom.

The rule I use: splat when future-you would have to re-read the line to understand it. For most scripts that turns out to be most of the non-trivial calls, and almost none of the trivial ones.

Documentation you no longer need

A splatted call documents itself in two places. The variable name says what the call is for; the table says how:

$openIncident = @{
    Uri         = 'https://status.example.com/api/incidents'
    Method      = 'Post'
    Headers     = @{
        Authorization = "Bearer $token"
        Accept        = 'application/json'
    }
    ContentType = 'application/json'
    Body        = $body
    TimeoutSec  = 30
}

Invoke-RestMethod @openIncident

The one-liner needed a comment above it to say what it did. This doesn’t. Comments still earn their place for why — why this endpoint, why this timeout — but what is now in the code, where it can’t drift from the code.

Readability compounds

Every future change to a script starts with reading it. A bug fix, a new parameter, an upgrade to a newer module: read first, then edit. The cost of an unreadable line is paid on every one of those visits, for as long as the script is in use. The scripts that matter stay in use for years.

Splatting is a small feature. What it represents is larger: optimize for the person who will maintain the code, not the machine that will run it. The machine is fast and doesn’t care whether the call is one line or twenty. The person is slow and cares whether they can understand it without an afternoon of archaeology.

Splatting is how a script written in one evening stays usable for the next several years.

References

• about_Splatting (opens in a new tab) — the PowerShell documentation, including $PSBoundParameters and positional splatting
• Basics of the Unix Philosophy (opens in a new tab) — Eric Raymond on writing for people first