Scanning Powershell Compatibility

Scanning PowerShell 5.1 → 7 Compatibility

Relationship to PSScriptAnalyzer

PSScriptAnalyzer is the primary detector. This catalog is a deliberately small sidecar for the classes it is structurally unable to see. Do not run this scan as a replacement for PSUseCompatibleCommands / PSUseCompatibleTypes / PSUseCompatibleSyntax; run it alongside them.

What PSScriptAnalyzer does better

It enumerates the entire command and type surface of the target runtime, so it catches every removed cmdlet, every removed parameter, and every removed type — including ones nobody thought to write a rule for. A curated catalog can only ever contain what someone remembered. For removed-API detection, that completeness wins outright, and this catalog should not compete with it.

What PSScriptAnalyzer cannot see, by construction

It infers breakage from absence from an inventory. Anything that still exists in PowerShell 7 but behaves differently is invisible to it, no matter how badly it breaks:

Encoding is typically the largest genuine finding class in the whole scan, and PSScriptAnalyzer reports zero of it.

It also has no symbol table and no interprocedural analysis. It reports a function as unavailable in the very file that defines it a few lines above, and it never follows a dot-source into a library. It also does not resolve abbreviated parameters — -fore for -ForegroundColor is reported as missing. See the upstream rule source, which explicitly defers parameter binding: "Ideally we would go through each command and emulate the parameter binding algorithm … but this is very involved. For now, we'll just check that the parameters exist." Those two classes dominate its false positives; see the triaging-powershell-analyzer-findings skill.

The division of labour

Every Command-kind target in the catalog was probed against PSUseCompatibleCommands with a validated profile to decide which side owns it. The two superseded Parameter-kind rules were probed the same way: PSUseCompatibleCommands reports removed parameters as well as removed commands, so Restart-Computer -Protocol and Get-Service -ComputerName are both caught even though the commands themselves still ship in 7.

The table is exhaustive: every id in PSCompatibilityRules.psd1 appears in exactly one row. If you add a rule, add it here too — a rule missing from the table is indistinguishable from a rule nobody measured.

Superseded rules are knowledge-only: they do not run, and they never emit a finding. Detection for anything in the first two rows is PSScriptAnalyzer's alone; the third row is detected by nobody, on purpose. The rule bodies stay in the catalog because they still do two jobs that have nothing to do with detection:

• Enrichment. Invoke-PSSACompatibilityScan.ps1 joins each PSSA finding against them on Command (and on Command + Parameter for Parameter-kind rules) and stamps back the category, the real severity, the remediation prose and the Skill that performs the rewrite. PSSA supplies none of those — its own Severity is Warning for every compatibility finding it emits.
• Profile contamination sentinels. New-PSSACompatibilityProfile.ps1 derives its "these must be absent from a clean 7 profile" probe list from the Command-kind rules. Every sentinel comes from a superseded rule; delete them and the generator has nothing left to validate against.

This is why the split is knowledge vs detection rather than keep vs delete. It also removes a failure mode: when the same break could be reported by two detectors, the deduplication was a static catalog attribute rather than a real join against the analyzer's output, so a supersession that stopped being true would fail open. With one detector there is nothing to deduplicate.

Two consequences for anyone extending the catalog:

• Do not add new rules that merely assert "this command is gone". Confirm against the profile first; if PSScriptAnalyzer reports it, tag the rule SupersededBy — it becomes enrichment, not a second detector.
• Rules for the blind-spot table above belong here, and nowhere else.

When measuring coverage, always pass -IncludeRule. A Settings hashtable configures the rules it names but does not restrict the run to them, so the default rule set fires as well. That is how Send-MailMessage first appeared to be covered — the hit was PSUseCmdletCorrectly complaining about missing mandatory parameters, not a compatibility finding at all.

Generating the compatibility profile

PSScriptAnalyzer's accuracy is entirely determined by the profile behind it, and the profiles it ships are not fit for this purpose: they top out at PowerShell 7.0.0, they were built on someone else's machine, and they inventory whatever module versions that machine happened to have.

Generate one on the target host instead:

pwsh -NoProfile -File <skill>/scripts/New-PSSACompatibilityProfile.ps1 -OutputPath .github/upgrades/<scenarioId>/target-profile.json -TargetPlatform Windows -TargetPSVersion 7.4

