Expose pathMappings to Start-DebugAttachSession and fixup Name

Author: jborean93

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

@@ -38,6 +38,10 @@ function Start-DebugAttachSession {
         [string]
         $ComputerName,
 
+        [Parameter()]
+        [IDictionary[]]
+        $PathMapping,
+
         [Parameter()]
         [switch]
         $AsJob
@@ -105,11 +109,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 {
@@ -127,6 +141,10 @@ function Start-DebugAttachSession {
             $configuration.runspaceName = $RunspaceName
         }
 
+        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,13 +16,14 @@ 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>] [-AsJob] [<CommonParameters>]
+ [-ComputerName <String>] [-PathMapping <IDictionary[]>] [-AsJob] [<CommonParameters>]
 ```
 
 ### CustomPipeName
 ```
 Start-DebugAttachSession [-Name <String>] [-CustomPipeName <String>] [-RunspaceName <String>]
- [-RunspaceId <Int32>] [-ComputerName <String>] [-AsJob] [<CommonParameters>]
+ [-RunspaceId <Int32>] [-ComputerName <String>] [-PathMapping <IDictionary[]>] [-AsJob]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -74,6 +75,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
@@ -142,6 +164,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`.