Add pathMappings option to debugger (#2251)

Adds the `pathMappings` option to the debugger that can be used to map a
local to remote path and vice versa. This is useful if the local
environment has a checkout of the files being run on a remote target but
at a different path. The mappings are used to translate the paths that
will the breakpoint will be set to in the target PowerShell instance. It
is also used to update the stack trace paths received from the remote.

Author: jborean93

module/PowerShellEditorServices/Commands/Public/Start-DebugAttachSession.ps1

@@ -43,6 +43,10 @@ function Start-DebugAttachSession {
         [string]
         $WindowActionOnEnd,
 
+        [Parameter()]
+        [IDictionary[]]
+        $PathMapping,
+
         [Parameter()]
         [switch]
         $AsJob
@@ -110,11 +114,21 @@ function Start-DebugAttachSession {
                 return
             }
 
-            $configuration.name = "Attach Process $ProcessId"
+            if ($Name) {
+                $configuration.name = $Name
+            }
+            else {
+                $configuration.name = "Attach Process $ProcessId"
+            }
             $configuration.processId = $ProcessId
         }
         elseif ($CustomPipeName) {
-            $configuration.name = "Attach Pipe $CustomPipeName"
+            if ($Name) {
+                $configuration.name = $Name
+            }
+            else {
+                $configuration.name = "Attach Pipe $CustomPipeName"
+            }
             $configuration.customPipeName = $CustomPipeName
         }
         else {
@@ -136,6 +150,10 @@ function Start-DebugAttachSession {
             $configuration.temporaryConsoleWindowActionOnDebugEnd = $WindowActionOnEnd.ToLowerInvariant()
         }
 
+        if ($PathMapping) {
+            $configuration.pathMappings = $PathMapping
+        }
+
         # https://microsoft.github.io/debug-adapter-protocol/specification#Reverse_Requests_StartDebugging
         $resp = $debugServer.SendRequest(
             'startDebugging',

module/docs/Start-DebugAttachSession.md

@@ -16,14 +16,15 @@ Starts a new debug session attached to the specified PowerShell instance.
 ### ProcessId (Default)
 ```
 Start-DebugAttachSession [-Name <String>] [-ProcessId <Int32>] [-RunspaceName <String>] [-RunspaceId <Int32>]
- [-ComputerName <String>] [-WindowActionOnEnd {Close | Hide | Keep}] [-AsJob] [<CommonParameters>]
+ [-ComputerName <String>] [-WindowActionOnEnd {Close | Hide | Keep}] [-PathMapping <IDictionary[]>] [-AsJob]
+ [<CommonParameters>]
 ```
 
 ### CustomPipeName
 ```
 Start-DebugAttachSession [-Name <String>] [-CustomPipeName <String>] [-RunspaceName <String>]
- [-RunspaceId <Int32>] [-ComputerName <String>] [-WindowActionOnEnd {Close | Hide | Keep}] [-AsJob]
- [<CommonParameters>]
+ [-RunspaceId <Int32>] [-ComputerName <String>] [-WindowActionOnEnd {Close | Hide | Keep}]
+ [-PathMapping <IDictionary[]>] [-AsJob] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -75,6 +76,27 @@ Write-Host "Test $a - $PID"
 
 Launches a new PowerShell process with a custom pipe and starts a new attach configuration that will debug the new process under a child debugging session. The caller waits until the new process ends before ending the parent session.
 
+### -------------------------- EXAMPLE 2 --------------------------
+
+```powershell
+$attachParams = @{
+    ComputerName = 'remote-windows'
+    ProcessId = $remotePid
+    RunspaceId = 1
+    PathMapping = @(
+        @{
+            localRoot = 'C:\local\path\to\scripts\'
+            remoteRoot = 'C:\remote\path\on\remote-windows\'
+        }
+    )
+}
+Start-DebugAttachSession @attachParams
+```
+
+Attaches to a remote PSSession through the WSMan parameter and maps the remote path running the script in the PSSession to the same copy of files locally. For example `remote-windows` is running the script `C:\remote\path\on\remote-windows\script.ps1` but the same script(s) are located locally on the current host `C:\local\path\to\scripts\script.ps1`.
+
+The debug client can see the remote files as local when setting breakpoints and inspecting the callstack with this mapped path.
+
 ## PARAMETERS
 
 ### -AsJob
@@ -143,6 +165,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -PathMapping
+
+An array of dictionaries with the keys `localRoot` and `remoteRoot` that maps a local and remote path root to each other. This option is useful when attaching to a PSSession running a script that is not accessible locally but can be found under a different path.
+
+It is a good idea to ensure the `localRoot` and `remoteRoot` entries are either the absolute path to a script or ends with the trailing directory separator if specifying a directory. A path can also be mapped from a Windows and non-Windows path, just ensure the correct directory separators are used for each OS type. For example `/` for non-Windows and `\` for Windows.
+
+```yaml
+Type: IDictionary[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -ProcessId
 
 The ID of the PowerShell host process that should be attached. This option is mutually exclusive with `-CustomPipeName`.

src/PowerShellEditorServices/Services/DebugAdapter/BreakpointService.cs

@@ -195,7 +195,7 @@ public async Task<IReadOnlyList<BreakpointDetails>> SetBreakpointsAsync(IReadOnl
                 // path which may or may not exist.
                 psCommand
                     .AddScript(_setPSBreakpointLegacy, useLocalScope: true)
-                    .AddParameter("Script", breakpoint.Source)
+                    .AddParameter("Script", breakpoint.MappedSource ?? breakpoint.Source)
                     .AddParameter("Line", breakpoint.LineNumber);
 
                 // Check if the user has specified the column number for the breakpoint.
@@ -219,7 +219,16 @@ public async Task<IReadOnlyList<BreakpointDetails>> SetBreakpointsAsync(IReadOnl
                 IEnumerable<Breakpoint> setBreakpoints = await _executionService
                     .ExecutePSCommandAsync<Breakpoint>(psCommand, CancellationToken.None)
                     .ConfigureAwait(false);
-                configuredBreakpoints.AddRange(setBreakpoints.Select((breakpoint) => BreakpointDetails.Create(breakpoint)));
+
+                int bpIdx = 0;
+                foreach (Breakpoint setBp in setBreakpoints)
+                {
+                    BreakpointDetails setBreakpoint = BreakpointDetails.Create(
+                        setBp,
+                        sourceBreakpoint: breakpoints[bpIdx]);
+                    configuredBreakpoints.Add(setBreakpoint);
+                    bpIdx++;
+                }
             }
             return configuredBreakpoints;
         }

src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs

@@ -15,7 +15,6 @@
 using Microsoft.PowerShell.EditorServices.Services.PowerShell.Execution;
 using Microsoft.PowerShell.EditorServices.Services.PowerShell.Host;
 using Microsoft.PowerShell.EditorServices.Services.PowerShell.Utility;
-using Microsoft.PowerShell.EditorServices.Services.TextDocument;
 using Microsoft.PowerShell.EditorServices.Utility;
 
 namespace Microsoft.PowerShell.EditorServices.Services
@@ -87,6 +86,11 @@ public bool IsDebuggingRemoteRunspace
             set => _debugContext.IsDebuggingRemoteRunspace = value;
         }
 
+        /// <summary>
+        /// Gets or sets an array of path mappings for the current debug session.
+        /// </summary>
+        public PathMapping[] PathMappings { get; set; } = [];
+
         #endregion
 
         #region Constructors
@@ -123,22 +127,22 @@ public DebugService(
         /// <summary>
         /// Sets the list of line breakpoints for the current debugging session.
         /// </summary>
-        /// <param name="scriptFile">The ScriptFile in which breakpoints will be set.</param>
+        /// <param name="scriptPath">The path in which breakpoints will be set.</param>
         /// <param name="breakpoints">BreakpointDetails for each breakpoint that will be set.</param>
         /// <param name="clearExisting">If true, causes all existing breakpoints to be cleared before setting new ones.</param>
+        /// <param name="skipRemoteMapping">If true, skips the remote file manager mapping of the script path.</param>
         /// <returns>An awaitable Task that will provide details about the breakpoints that were set.</returns>
         public async Task<IReadOnlyList<BreakpointDetails>> SetLineBreakpointsAsync(
-            ScriptFile scriptFile,
+            string scriptPath,
             IReadOnlyList<BreakpointDetails> breakpoints,
-            bool clearExisting = true)
+            bool clearExisting = true,
+            bool skipRemoteMapping = false)
         {
             DscBreakpointCapability dscBreakpoints = await _debugContext.GetDscBreakpointCapabilityAsync().ConfigureAwait(false);
 
-            string scriptPath = scriptFile.FilePath;
-
             _psesHost.Runspace.ThrowCancelledIfUnusable();
             // Make sure we're using the remote script path
-            if (_psesHost.CurrentRunspace.IsOnRemoteMachine && _remoteFileManager is not null)
+            if (!skipRemoteMapping && _psesHost.CurrentRunspace.IsOnRemoteMachine && _remoteFileManager is not null)
             {
                 if (!_remoteFileManager.IsUnderRemoteTempPath(scriptPath))
                 {
@@ -162,7 +166,7 @@ public async Task<IReadOnlyList<BreakpointDetails>> SetLineBreakpointsAsync(
             {
                 if (clearExisting)
                 {
-                    await _breakpointService.RemoveAllBreakpointsAsync(scriptFile.FilePath).ConfigureAwait(false);
+                    await _breakpointService.RemoveAllBreakpointsAsync(scriptPath).ConfigureAwait(false);
                 }
 
                 return await _breakpointService.SetBreakpointsAsync(breakpoints).ConfigureAwait(false);
@@ -603,6 +607,49 @@ public VariableScope[] GetVariableScopes(int stackFrameId)
             };
         }
 
+        internal bool TryGetMappedLocalPath(string remotePath, out string localPath)
+        {
+            foreach (PathMapping mapping in PathMappings)
+            {
+                if (string.IsNullOrWhiteSpace(mapping.LocalRoot) || string.IsNullOrWhiteSpace(mapping.RemoteRoot))
+                {
+                    // If either path mapping is null, we can't map the path.
+                    continue;
+                }
+
+                if (remotePath.StartsWith(mapping.RemoteRoot, StringComparison.OrdinalIgnoreCase))
+                {
+                    localPath = mapping.LocalRoot + remotePath.Substring(mapping.RemoteRoot.Length);
+                    return true;
+                }
+            }
+
+            localPath = null;
+            return false;
+        }
+
+        internal bool TryGetMappedRemotePath(string localPath, out string remotePath)
+        {
+            foreach (PathMapping mapping in PathMappings)
+            {
+                if (string.IsNullOrWhiteSpace(mapping.LocalRoot) || string.IsNullOrWhiteSpace(mapping.RemoteRoot))
+                {
+                    // If either path mapping is null, we can't map the path.
+                    continue;
+                }
+
+                if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase))
+                {
+                    // If the local path starts with the local path mapping, we can replace it with the remote path.
+                    remotePath = mapping.RemoteRoot + localPath.Substring(mapping.LocalRoot.Length);
+                    return true;
+                }
+            }
+
+            remotePath = null;
+            return false;
+        }
+
         #endregion
 
         #region Private Methods
@@ -873,14 +920,19 @@ private async Task FetchStackFramesAsync(string scriptNameOverride)
                 StackFrameDetails stackFrameDetailsEntry = StackFrameDetails.Create(callStackFrame, autoVariables, commandVariables);
                 string stackFrameScriptPath = stackFrameDetailsEntry.ScriptPath;
 
-                if (scriptNameOverride is not null
-                    && string.Equals(stackFrameScriptPath, StackFrameDetails.NoFileScriptPath))
+                bool isNoScriptPath = string.Equals(stackFrameScriptPath, StackFrameDetails.NoFileScriptPath);
+                if (scriptNameOverride is not null && isNoScriptPath)
                 {
                     stackFrameDetailsEntry.ScriptPath = scriptNameOverride;
                 }
+                else if (TryGetMappedLocalPath(stackFrameScriptPath, out string localMappedPath)
+                    && !isNoScriptPath)
+                {
+                    stackFrameDetailsEntry.ScriptPath = localMappedPath;
+                }
                 else if (_psesHost.CurrentRunspace.IsOnRemoteMachine
                     && _remoteFileManager is not null
-                    && !string.Equals(stackFrameScriptPath, StackFrameDetails.NoFileScriptPath))
+                    && !isNoScriptPath)
                 {
                     stackFrameDetailsEntry.ScriptPath =
                         _remoteFileManager.GetMappedPath(stackFrameScriptPath, _psesHost.CurrentRunspace);
@@ -981,9 +1033,13 @@ await _executionService.ExecutePSCommandAsync<PSObject>(
                 // Begin call stack and variables fetch. We don't need to block here.
                 StackFramesAndVariablesFetched = FetchStackFramesAndVariablesAsync(noScriptName ? localScriptPath : null);
 
+                if (!noScriptName && TryGetMappedLocalPath(e.InvocationInfo.ScriptName, out string mappedLocalPath))
+                {
+                    localScriptPath = mappedLocalPath;
+                }
                 // If this is a remote connection and the debugger stopped at a line
                 // in a script file, get the file contents
-                if (_psesHost.CurrentRunspace.IsOnRemoteMachine
+                else if (_psesHost.CurrentRunspace.IsOnRemoteMachine
                     && _remoteFileManager is not null
                     && !noScriptName)
                 {
@@ -1034,8 +1090,12 @@ private void OnBreakpointUpdated(object sender, BreakpointUpdatedEventArgs e)
             {
                 // TODO: This could be either a path or a script block!
                 string scriptPath = lineBreakpoint.Script;
-                if (_psesHost.CurrentRunspace.IsOnRemoteMachine
-                    && _remoteFileManager is not null)
+                if (TryGetMappedLocalPath(scriptPath, out string mappedLocalPath))
+                {
+                    scriptPath = mappedLocalPath;
+                }
+                else if (_psesHost.CurrentRunspace.IsOnRemoteMachine
+                        && _remoteFileManager is not null)
                 {
                     string mappedPath = _remoteFileManager.GetMappedPath(scriptPath, _psesHost.CurrentRunspace);
 

src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointApiUtils.cs

@@ -136,7 +136,7 @@ public static Breakpoint SetBreakpoint(Debugger debugger, BreakpointDetailsBase
             {
                 BreakpointDetails lineBreakpoint => SetLineBreakpointDelegate(
                     debugger,
-                    lineBreakpoint.Source,
+                    lineBreakpoint.MappedSource ?? lineBreakpoint.Source,
                     lineBreakpoint.LineNumber,
                     lineBreakpoint.ColumnNumber ?? 0,
                     actionScriptBlock,

src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointDetails.cs

@@ -24,6 +24,11 @@ internal sealed class BreakpointDetails : BreakpointDetailsBase
         /// </summary>
         public string Source { get; private set; }
 
+        /// <summary>
+        /// Gets the source where the breakpoint is mapped to, will be null if no mapping exists.  Used only for debug purposes.
+        /// </summary>
+        public string MappedSource { get; private set; }
+
         /// <summary>
         /// Gets the line number at which the breakpoint is set.
         /// </summary>
@@ -50,14 +55,16 @@ private BreakpointDetails()
         /// <param name="condition"></param>
         /// <param name="hitCondition"></param>
         /// <param name="logMessage"></param>
+        /// <param name="mappedSource"></param>
         /// <returns></returns>
         internal static BreakpointDetails Create(
             string source,
             int line,
             int? column = null,
             string condition = null,
             string hitCondition = null,
-            string logMessage = null)
+            string logMessage = null,
+            string mappedSource = null)
         {
             Validate.IsNotNullOrEmptyString(nameof(source), source);
 
@@ -69,7 +76,8 @@ internal static BreakpointDetails Create(
                 ColumnNumber = column,
                 Condition = condition,
                 HitCondition = hitCondition,
-                LogMessage = logMessage
+                LogMessage = logMessage,
+                MappedSource = mappedSource
             };
         }
 
@@ -79,10 +87,12 @@ internal static BreakpointDetails Create(
         /// </summary>
         /// <param name="breakpoint">The Breakpoint instance from which details will be taken.</param>
         /// <param name="updateType">The BreakpointUpdateType to determine if the breakpoint is verified.</param>
+        /// /// <param name="sourceBreakpoint">The breakpoint source from the debug client, if any.</param>
         /// <returns>A new instance of the BreakpointDetails class.</returns>
         internal static BreakpointDetails Create(
             Breakpoint breakpoint,
-            BreakpointUpdateType updateType = BreakpointUpdateType.Set)
+            BreakpointUpdateType updateType = BreakpointUpdateType.Set,
+            BreakpointDetails sourceBreakpoint = null)
         {
             Validate.IsNotNull(nameof(breakpoint), breakpoint);
 
@@ -96,10 +106,11 @@ internal static BreakpointDetails Create(
             {
                 Id = breakpoint.Id,
                 Verified = updateType != BreakpointUpdateType.Disabled,
-                Source = lineBreakpoint.Script,
+                Source = sourceBreakpoint?.MappedSource is not null ? sourceBreakpoint.Source : lineBreakpoint.Script,
                 LineNumber = lineBreakpoint.Line,
                 ColumnNumber = lineBreakpoint.Column,
-                Condition = lineBreakpoint.Action?.ToString()
+                Condition = lineBreakpoint.Action?.ToString(),
+                MappedSource = sourceBreakpoint?.MappedSource,
             };
 
             if (lineBreakpoint.Column > 0)