Document MSIX-only system-wide configuration in a PFN-isolated ProgramData store

Prima conferma il comportamento e la formulazione della release in PowerShell/PowerShell#27535, quindi aggiorna about_PowerShell_Config, about_Execution_Policies, about_Windows_PowerShell_Compatibility e la documentazione di installazione Windows/MSIX indicata qui. Copri il percorso ProgramData esclusivo di MSIX, i livelli di configurazione, le autorizzazioni, la persistenza, la pulizia e il comportamento dei comandi, escludendo il percorso superato e le funzionalità fuori ambito; il lavoro è completo quando tutti gli scenari elencati sono documentati in modo coerente con l’implementazione integrata.

Draft documentation tracking issue filed by the PowerShell team for an upcoming feature. The target release remains subject to the implementation PR being merged.

Current implementation: PowerShell/PowerShell#27535
Earlier design prototype: PowerShell/PowerShell#27632
Design discussion: PowerShell/PowerShell#27697
Umbrella: PowerShell/PowerShell#27565

Summary

For Windows MSIX-packaged PowerShell only, machine-wide configuration writes are redirected from the read-only $PSHOME installation directory to an admin-controlled, package-family-isolated directory under ProgramData:

%ProgramData%\Microsoft\PowerShell\<PackageFamilyName>\powershell.config.json

%ProgramData% is normally C:\ProgramData.

The shipped file at $PSHOME\powershell.config.json remains a read-only product-defaults layer. PowerShell does not copy or seed the whole product file into ProgramData. It writes only keys changed by an administrator.

This change is MSIX-specific:

• Windows MSIX packages use the new ProgramData override.
• Windows MSI, ZIP, and other unpackaged installations continue using $PSHOME.
• Linux and macOS continue using $PSHOME; no /etc/powershell relocation is included.
• Current-user configuration remains in the existing per-user configuration directory.
• Profiles are not relocated by this work.

Why the location changes

MSIX installs PowerShell into a read-only, tamper-protected package location. Machine-wide settings therefore cannot be safely written into $PSHOME.

PowerShell detects the current process's package identity with GetCurrentPackageFamilyName() and composes the ProgramData path itself. The implementation does not use the Windows App SDK MachineFolder manifest extension or its WindowsApps-backed path.

Using the package family name isolates Stable, Preview, and LTS packages when they have different package identities, preventing configuration from bleeding across channels.

Creation, permissions, and cleanup

PowerShell creates the ProgramData directory tree on the first redirected machine-wide write. It protects the PowerShell root and package-family directory from inheriting ambient ProgramData permissions, then applies inheritable rules at those directory boundaries:

• Owner: Built-in Administrators
• SYSTEM: Full Control
• Built-in Administrators: Full Control
• Built-in Users: Read and Execute

The configuration file and any future children inside the package-family directory inherit those rules. This avoids duplicating protected ACLs on every file while keeping broader or attacker-controlled parent permissions out of the machine configuration path.

Machine-wide writes require elevation. All users can read the resulting configuration.

For defense in depth, PowerShell rejects reparse points, inherited ACLs on the protected directory boundaries, a configuration file that does not inherit from the package-family directory, an untrusted owner, or a write-capable allow rule for an identity other than Administrators or SYSTEM.

The ProgramData file is intentionally outside the MSIX package and survives package upgrades and ordinary uninstall/reinstall operations. PowerShell does not automatically remove it during uninstall. Documentation should explain how an administrator can remove the package-family directory manually when permanent cleanup is desired.

Configuration layers and merge behavior

The implementation adds an internal MachineFolder configuration layer between the current-user configuration and the shipped $PSHOME defaults.

Preference settings

Preference settings use the first scope that defines the key:

CurrentUser > MachineFolder > $PSHOME (AllUsers product defaults)

Examples include:

• ExecutionPolicy from JSON configuration
• DisableImplicitWinCompat
• WindowsPowerShellCompatibilityNoClobberModuleList

