PowerShell · jshigetomi · Mar 13, 2025 · Mar 17, 2025 · Aug 6, 2025 · Aug 6, 2025
@@ -165,8 +165,20 @@ public static bool IsStaSupported
         // Gets the location for cache and config folders.
         internal static readonly string CacheDirectory = Platform.SelectProductNameForDirectory(Platform.XDG_Type.CACHE);
         internal static readonly string ConfigDirectory = Platform.SelectProductNameForDirectory(Platform.XDG_Type.CONFIG);
+        internal static readonly string LegacyPSContentDirectory = Platform.SelectProductNameForDirectory(Platform.XDG_Type.DATA);
+        internal static readonly string LocalAppDataPSContentDirectory = Platform.SelectProductNameForDirectory(Platform.XDG_Type.DATA);
 #else
         // Gets the location for cache and config folders.
+        // Legacy Documents\PowerShell path kept for backward compatibility (modules fallback).
+        // The preferred location is LocalAppData\PowerShell via LocalAppDataPSContentDirectory.
+        internal static readonly string LegacyPSContentDirectory = SafeDeriveFromSpecialFolder(
+            Environment.SpecialFolder.Personal,
+            @"PowerShell");
+
+        internal static readonly string LocalAppDataPSContentDirectory = SafeDeriveFromSpecialFolder(
+            Environment.SpecialFolder.LocalApplicationData,
+            @"PowerShell");
+
         internal static readonly string CacheDirectory = SafeDeriveFromSpecialFolder(
             Environment.SpecialFolder.LocalApplicationData,
             @"Microsoft\PowerShell");