-TargetPlatform and -TargetPSVersion do not change what is generated — a profile only ever describes the interpreter it ran under. They exist to make a mismatch audible, because both failure modes are silent and both point the same way: a host that is newer or richer than the target inventories things the target does not have, suppressing exactly the findings the migration exists to surface. Generating on a host older than the target can only over-report and is noted rather than warned about. Run this under the pwsh the user is actually migrating to.

The script does three things:

1. Provisions modules onto PSModulePath before reflecting. The default pins Pester:5.0:5.99. Windows ships Pester 3.4.0 in-box, whose Should takes no declared parameters at all (raw $args), so a profile built over it records zero parameters and rejects every -Be/-Match/-Throw — a single wrong module version can dominate the whole report with false findings. It also prunes versions newer than the pin, because the analyzer unions parameters across versions and a newer major silently masks real findings.
2. Generates the profile against the running host.
3. Validates it by round-tripping sentinels, and writes a <profile>.validation.json beside it.

Reading the validation result

FAIL means contamination: if WindowsCompatibility or an implicit remoting session was loaded during generation, its proxy functions for Get-WmiObject and Get-EventLog get inventoried as real commands, and the analyzer then goes silent on every WMI site in the estate. That is a false pass — strictly worse than any false positive, which is why it is fatal rather than a warning. The check distinguishes them by CommandType: native commands are Cmdlet, compatibility shims are Function.

That distinction is not optional, because a bare presence test is guaranteed to be wrong here. On Windows, PowerShell 7 keeps the Windows PowerShell module path on $env:PSModulePath, so calling a removed command in a stock pwsh -NoProfile silently autoloads the 5.1 module through the compatibility layer and answers with a generated proxy. Get-Command Get-WmiObject therefore succeeds on a perfectly clean host. Only CommandType separates the two:

$c = Get-Command Get-WmiObject; $c.CommandType   # Function => shim, Cmdlet => native

A WARN is normal and useful. On a stock Windows 11 host it reports Get-WinEvent, Get-Counter, and System.Data.SqlClient.SqlConnection — all three work at runtime but are dropped during generation, so every use of them would otherwise be chased as a real blocker. Getting that list before triage instead of discovering it finding-by-finding is the point of the rung.

Running PSScriptAnalyzer against the profile

Use the wrapper, not a hand-rolled Invoke-ScriptAnalyzer call:

pwsh -NoProfile -File <skill>/scripts/Invoke-PSSACompatibilityScan.ps1 -Path <scope-root> -ProfilePath .github/upgrades/<scenarioId>/target-profile.json -TargetPSVersion 7.4 -OutputPath .github/upgrades/<scenarioId>/pssa-findings.json

The direct call has four traps, and three of them fail by reporting a clean estate, which on primary detection is the worst possible failure mode:

The wrapper closes all four. It also refuses to run against a profile whose validation status is FAIL, carries MissingCommands/MissingTypes into the output as falsePositiveLedger, and tracks files the analyzer could not process — a file that errored contributed zero findings without being analyzed, which is not the same as clean. Any such file makes the run coverage: INCOMPLETE and exits non-zero.

Exit code is 1 on findings or on any coverage gap, 0 only on a clean and complete run.

Why not just search for the strings

Text search cannot tell code from prose, and PowerShell estates are full of prose that looks like code:

• Comment-based help almost always contains .EXAMPLE Get-WmiObject -Class Win32_BIOS.
• A comment reading # do not call powershell.exe here is not a call.
• A here-string containing a script template is data, not code.
• -Enc Byte is -Encoding Byte — PowerShell resolves unambiguous parameter prefixes, and no regex knows the parameter set.
• Add-Content @splat may or may not set -Encoding; only the parser can see that the parameter set is hidden behind splatting and that the call must therefore not be reported.

Every one of those is a false positive or a false negative under grep / Select-String, and a false positive here becomes a must-remediate item on someone's migration plan. Use the parser.

Prerequisite: locate a host

The scan runs under PowerShell itself. Before scanning, establish which hosts are available and tell the user which one you used — the choice affects fidelity (see below).

Get-Command pwsh, powershell -ErrorAction SilentlyContinue |
    Select-Object Name, Version, Source

