Your PowerShell Script Has a .NET Runtime Too

A PowerShell script can parse cleanly, pass review, and still fail before it performs any useful deployment work.

The missing part of the compatibility statement is often the runtime underneath the shell.

A recent CI/CD fix in a shared .NET repository exposed a compact example. A deployment-proof script needed case-aware substring checks, so it called this overload:

$text.Contains(
    $expected,
    [System.StringComparison]::OrdinalIgnoreCase)

In a minimal two-host smoke check, that expression works in modern PowerShell running on current .NET. On Windows PowerShell 5.1, backed by the older .NET Framework, the isolated call fails with a method-resolution error because that overload is not available.

The script's syntax is valid in both places. The API surface is not.

PowerShell is also a .NET API client

PowerShell makes .NET methods feel like part of the language. That convenience can hide an important dependency.

When a script calls an instance method, overload resolution happens against the runtime loaded by the current host. A method introduced in a newer .NET version does not become available merely because the PowerShell syntax parser accepts the expression.

This creates a portability stack:

1. PowerShell language version;
2. underlying .NET runtime and API surface;
3. installed modules;
4. native tools and their versions; and
5. host operating-system behaviour.

“It is a PowerShell script” names only the first layer.

Preserve the semantics, not just the outcome

The fix was to use an older-compatible API while keeping the comparison rule explicit:

$text.IndexOf(
    $expected,
    [System.StringComparison]::OrdinalIgnoreCase) -ge 0

IndexOf returning zero or greater means the value was found. More importantly, the explicit StringComparison preserves the original case and culture semantics.

A tempting rewrite is:

$text -like "*$expected*"

That may be acceptable in some scripts, but it changes the contract. Wildcard metacharacters, default case behaviour, and culture expectations can produce different results. Compatibility work should not quietly change meaning.

When replacing an unavailable API, write down the behaviour being preserved:

• ordinal or culture-aware comparison;
• case-sensitive or case-insensitive matching;
• literal text or wildcard pattern;
• null and empty-value behaviour; and
• success and failure return conventions.

Choose a support strategy deliberately

There are two honest approaches.

Standardise on a modern host. Pin PowerShell 7 and a known .NET runtime in every supported runner. This gives scripts a cleaner API surface and reduces compatibility branches.

Support the oldest required host. If a deployment server still runs Windows PowerShell 5.1, treat that environment as part of the product contract. Use compatible APIs and test there.

Neither choice is free. Upgrading a runner may involve operating-system constraints, security review, module changes, or a carefully staged deployment. Supporting multiple engines increases the test matrix and can make otherwise simple expressions more verbose.

The expensive option is pretending the choice has not been made.

Put the real runtime in the test loop

A source guard can stop a known incompatible pattern from returning. For example, a repository test might require the supported IndexOf form and reject the problematic Contains overload in a critical script.

That is useful, but it is structural evidence. It proves that one text pattern is absent; it does not prove the script runs on the target host.

A stronger CI matrix adds a small runtime smoke test:

$engines = @(
    @{ Name = "legacy"; Command = "powershell.exe" },
    @{ Name = "modern"; Command = "pwsh" }
)

foreach ($engine in $engines) {
    & $engine.Command -NoProfile -File ./verify-script-contract.ps1
    if ($LASTEXITCODE -ne 0) {
        throw "Runtime contract failed for $($engine.Name)"
    }
}

In a real pipeline, run this on actual runner images rather than assuming both commands on one machine represent production. Keep the smoke test narrow: load the script, exercise compatibility-sensitive helpers, and avoid invoking external side effects.

Build a runtime manifest

For deployment automation, a small machine-readable manifest can make assumptions reviewable:

shells:
  - windows-powershell-5.1
  - powershell-7
requiredModules:
  - name: Example.Module
    minimumVersion: 2.4.0
nativeTools:
  - name: dotnet
    version: 10.0.x

The exact format is less important than ownership. Someone must decide when an old engine leaves the support set, who validates runner images, and how a toolchain change is rolled out.

The practical review

When a CI or deployment script changes, ask:

• Which shell executable will run it?
• Which .NET runtime backs that shell?
• Are called method overloads present there?
• Are comparison semantics explicit?
• Are module and native-tool versions pinned or checked?
• Does at least one test execute on the oldest supported runner?

Portability is not a property of syntax alone. It is an agreement between the script and the complete execution environment.

Make that environment explicit, test the oldest supported boundary, and choose compatibility shims only when they preserve the behaviour you intended.