Documentation Request: Platform-Aware Installation for `Install-PSResource`

[jshigetomi]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Document new Get-Foo cmdlet" instead of "New cmdlet."

Summary

Install-PSResource has been updated with platform-aware installation capabilities that automatically filter runtime assets and target framework libraries during package extraction.

Two new parameters have been added and the extraction pipeline now performs RID (Runtime Identifier) and TFM (Target Framework Moniker) filtering by default.

The published documentation at Install-PSResource needs to be updated to reflect these changes.

Details

New Parameters

-RuntimeIdentifier <String>

Specifies the Runtime Identifier (RID) to filter platform-specific assets. When specified, only runtime assets compatible with this RID are installed instead of the auto-detected platform. Use this for cross-platform deployment scenarios (e.g., preparing a Linux package from Windows).

Valid values follow the .NET RID catalog:
win-x64, win-x86, win-arm64, linux-x64, linux-arm64, linux-musl-x64, osx-x64, osx-arm64, etc.

Property	Value
Type	String
Default value	None (auto-detected from current platform)
Supports wildcards	False
Position	Named
Mandatory	False
Parameter sets	NameParameterSet, InputObjectParameterSet

Example:

# Install for Linux x64 from a Windows machine (cross-platform deployment)
Install-PSResource -Name PSReadLine -RuntimeIdentifier 'linux-x64' -Path ./deploy/linux

# Install for Windows ARM64
Install-PSResource -Name PSReadLine -RuntimeIdentifier 'win-arm64'

-TargetFramework <String>

Specifies the Target Framework Moniker (TFM) to select for lib/ folder filtering. When specified, only lib/ assets matching this TFM are installed instead of the auto-detected framework. Use this for cross-framework deployment scenarios (e.g., preparing a .NET 6 package from a .NET 8 host).

Valid values follow the NuGet TFM format:
net472, netstandard2.0, net6.0, net8.0, etc.

Property	Value
Type	String
Default value	None (auto-detected from running PowerShell host)
Supports wildcards	False
Position	Named
Mandatory	False
Parameter sets	NameParameterSet, InputObjectParameterSet

Example:

# Install targeting .NET 6.0 framework from a .NET 8 host
Install-PSResource -Name MyModule -TargetFramework 'net6.0'

# Combine both overrides for cross-platform deployment
Install-PSResource -Name MyModule -RuntimeIdentifier 'linux-x64' -TargetFramework 'net6.0'

New Default Behavior to Document

Automatic RID Filtering

Install-PSResource now automatically detects the current platform's Runtime Identifier and only installs runtime assets for compatible RIDs. For modules with native dependencies (e.g., PSReadLine with SQLite), this reduces installed size by up to 95%.

Root-level RID folders: PowerShell modules use root-level RID-named folders (e.g., win-x64/, linux-x64/) for native assets, rather than the NuGet convention runtimes/{rid}/native/. PSResourceGet filters based on these root-level RID folders.

RID compatibility chains are supported. For example, installing on win10-x64 also includes assets from the win-x64 folder.

Automatic TFM Filtering

Install-PSResource now uses NuGet.Frameworks.FrameworkReducer to select the best-match target framework from the package's lib/ folder. Only the matching TFM's assemblies are extracted.

Merge Behavior: -TargetFramework and -RuntimeIdentifier on Already-Installed Modules

The module install path is {ModulesDir}/{Name}/{Version}/ — keyed by name and version only. When the same name+version is already installed and the user explicitly specifies -TargetFramework or -RuntimeIdentifier, Install-PSResource now merges the additional content into the existing install directory without overwriting existing files.

# Step 1: Normal install from PS7 — gets net8.0 assemblies
Install-PSResource -Name MyModule

# Step 2: Add net472 support for Windows PowerShell 5.1
Install-PSResource -Name MyModule -TargetFramework 'net472'

After both commands, the installed module contains both TFMs:

MyModule/1.0.0/
├── MyModule.psd1
├── lib/
│   ├── net8.0/
│   │   └── MyModule.dll    ← from step 1
│   └── net472/
│       └── MyModule.dll    ← from step 2 (merged)

The same applies for RID merging:

# Step 1: Normal install on Windows — gets win-x64 native assets
Install-PSResource -Name MyModule

# Step 2: Add linux-x64 native assets for cross-platform deployment
Install-PSResource -Name MyModule -RuntimeIdentifier 'linux-x64'

---

Key behaviors:

• Existing files are never overwritten during a merge — only new files and directories are added.
• Without explicit -TargetFramework/-RuntimeIdentifier, the "already installed" skip behavior is unchanged.
• If the specified TFM/RID does not exist in the package, a warning is emitted:
  "The specified TargetFramework 'net472' was not found in this package. No lib/ assemblies were installed. Available TFMs: net8.0"
"The specified RuntimeIdentifier 'linux-x64' was not found in this package. No platform-specific assets were installed. Available RIDs: 'win-x32' 'win-x64' 'win-x86'"
• -Reinstall overrides merge behavior: When -Reinstall is used alongside -TargetFramework/-RuntimeIdentifier, the existing install is fully replaced (not merged). Only the specified TFM/RID content is installed. Use -Reinstall when you want a clean filtered install rather than additive merge.

Cross-lineage TFM warning

• When the selected TFM belongs to a different .NET lineage than other TFMs in the package (e.g., .NET Core vs .NET Framework), a warning is emitted indicating the skipped assemblies.
  "WARNING: This package contains assemblies for net472 which were not installed because the current runtime selected net8.0. If you also use this module on Windows PowerShell 5.1, run: Install-PSResource -Name <ModuleName> -TargetFramework 'net472'"
• To add support for the other host, run Install-PSResource -Name <ModuleName> -TargetFramework '<skippedTfm>' which will merge the missing assemblies into the existing install without overwriting existing files.

---

Articles

No response

Related Source Pull Requests

• Platform-aware Install-PSResource: filter runtimes by RID, libs by TFM PowerShell/PSResourceGet#1963

Related Source Issues

• PSGet needs to support selectively installing modules that support multiple platform runtimes PowerShell/PSResourceGet#794