• pwsh (PowerShell 7.x) — required. It is the target engine, so its verdict is the one that matters, and it is the only host that can generate the PSScriptAnalyzer compatibility profile the primary detector runs against. If it is missing, stop and have it installed; PowerShell 7 is a hard-stop prerequisite for this scenario.
• powershell (Windows PowerShell 5.1) — use it in addition to pwsh when the estate contains workflows (see below), never as a substitute for it. A sidecar scan under 5.1 cannot stand in for the primary detector.
• Neither — stop. Report that the scan cannot run and that PowerShell 7 is required for the migration regardless. Do not fall back to Select-String and present the result as an inventory.

The script only reads files and writes its output file. It never executes the scripts it scans.

Running the scan

Check for contributed rules first (see Organisation knowledge below) — a scan run without them reports internal snap-ins as generic, unremediated blockers.

pwsh -NoProfile -File <skill>/scripts/Get-PSCompatibilityScan.ps1 -Path <scope-root> -AdditionalRulesPath .github/upgrades/<scenarioId>/contributed-rules.psd1 -OutputPath .github/upgrades/<scenarioId>/scan-findings.csv

Drop -AdditionalRulesPath when no skill contributed anything.

Useful parameters:

Json writes an envelope rather than a bare array: the findings plus the run metadata needed to tell two scans apart (host, catalog files loaded, contributed rule count, coverage status, counts by rule). Two scans of the same tree with different catalogs are different scans, and the bare rows do not say so. Both writes the CSV at -OutputPath and the JSON beside it.

Exit code is 1 when anything non-Advisory was found or when coverage is incomplete — an unreadable directory, a -Path that resolved to nothing, or a file that did not parse. 0 means clean and complete, so the call can gate a pipeline step on it.

Write the CSV outside the scanned tree, or into a directory that is in -ExcludeDirectory. Otherwise a later re-scan picks up its own output. Rule catalogs need no such care — the scan excludes every catalog it loaded from its own enumeration.

Reading the result

The script prints the summary you should read: counts by severity, counts by rule id, and the list of files that could not be fully parsed.

scan-findings.csv is a lookup table, not reading material. On a real estate it is tens of thousands of rows and will blow out the context window. Query it per file or per rule id when you reach that item in the execution loop; never read it whole.

Columns: File, Line, RuleId, Category, Severity, Fidelity, DetectedBy, Snippet

DetectedBy is catalog on every row. It is retained so the schema is stable for anything already consuming it, but it no longer carries a decision: the sidecar only runs its active rules, and every finding it emits is one PSScriptAnalyzer does not report. Superseded rules are knowledge-only and never reach this file — their content arrives instead as the CatalogRuleId, Category, CatalogSeverity, Skill and Remediation columns stamped onto the PSSA findings by Invoke-PSSACompatibilityScan.ps1.

The two outputs do not duplicate each other at the rule level. Add both to the plan.

One exception is deliberate. exchange-snapin (the only rule carrying Supersedes) overlays a specific answer on a generic analyzer finding: PSSA reports Add-PSSnapin Microsoft.Exchange... as the generic snapin Blocker, and the sidecar adds the Exchange-specific remediation for the same site. One site, two findings. Count it once and plan from the specific one.

# every file affected by one rule
Import-Csv scan-findings.csv | Where-Object RuleId -eq 'send-mailmessage' |
    Group-Object File | Select-Object Name, Count

# everything in one file
Import-Csv scan-findings.csv | Where-Object File -eq $target

The exit code is non-zero if any non-Advisory finding remains, because as an execution re-scan gate a leftover blocker is a blocker.

Fidelity: Full vs Tokens

Every finding carries a Fidelity column.

• Full — the file parsed cleanly and the syntax tree was walked. Every rule applies.
• Tokens — the file did not parse under the host that ran the scan. The token stream survives a parse failure intact and is still fully classified, so name-based rules (commands, keywords, types, modules, string literals, member names) still apply and comments are still excluded. CommandArgument rules degrade to a broad unanchored match — deliberately trading precision for recall, since dropping a Blocker on an unparseable file is the worse error. Rules that need real tree shape cannot be evaluated at all: Parameter, ParameterValue, MissingParameter, NullComparison, FileRedirection and StaticMember. That includes com-object and encoding-default, both easy to overlook. The run summary lists the exact rule IDs that were skipped, so read it rather than inferring; a clean result for those rules on a degraded file means not checked, not not present.