@@ -0,0 +1,261 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.IO;
+using System.Management.Automation;
+using System.Management.Automation.Configuration;
+using System.Management.Automation.Internal;
+
+namespace Microsoft.PowerShell.Commands
+{
+    /// <summary>
+    /// Implements Get-PSContentPath cmdlet.
+    /// </summary>
+    [Cmdlet(VerbsCommon.Get, "PSContentPath", HelpUri = "https://go.microsoft.com/fwlink/?linkid=2344910")]
+    [OutputType(typeof(DirectoryInfo))]
+    public class GetPSContentPathCommand : PSCmdlet
+    {
+        /// <summary>
+        /// EndProcessing method of this cmdlet.
+        /// Outputs the PSContentPath as a DirectoryInfo object with ConfigFile NoteProperty.
+        /// </summary>
+        protected override void EndProcessing()
+        {
+            try
+            {
+                var psContentPath = Utils.GetPSContentPath();
+                var configFilePath = PowerShellConfig.Instance.GetConfigFilePath(ConfigScope.CurrentUser);
+
+                // Create DirectoryInfo object
+                var directoryInfo = new DirectoryInfo(psContentPath);
+
+                // Wrap in PSObject to add the ConfigFile NoteProperty
+                var result = PSObject.AsPSObject(directoryInfo);
+                result.Properties.Add(new PSNoteProperty("ConfigFile", configFilePath));
+
+                WriteObject(result);
+            }
+            catch (Exception ex)
+            {
+                WriteError(new ErrorRecord(
+                    ex,
+                    "GetPSContentPathFailed",
+                    ErrorCategory.ReadError,
+                    null));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Implements Set-PSContentPath cmdlet.
+    /// </summary>
+    [Cmdlet(VerbsCommon.Set, "PSContentPath", SupportsShouldProcess = true, ConfirmImpact = ConfirmImpact.High, HelpUri = "https://go.microsoft.com/fwlink/?linkid=2344807")]
+    public class SetPSContentPathCommand : PSCmdlet
+    {
+        private const string RestartWarning = "Restart PowerShell for the content path change to take full effect on module paths, profiles, help files, and scripts.";
+        /// <summary>
+        /// Gets or sets the PSContentPath to configure.
+        /// </summary>
+        [Parameter(Mandatory = true, Position = 0, ParameterSetName = "Path")]
+        [ValidateNotNullOrEmpty]
+        public string Path { get; set; }
+
+        /// <summary>
+        /// Resets the PSContentPath to the platform default.
+        /// </summary>
+        [Parameter(Mandatory = true, ParameterSetName = "Default")]
+        public SwitchParameter Default { get; set; }
+
+        /// <summary>
+        /// EndProcessing method of this cmdlet.
+        /// Validates the path and sets the PSContentPath in the configuration.
+        /// </summary>
+        protected override void EndProcessing()
+        {
+            if (Default)
+            {
+                ResetToDefault();
+                return;
+            }
+
+            // Validate the path
+            if (!ValidatePath(Path))
+            {
+                return;
+            }
+
+            string expandedPath = Environment.ExpandEnvironmentVariables(Path);
+            string currentPath = Utils.GetPSContentPath();
+            string configFile = PowerShellConfig.Instance.GetConfigFilePath(ConfigScope.CurrentUser);
+
+            string target = $"Config file: '{configFile}'";
+            string action = $"Set PSUserContentPath from '{currentPath}' to '{expandedPath}'";
+
+            if (ShouldProcess(target, action))
+            {
+                try
+                {
+                    PowerShellConfig.Instance.SetPSContentPath(Path);
+
+                    // Update the $PSUserContentPath readonly variable in the current session
+                    UpdatePSUserContentPathVariable(expandedPath);
+
+                    WriteWarning(RestartWarning);
+                    WriteVerbose($"Successfully set PSContentPath to '{Path}'");
+                }
+                catch (Exception ex)
+                {
+                    WriteError(new ErrorRecord(
+                        ex,
+                        "SetPSContentPathFailed",
+                        ErrorCategory.WriteError,
+                        Path));
+                }
+            }
+        }
+
+        /// <summary>
+        /// Resets the PSContentPath to the platform default by clearing the custom config.
+        /// </summary>
+        /// <remarks>
+        /// Currently resets to Documents\PowerShell (LegacyPSContentDirectory) for backward compatibility.
+        /// In a future release, this will change to LocalAppData\PowerShell as the default content directory.
+        /// </remarks>
+        private void ResetToDefault()
+        {
+            string defaultPath = Platform.LegacyPSContentDirectory;
+            string currentPath = Utils.GetPSContentPath();
+            string configFile = PowerShellConfig.Instance.GetConfigFilePath(ConfigScope.CurrentUser);
+
+            string target = $"Config file: '{configFile}'";
+            string action = $"Reset PSUserContentPath from '{currentPath}' to platform default '{defaultPath}'";
+
+            if (ShouldProcess(target, action))
+            {
+                try
+                {
+                    // Clear the custom path from config (passing null/empty removes the key)
+                    PowerShellConfig.Instance.SetPSContentPath(null);
+
+                    // Update the variable to the platform default
+                    UpdatePSUserContentPathVariable(defaultPath);
+
+                    WriteWarning(RestartWarning);
+                    WriteVerbose($"Successfully reset PSContentPath to default: '{defaultPath}'");
+                }
+                catch (Exception ex)
+                {
+                    WriteError(new ErrorRecord(
+                        ex,
+                        "ResetPSContentPathFailed",
+                        ErrorCategory.WriteError,
+                        null));
+                }
+            }
+        }
+
+        /// <summary>
+        /// Updates the $PSUserContentPath readonly variable in the current session.
+        /// </summary>
+        /// <param name="newPath">The new path value to set.</param>
+        private void UpdatePSUserContentPathVariable(string newPath)
+        {
+            // Get the existing PSUserContentPathVariable and update its internal value
+            var existingVariable = SessionState.PSVariable.Get(SpecialVariables.PSUserContentPath);
+            if (existingVariable is PSUserContentPathVariable contentPathVariable)
+            {
+                contentPathVariable.UpdateValue(newPath);
+            }
+            else
+            {
+                // Fallback: create a new PSUserContentPathVariable (shouldn't normally happen)
+                var variable = new PSUserContentPathVariable(newPath);
+                SessionState.Internal.SetVariableAtScope(variable, "global", force: true, CommandOrigin.Internal);
+            }
+        }
+
+        /// <summary>
+        /// Validates that the provided path is a valid directory path.
+        /// </summary>
+        /// <param name="path">The path to validate.</param>
+        /// <returns>True if the path is valid, false otherwise.</returns>
+        private bool ValidatePath(string path)
+        {
+            try
+            {
+                // Expand environment variables if present
+                string expandedPath = Environment.ExpandEnvironmentVariables(path);
+
+                // Check if the path contains invalid characters using PowerShell's existing utility
+                if (PathUtils.ContainsInvalidPathChars(expandedPath))
+                {
+                    WriteError(new ErrorRecord(
+                        new ArgumentException($"The path '{path}' contains invalid characters."),
+                        "InvalidPathCharacters",
+                        ErrorCategory.InvalidArgument,
+                        path));
+                    return false;
+                }
+
+                // Check if the path is rooted (absolute path)
+                if (!System.IO.Path.IsPathRooted(expandedPath))
+                {
+                    WriteError(new ErrorRecord(
+                        new ArgumentException($"The path '{path}' must be an absolute path."),
+                        "RelativePathNotAllowed",
+                        ErrorCategory.InvalidArgument,
+                        path));
+                    return false;
+                }
+
+                // Try to get the full path to validate format
+                string fullPath = System.IO.Path.GetFullPath(expandedPath);
+
+                // Warn if the directory doesn't exist, but don't fail
+                if (!Directory.Exists(fullPath))
+                {
+                    WriteWarning($"The directory '{fullPath}' does not exist. It will be created when needed.");
+                }
+
+                return true;
+            }
+            catch (ArgumentException ex)
+            {
+                WriteError(new ErrorRecord(
+                    ex,
+                    "InvalidPathFormat",
+                    ErrorCategory.InvalidArgument,
+                    path));
+                return false;
+            }
+            catch (System.Security.SecurityException ex)
+            {
+                WriteError(new ErrorRecord(
+                    ex,
+                    "PathAccessDenied",
+                    ErrorCategory.PermissionDenied,
+                    path));
+                return false;
+            }
+            catch (NotSupportedException ex)
+            {
+                WriteError(new ErrorRecord(
+                    ex,
+                    "PathNotSupported",
+                    ErrorCategory.InvalidArgument,
+                    path));
+                return false;
+            }
+            catch (PathTooLongException ex)
+            {
+                WriteError(new ErrorRecord(
+                    ex,
+                    "PathTooLong",
+                    ErrorCategory.InvalidArgument,
+                    path));
+                return false;
+            }
+        }
+    }
+}
@@ -5250,7 +5250,7 @@ internal static void AnalyzePSSnapInAssembly(
                 }
 
                 Diagnostics.Assert(cmdletsCheck.Count == cmdlets.Count, "new Cmdlet added to System.Management.Automation.dll - update InitializeCoreCmdletsAndProviders");
-
+                
                 foreach (var pair in cmdletsCheck)
                 {
                     SessionStateCmdletEntry other;
@@ -5476,6 +5476,7 @@ private static void InitializeCoreCmdletsAndProviders(
                 { "Get-History",                       new SessionStateCmdletEntry("Get-History", typeof(GetHistoryCommand), helpFile) },
                 { "Get-Job",                           new SessionStateCmdletEntry("Get-Job", typeof(GetJobCommand), helpFile) },
                 { "Get-Module",                        new SessionStateCmdletEntry("Get-Module", typeof(GetModuleCommand), helpFile) },
+                { "Get-PSContentPath",                 new SessionStateCmdletEntry("Get-PSContentPath", typeof(GetPSContentPathCommand), helpFile) },
                 { "Get-PSHostProcessInfo",             new SessionStateCmdletEntry("Get-PSHostProcessInfo", typeof(GetPSHostProcessInfoCommand), helpFile) },
                 { "Get-PSSession",                     new SessionStateCmdletEntry("Get-PSSession", typeof(GetPSSessionCommand), helpFile) },
                 { "Get-PSSubsystem",                   new SessionStateCmdletEntry("Get-PSSubsystem", typeof(Subsystem.GetPSSubsystemCommand), helpFile) },
@@ -5498,6 +5499,7 @@ private static void InitializeCoreCmdletsAndProviders(
                 { "Remove-Module",                     new SessionStateCmdletEntry("Remove-Module", typeof(RemoveModuleCommand), helpFile) },
                 { "Remove-PSSession",                  new SessionStateCmdletEntry("Remove-PSSession", typeof(RemovePSSessionCommand), helpFile) },
                 { "Save-Help",                         new SessionStateCmdletEntry("Save-Help", typeof(SaveHelpCommand), helpFile) },
+                { "Set-PSContentPath",                 new SessionStateCmdletEntry("Set-PSContentPath", typeof(SetPSContentPathCommand), helpFile) },
                 { "Set-PSDebug",                       new SessionStateCmdletEntry("Set-PSDebug", typeof(SetPSDebugCommand), helpFile) },
                 { "Set-StrictMode",                    new SessionStateCmdletEntry("Set-StrictMode", typeof(SetStrictModeCommand), helpFile) },
                 { "Start-Job",                         new SessionStateCmdletEntry("Start-Job", typeof(StartJobCommand), helpFile) },

@@ -19,6 +19,7 @@ namespace System.Management.Automation
     internal static class Constants
     {
         public const string PSModulePathEnvVar = "PSModulePath";
+        public const string PSUserContentPathConfigKey = "PSUserContentPath";
     }
 
     /// <summary>
@@ -490,7 +491,7 @@ internal static bool IsModuleMatchingConstraints(
         /// <param name="requiredVersion">The required version of the expected module.</param>
         /// <param name="minimumVersion">The minimum required version of the expected module.</param>
         /// <param name="maximumVersion">The maximum required version of the expected module.</param>
-        /// <returns>True if the module info object matches all given constraints, false otherwise.</returns>
+        /// <returns>True if the module info object matches all the constraints on the module specification, false otherwise.</returns>
         internal static bool IsModuleMatchingConstraints(
             out ModuleMatchFailure matchFailureReason,
             PSModuleInfo moduleInfo,
@@ -961,17 +962,30 @@ internal static string GetModuleName(string path)
         /// <summary>
         /// Gets the personal module path.
         /// </summary>
-        /// <returns>Personal module path.</returns>
+        /// <returns>Personal module path, or null if the content path cannot be determined.</returns>
         internal static string GetPersonalModulePath()
         {
-#if UNIX
-            return Platform.SelectProductNameForDirectory(Platform.XDG_Type.USER_MODULES);
-#else
-            string myDocumentsPath = InternalTestHooks.SetMyDocumentsSpecialFolderToBlank
-                ? string.Empty
-                : Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments, Environment.SpecialFolderOption.DoNotVerify);
-            return string.IsNullOrEmpty(myDocumentsPath) ? null : Path.Combine(myDocumentsPath, Utils.ModuleDirectory);
-#endif
+            string contentPath = Utils.GetPSContentPath();
+            return string.IsNullOrEmpty(contentPath) ? null : Path.Combine(contentPath, "Modules");
+        }
+
+        /// <summary>
+        /// Gets the legacy personal module path (Documents\PowerShell\Modules).
+        /// This is used for backwards compatibility with PowerShellGet.
+        /// </summary>
+        /// <returns>Legacy personal module path, or null if same as current personal path.</returns>
+        internal static string GetLegacyPersonalModulePath()
+        {
+            string legacyPath = Path.Combine(Platform.LegacyPSContentDirectory, "Modules");
+            string currentPath = GetPersonalModulePath();
+
+            // Only return the legacy path if it's different from the current personal module path
+            if (!string.Equals(legacyPath, currentPath, StringComparison.OrdinalIgnoreCase))
+            {
+                return legacyPath;
+            }
+
+            return null;
         }
 
         /// <summary>
@@ -1348,6 +1362,22 @@ private static string SetModulePath()
 #endif
             string allUsersModulePath = PowerShellConfig.Instance.GetModulePath(ConfigScope.AllUsers);
             string personalModulePath = PowerShellConfig.Instance.GetModulePath(ConfigScope.CurrentUser);
+
+            // If no user-configured module path, use the PSContentPath-based personal module path
+            // and include the legacy Documents module path for backwards compatibility with PowerShellGet.
+            // This ensures both old (Documents) and new (PSContentPath) module locations are searched.
+            if (string.IsNullOrEmpty(personalModulePath))
+            {
+                personalModulePath = GetPersonalModulePath();
+                string legacyModulePath = GetLegacyPersonalModulePath();
+
+                if (!string.IsNullOrEmpty(legacyModulePath) && !string.IsNullOrEmpty(personalModulePath))
+                {
+                    // Combine personal path with legacy path (personal takes precedence)
+                    personalModulePath = string.Concat(personalModulePath, Path.PathSeparator, legacyModulePath);
+                }
+            }
+
             string newModulePathString = GetModulePath(currentModulePath, allUsersModulePath, personalModulePath);
 
             if (!string.IsNullOrEmpty(newModulePathString))