Policy-list settings

Policy-style lists are combined as a case-insensitive union across CurrentUser, MachineFolder, and $PSHOME. A higher-precedence scope cannot remove an entry supplied by another scope.

The current setting using this behavior is:

• WindowsPowerShellCompatibilityModuleDenyList

Group Policy

Registry-backed Group Policy remains above all JSON configuration:

MachinePolicy > UserPolicy > Process > CurrentUser > LocalMachine

The new storage location does not change this public execution-policy ordering.

User-facing command behavior

Set-ExecutionPolicy

For an MSIX installation:

• Set-ExecutionPolicy -Scope LocalMachine writes the changed value to the package-family ProgramData file.
• Removing the LocalMachine execution-policy value removes it from that same ProgramData file.
• Reading LocalMachine policy checks the ProgramData override first and then falls back to the shipped $PSHOME value.

LocalMachine remains the public scope name. Users do not need to select an additional scope to get the redirected behavior.

Experimental-feature cmdlets

Enable-ExperimentalFeature and Disable-ExperimentalFeature retain their existing implementation. Their AllUsers behavior is not redirected by this change and still targets $PSHOME, which remains read-only for MSIX.

The redesign needed to merge experimental-feature enable/disable state across machine layers is tracked separately in PowerShell/PowerShell#27702.

Configuration-discovery cmdlet

This implementation does not add Get-PowerShellConfiguration or another new configuration-discovery cmdlet. Configuration discovery/export remains separate work.

Documentation to add or update

• about_PowerShell_Config
  • Document the MSIX-only ProgramData path.
  • Explain the three effective layers and their merge behavior.
  • Make clear that $PSHOME\powershell.config.json remains the immutable product-defaults file.
  • Explain elevation, ACLs, package-family isolation, and uninstall persistence.
• about_Execution_Policies
  • Explain that LocalMachine uses the ProgramData override for MSIX.
  • Preserve the existing public scope ordering.
  • Distinguish JSON execution-policy preferences from registry-backed Group Policy.
• about_Windows_PowerShell_Compatibility
  • Document union behavior for WindowsPowerShellCompatibilityModuleDenyList.
  • Document preference behavior for DisableImplicitWinCompat and WindowsPowerShellCompatibilityNoClobberModuleList.
• Windows/MSIX installation documentation
  • Explain that the ProgramData configuration survives uninstall/reinstall.
  • Provide optional manual-cleanup instructions.
• Add a practical how-to for editing machine-wide settings in MSIX PowerShell:
  • Locate %ProgramData%\Microsoft\PowerShell\<PackageFamilyName>.
  • Start an elevated editor or PowerShell session.
  • Create or edit powershell.config.json.
  • Avoid editing the $PSHOME copy.

Documentation should not reference the superseded WindowsApps Families\ApplicationData\<PFN>\Machine path or the appdata:MachineFolder manifest SDDL.

Out of scope

• AllUsers profile relocation ($PROFILE.AllUsersAllHosts and $PROFILE.AllUsersCurrentHost) - PowerShell/PowerShell#27564
• Experimental-feature MachineFolder merge semantics - PowerShell/PowerShell#27702
• Updatable help under MSIX (Update-Help -Scope AllUsers) - PowerShell/PowerShell#27699
• Session configuration (.pssc) relocation - PowerShell/PowerShell#9278
• Configuration discovery or effective-config export cmdlet - PowerShell/PowerShell#27698

References

• Current implementation PR: PowerShell/PowerShell#27535
• Earlier MachineFolder design prototype (closed): PowerShell/PowerShell#27632
• Design issue: PowerShell/PowerShell#27697
• Umbrella tracking issue: PowerShell/PowerShell#27565

---

This issue reflects the latest implementation plan in PowerShell/PowerShell#27535. Exact release targeting and final wording should be confirmed when the implementation merges.