The most common cause is workflow, which PowerShell 7 refuses to parse at all (Workflow is not supported in PowerShell 6+). That is itself a Blocker finding, so a degraded file is usually the file that most needs migrating.

A degraded file counts as a coverage gap, so the run reports coverage : INCOMPLETE and exits 1 even when it found nothing. That is deliberate: the rules it skipped are the ones most likely to hold the blocker, so a 0 exit would be the scan's clean bill of health for a file it never finished reading.

If the summary reports degraded files, re-run the scan under Windows PowerShell 5.1 for those paths — 5.1 parses workflows, so they come back at Full fidelity:

$degraded = Import-Csv scan-findings.csv |
    Where-Object Fidelity -eq 'Tokens' |
    Select-Object -ExpandProperty File -Unique
powershell -NoProfile -File <skill>/scripts/Get-PSCompatibilityScan.ps1 -Path $degraded -OutputPath .github/upgrades/<scenarioId>/scan-findings-51.csv

Genuinely malformed scripts also land at Tokens fidelity, and the summary prints the parse error for each. Do not silently ignore those — a script that does not parse under either host is broken today, which is a finding in its own right and worth raising with the user.

Severity model

Advisory findings do not fail the scan and must not be presented as migration blockers.

The six encoding rules in particular fire on a large fraction of any real estate, so report them as counts, not as a task list. They are split by behaviour so the count means something:

The first four are the ones you cannot dismiss with "our data is all ASCII".

Extending the catalog

The rules live in rules/PSCompatibilityRules.psd1 as data, loaded with Import-PowerShellDataFile, which parses restricted data-language literals and never evaluates code. A rule file therefore cannot execute anything — keep it that way. If a rule needs behaviour, it needs a new Kind implemented in the script, not code smuggled into the data.

There are two ways in, and they are not equivalent:

Never edit the shipped file inside a customer repo.

A rule is:

@{
    Id          = 'contoso-legacy-module'
    Kind        = 'Module'
    Match       = @('Contoso.Legacy.Admin')
    Category    = 'InternalModule'
    Severity    = 'Blocker'
    Remediation = 'Contoso.Legacy.Admin is .NET Framework only. Use Contoso.Admin 3.x.'
    Skill       = 'fixing-windows-only-modules'
}

Available Kind values, and what each matches:

Supersedes suppresses a more general rule when a specific one fires on the same line — exchange-snapin supersedes snapin, so Add-PSSnapin Microsoft.Exchange.Management.PowerShell.E2010 is one finding, not two. This is intra-catalog: both rules belong to this scan.

SupersededBy is the opposite direction and crosses tools. It names a PSScriptAnalyzer rule that was measured to report the same sites, and it takes the rule out of detection entirely: the rule no longer runs and emits nothing. Its body becomes a knowledge record that Invoke-PSSACompatibilityScan.ps1 joins onto the analyzer's own findings, and a source of profile contamination sentinels. Do not set it by guesswork — probe the rule's targets against a validated profile first, with -IncludeRule, and only tag what comes back fully covered. Tagging a rule PSSA does not report silently deletes a detector.

Skill names the remediation skill to load for that bucket. The planner emits it as a #skill: marker on the task.

Organisation knowledge: contributed rules and snap-in maps

Writing a .psd1 is fine for someone who has read this file. It is the wrong ask for the person who actually knows the answer — the owner of an internal snap-in. So a user contributes knowledge the same way they contribute anything else in this product: a skill in .github/skills/, discovered automatically. No flag to pass, nothing to tell the agent.

This mirrors the existing upgrade-option: and provides: task-breakdown-hints conventions.

A contribution skill declares provides: powershell-compatibility-rules in its description:

---
name: contoso-powershell-map
description: >
  Contoso snap-in and module inventory for the PowerShell 5.1 → 7 migration.
  provides: powershell-compatibility-rules
metadata:
  discovery: lazy
  traits: PowerShell
---

## Snapin Module Map

