Migrating Powershell Sdk

System.Management.Automation Migration

Overview

Migrate PowerShell cmdlet projects from .NET Framework (Windows PowerShell 5.1) to modern .NET (.NET 6+). The core change is replacing the Windows PowerShell reference assembly with the cross-platform System.Management.Automation NuGet package. Most code remains unchanged because the SDK types (PSCmdlet, Cmdlet, PSObject, attributes) are identical across both packages.

Scope. This skill retargets the project. It does not read or edit .ps1/.psm1 files, so it will not find the script-level 5.1 → 7 breaks — removed cmdlets, snap-ins, WMI, encoding defaults. If the repository also carries loose PowerShell scripts that must run on PowerShell 7, those are the powershell-5.1-to-7-upgrade scenario's work, not this skill's.

Package Reference Changes

Old References (Remove)

<!-- GAC/file reference -->
<Reference Include="System.Management.Automation" />

<!-- Windows PowerShell ref assemblies NuGet -->
<PackageReference Include="Microsoft.PowerShell.5.ReferenceAssemblies" Version="1.1.0" />

New Reference (Add)

<!-- Cross-platform NuGet package; use version matching target framework -->
<PackageReference Include="System.Management.Automation" Version="{version-for-target-framework}" />

<!-- OR for dual-targeting Windows PowerShell 5.1 + PowerShell 7 -->
<PackageReference Include="PowerShellStandard.Library" Version="{stable-version}" />

Choosing the Right Package

Use tools or PowerShell releases to find the latest stable package version for the target framework.

Workflow

Migration Progress:
- [ ] Step 1: Detect PowerShell SDK usage
- [ ] Step 2: Determine target framework and package version
- [ ] Step 3: Update project file references
- [ ] Step 4: Handle API differences
- [ ] Step 5: Update module manifest
- [ ] Step 6: Build and verify

Step 1: Detect PowerShell SDK Usage

Scan the project for:

• using System.Management.Automation; statements
• Types inheriting from Cmdlet or PSCmdlet
• [Cmdlet(...)] attributes
• Reference type: GAC reference, Microsoft.PowerShell.5.ReferenceAssemblies NuGet, or direct file reference

If the project already uses the cross-platform NuGet package, no migration is needed.

Step 2: Determine Target Framework and Package Version

1. Check if the user specified a target framework (e.g., "migrate to net10.0")
2. Otherwise, read <TargetFramework> or <TargetFrameworks> from the project file or Directory.Build.props
3. Look up the best System.Management.Automation package version for that framework
4. If the project must support both Windows PowerShell 5.1 and PowerShell 7+, choose PowerShellStandard.Library instead — it targets netstandard2.0 so a single binary works in both hosts

Step 3: Update Project File References

Remove old references and add the new package reference (see "Package Reference Changes" above).

Step 4: Handle API Differences

Most SDK types are identical, but these APIs changed:

Step 5: Update Module Manifest (If Applicable)

If the project produces a PowerShell module, update the .psd1:

@{
    PowerShellVersion     = '7.0'
    CompatiblePSEditions  = @('Core')
    ProcessorArchitecture = 'None'
}

Step 6: Build and Verify

1. Build the module:

   dotnet build
   

2. Import and check cmdlet registration:

   Import-Module ./bin/Debug/{target-framework}/MyModule.dll
   Get-Command -Module MyModule
   

3. Run cmdlet smoke tests to verify parameter binding and pipeline operations

Troubleshooting

Cmdlets Not Found After Import

Ensure the assembly contains [Cmdlet] attributes and the namespace is correctly exported in the module manifest.

Type Conflicts with Other Modules

Another loaded module may bundle a different System.Management.Automation version. Use assembly load contexts or module isolation boundaries to resolve.

Missing APIs at Runtime

Some Windows PowerShell APIs have no PowerShell 7 equivalent. Check the PowerShell 7 SDK docs for alternatives.

Snap-in Code

PowerShell 7 does not support snap-ins. Remove PSSnapIn-derived classes and replace with:

• Module manifests (.psd1) for metadata
• RequiredModules in the manifest for dependency management