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.

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