| Snap-in | Replacement module | Notes |
|---|---|---|
| Contoso.Foo.Snapin | Contoso.Foo.Management | 3.x or later |
| Contoso.Bar.Snapin | — | No module. Use implicit remoting. |

Before running the scan, check Available Skills for that marker. For each matching skill, read its ## Snapin Module Map and project every row into a rule, then pass the projected file as -AdditionalRulesPath:

@{
    Id          = 'contoso-foo-snapin'          # stable, derived from the snap-in name
    Kind        = 'StringLiteral'
    Match       = @('Contoso.Foo.Snapin')
    MatchMode   = 'Contains'
    Category    = 'PSSnapin'
    Severity    = 'Blocker'
    Supersedes  = @('snapin')                   # so the generic rule does not double-count
    Remediation = 'Replace Add-PSSnapin Contoso.Foo.Snapin with Import-Module Contoso.Foo.Management (3.x or later).'
    Skill       = 'handling-removed-snapins'
}

Write the projected catalog to the operation folder (.github/upgrades/<scenarioId>/contributed-rules.psd1), not into the source tree.

A —, none, or empty Replacement column is meaningful, not missing: it says a module replacement was looked for and does not exist. Project it with a remediation naming implicit remoting or the Windows PowerShell compatibility layer rather than telling the migrator to go find a module. This is the main thing the shipped catalog cannot express — it only knows that some snap-in was loaded, never which one or what replaces it.

A snap-in with no row falls through to the generic snapin rule, which is the correct outcome: it is still reported as a Blocker, just without a specific remediation.

Other sections a contribution skill may carry:

• ## Compatibility Rules — a fenced powershell block containing raw rule hashtables, for knowledge that is not a snap-in mapping. Pass it through as-is.

Use the same Id as a shipped rule to correct one in place — severity, wording, or an internal policy call. The scan reports what was added and what was overridden, so a merged catalog never silently changes the result.

A mapping given in conversation

A skill is the right shape for an inventory an organisation maintains. It is overkill for someone who knows two snap-ins and wants to say so. If the user states a mapping in conversation — "Contoso.Foo.Snapin is ContosoFoo now", "Contoso.Legacy.Snapin has no replacement" — project it into the same contributed-rules.psd1 and pass it the same way.

Do this rather than just remembering it. A mapping that only lives in the conversation changes how you remediate but not what the scan reports, so the CSV still says snapin, the assessment still counts an unnamed blocker, and the execution re-scan gate compares against a baseline that disagrees with what the user told you. Every artifact must reflect the same knowledge.

Precedence, most specific last: shipped catalog → contribution skills → what the user said in this conversation. The user is in front of you and knows their estate; if they contradict a contributed skill, they win — but say that you are overriding it, and name the skill.

Conversation-sourced rules are per operation, not permanent: they live in the operation folder and a fresh clone starts without them. When the user gives you one, offer once to promote it into a provides: powershell-compatibility-rules skill so it survives. Do not nag — offer, and drop it if declined.

Asking for the mappings you are missing

Do not expect the user to know upfront which snap-ins matter. Let the scan find out, then ask.

After the scan, if there are generic snapin findings, pull the distinct snap-in names out of their Snippet column and present that list. It is short, concrete, and it is the one question in this whole assessment where the user holds information you cannot derive. Ask for a replacement module or an explicit "no replacement" for each, project the answers, and re-run the scan so the findings carry the specific rule ids.

Re-run only if you actually received mappings — a re-scan that changes nothing is pure cost on a large estate.

Stability contract

Id values are the join key between the findings CSV, the assessment, plan tasks, and the execution re-scan gate. Never reuse or repurpose an id. Adding rules is safe; renaming one silently breaks every plan written against the old name.

Narrowing a rule counts as repurposing. If a rule's meaning changes, retire the id and add a new one — otherwise a scan run before the change and one run after are silently incomparable, and a dropped count reads as progress.

Retired ids (never to be reused):

What this skill does not do

It is an inventory, not a verification. It tells you what is there before the migration and confirms the count reached zero after. It cannot tell you the rewrite is correct — a Get-CimInstance call with the wrong property name scans clean and fails at runtime. Proving the fix works is the validation ladder's job: parse check, PSScriptAnalyzer PSUseCompatible*, then actually running the script under pwsh.