Add option for debugging scripts in a temporary Integrated Console

This change enables the user to configure their debugging sessions to
launch a temporary Integrated Console each time they start the debugger.
This is useful when debugging scripts or modules which use PowerShell
classes or managed assemblies which cannot be reloaded within the same
process.

Resolves #367.

Author: daviwil

examples/.vscode/launch.json

@@ -9,6 +9,15 @@
             "args": [],
             "cwd": "${file}"
         },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch Current File in Temporary Console",
+            "script": "${file}",
+            "args": [],
+            "cwd": "${file}",
+            "createTemporaryIntegratedConsole": true
+        },
         {
             "type": "PowerShell",
             "request": "launch",

package.json

@@ -211,6 +211,19 @@
               "cwd": "^\"\\${file}\""
             }
           },
+          {
+            "label": "PowerShell: Launch Current File in Temporary Console",
+            "description": "Launch current file (in active editor window) under debugger in a temporary Integrated Console.",
+            "body": {
+              "type": "PowerShell",
+              "request": "launch",
+              "name": "PowerShell Launch Current File in Temporary Console",
+              "script": "^\"\\${file}\"",
+              "args": [],
+              "cwd": "^\"\\${file}\"",
+              "createTemporaryIntegratedConsole": true
+            }
+          },
           {
             "label": "PowerShell: Launch - Current File w/Args Prompt",
             "description": "Launch current file (in active editor window) under debugger, prompting first for script arguments",
@@ -292,6 +305,11 @@
                 "type": "string",
                 "description": "Absolute path to the working directory. Default is the current workspace.",
                 "default": "${workspaceRoot}"
+              },
+              "createTemporaryIntegratedConsole": {
+                "type": "boolean",
+                "description": "Determines whether a temporary PowerShell Integrated Console is created for each debugging session, useful for debugging PowerShell classes and binary modules.  Overrides the user setting 'powershell.debugging.createTemporaryIntegratedConsole'.",
+                "default": false
               }
             }
           },
@@ -323,6 +341,15 @@
             "args": [],
             "cwd": "${file}"
           },
+          {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch Current File in Temporary Console",
+            "script": "${file}",
+            "args": [],
+            "cwd": "${file}",
+            "createTemporaryIntegratedConsole": true
+          },
           {
             "type": "PowerShell",
             "request": "launch",
@@ -448,6 +475,11 @@
           "default": true,
           "description": "Switches focus to the console when a script selection is run or a script file is debugged. This is an accessibility feature. To disable it, set to false."
         },
+        "powershell.debugging.createTemporaryIntegratedConsole": {
+          "type": "boolean",
+          "default": false,
+          "description": "Determines whether a temporary PowerShell Integrated Console is created for each debugging session, useful for debugging PowerShell classes and binary modules."
+        },
         "powershell.developer.bundledModulesPath": {
           "type": "string",
           "description": "Specifies an alternate path to the folder containing modules that are bundled with the PowerShell extension (i.e. PowerShell Editor Services, PSScriptAnalyzer, Plaster)"

scripts/Start-EditorServices.ps1

@@ -55,7 +55,7 @@ param(
     [switch]
     $EnableConsoleRepl,
 
-    [string]
+    [switch]
     $DebugServiceOnly,
 
     [string[]]

src/features/DebugSession.ts

@@ -4,6 +4,7 @@
 
 import vscode = require('vscode');
 import utils = require('../utils');
+import Settings = require('../settings');
 import { IFeature } from '../feature';
 import { SessionManager } from '../session';
 import { LanguageClient, RequestType, NotificationType } from 'vscode-languageclient';
@@ -13,6 +14,8 @@ export namespace StartDebuggerNotification {
 }
 
 export class DebugSessionFeature implements IFeature {
+
+    private sessionCount: number = 1;
     private command: vscode.Disposable;
     private examplesPath: string;
 
@@ -42,6 +45,9 @@ export class DebugSessionFeature implements IFeature {
         let debugCurrentScript = (config.script === "${file}") || !config.request;
         let generateLaunchConfig = !config.request;
 
+        var settings = Settings.load();
+        let createNewIntegratedConsole = settings.debugging.createTemporaryIntegratedConsole;
+
         if (generateLaunchConfig) {
             // No launch.json, create the default configuration for both unsaved (Untitled) and saved documents.
             config.type = 'PowerShell';
@@ -106,20 +112,50 @@ export class DebugSessionFeature implements IFeature {
                     }
                 }
             }
+
+            if (config.createTemporaryIntegratedConsole !== undefined) {
+                createNewIntegratedConsole = config.createTemporaryIntegratedConsole;
+            }
         }
 
         // Prevent the Debug Console from opening
         config.internalConsoleOptions = "neverOpen";
 
         // Create or show the interactive console
-        // TODO #367: Check if "newSession" mode is configured
         vscode.commands.executeCommand('PowerShell.ShowSessionConsole', true);
 
-        // Write out temporary debug session file
-        utils.writeSessionFile(
-            utils.getDebugSessionFilePath(),
-            this.sessionManager.getSessionDetails());
+        var sessionFilePath = utils.getDebugSessionFilePath();
+
+        if (createNewIntegratedConsole) {
+            var debugProcess =
+                this.sessionManager.createDebugSessionProcess(
+                    sessionFilePath,
+                    settings);
+
+            debugProcess
+                .start(`DebugSession-${this.sessionCount++}`)
+                .then(
+                    sessionDetails => {
+                        this.startDebugger(
+                            config,
+                            sessionFilePath,
+                            sessionDetails);
+                    });
+        }
+        else {
+            this.startDebugger(
+                config,
+                sessionFilePath,
+                this.sessionManager.getSessionDetails());
+        }
+    }
+
+    private startDebugger(
+        config: any,
+        sessionFilePath: string,
+        sessionDetails: utils.EditorServicesSessionDetails) {
 
+        utils.writeSessionFile(sessionFilePath, sessionDetails);
         vscode.commands.executeCommand('vscode.startDebug', config);
     }
 }

src/process.ts

@@ -15,7 +15,6 @@ import { Logger } from './logging';
 
 export class PowerShellProcess {
 
-    private sessionFilePath: string;
     private consoleTerminal: vscode.Terminal = undefined;
     private consoleCloseSubscription: vscode.Disposable;
     private sessionDetails: utils.EditorServicesSessionDetails;
@@ -25,15 +24,14 @@ export class PowerShellProcess {
 
     constructor(
         public exePath: string,
+        private title: string,
         private log: Logger,
+        private startArgs: string,
+        private sessionFilePath: string,
         private sessionSettings: Settings.ISettings) {
-
-        this.sessionFilePath =
-            utils.getSessionFilePath(
-                Math.floor(100000 + Math.random() * 900000));
     }
 
-    public start(startArgs: string): Thenable<utils.EditorServicesSessionDetails> {
+    public start(logFileName: string): Thenable<utils.EditorServicesSessionDetails> {
 
         return new Promise<utils.EditorServicesSessionDetails>(
             (resolve, reject) => {
@@ -44,14 +42,14 @@ export class PowerShellProcess {
                             __dirname,
                             '../scripts/Start-EditorServices.ps1');
 
-                    var editorServicesLogPath = this.log.getLogFilePath("EditorServices");
+                    var editorServicesLogPath = this.log.getLogFilePath(logFileName);
 
                     var featureFlags =
                         this.sessionSettings.developer.featureFlags !== undefined
                             ? this.sessionSettings.developer.featureFlags.map(f => `'${f}'`).join(', ')
                             : "";
 
-                    startArgs +=
+                    this.startArgs +=
                         `-LogPath '${editorServicesLogPath}' ` +
                         `-SessionDetailsPath '${this.sessionFilePath}' ` +
                         `-FeatureFlags @(${featureFlags})`
@@ -68,7 +66,7 @@ export class PowerShellProcess {
 
                     powerShellArgs.push(
                         "-Command",
-                        "& '" + startScriptPath + "' " + startArgs);
+                        "& '" + startScriptPath + "' " + this.startArgs);
 
                     var powerShellExePath = this.exePath;
 
@@ -95,7 +93,7 @@ export class PowerShellProcess {
                     // Launch PowerShell in the integrated terminal
                     this.consoleTerminal =
                         vscode.window.createTerminal(
-                            "PowerShell Integrated Console",
+                            this.title,
                             powerShellExePath,
                             powerShellArgs);
 
@@ -148,7 +146,7 @@ export class PowerShellProcess {
                             "powershell.exe started --",
                             "    pid: " + pid,
                             "    exe: " + powerShellExePath,
-                            "    args: " + startScriptPath + ' ' + startArgs + os.EOL + os.EOL);
+                            "    args: " + startScriptPath + ' ' + this.startArgs + os.EOL + os.EOL);
                     });
             }
             catch (e)

src/session.ts

@@ -36,13 +36,15 @@ export class SessionManager implements Middleware {
 
     private hostVersion: string;
     private isWindowsOS: boolean;
+    private editorServicesArgs: string;
     private powerShellExePath: string = "";
     private sessionStatus: SessionStatus;
     private suppressRestartPrompt: boolean;
     private focusConsoleOnExecute: boolean;
     private extensionFeatures: IFeature[] = [];
     private statusBarItem: vscode.StatusBarItem;
-    private powerShellProcess: PowerShellProcess;
+    private languageServerProcess: PowerShellProcess;
+    private debugSessionProcess: PowerShellProcess;
     private versionDetails: PowerShellVersionDetails;
     private registeredCommands: vscode.Disposable[] = [];
     private languageServerClient: LanguageClient = undefined;
@@ -139,7 +141,7 @@ export class SessionManager implements Middleware {
                 }
             }
 
-            var startArgs =
+            this.editorServicesArgs =
                 "-EditorServicesVersion '" + this.requiredEditorServicesVersion + "' " +
                 "-HostName 'Visual Studio Code Host' " +
                 "-HostProfileId 'Microsoft.VSCode' " +
@@ -149,17 +151,17 @@ export class SessionManager implements Middleware {
                 "-EnableConsoleRepl ";
 
             if (this.sessionSettings.developer.editorServicesWaitForDebugger) {
-                startArgs += '-WaitForDebugger ';
+                this.editorServicesArgs += '-WaitForDebugger ';
             }
             if (this.sessionSettings.developer.editorServicesLogLevel) {
-                startArgs += "-LogLevel '" + this.sessionSettings.developer.editorServicesLogLevel + "' "
+                this.editorServicesArgs += "-LogLevel '" + this.sessionSettings.developer.editorServicesLogLevel + "' "
             }
 
             this.startPowerShell(
                 this.powerShellExePath,
                 this.sessionSettings.developer.powerShellExeIsWindowsDevBuild,
                 bundledModulesPath,
-                startArgs);
+                this.editorServicesArgs);
         }
         else {
             this.setSessionFailure("PowerShell could not be started, click 'Show Logs' for more details.");
@@ -175,7 +177,7 @@ export class SessionManager implements Middleware {
             // Before moving further, clear out the client and process if
             // the process is already dead (i.e. it crashed)
             this.languageServerClient = undefined;
-            this.powerShellProcess = undefined;
+            this.languageServerProcess = undefined;
         }
 
         this.sessionStatus = SessionStatus.Stopping;
@@ -186,9 +188,12 @@ export class SessionManager implements Middleware {
             this.languageServerClient = undefined;
         }
 
-        // Kill the PowerShell process we spawned
-        if (this.powerShellProcess) {
-            this.powerShellProcess.dispose();
+        // Kill the PowerShell proceses we spawned
+        if (this.debugSessionProcess) {
+            this.debugSessionProcess.dispose();
+        }
+        if (this.languageServerProcess) {
+            this.languageServerProcess.dispose();
         }
 
         this.sessionStatus = SessionStatus.NotStarted;
@@ -206,6 +211,22 @@ export class SessionManager implements Middleware {
         this.registeredCommands.forEach(command => { command.dispose(); });
     }
 
+    public createDebugSessionProcess(
+        sessionPath: string,
+        sessionSettings: Settings.ISettings): PowerShellProcess {
+
+        this.debugSessionProcess =
+            new PowerShellProcess(
+                this.powerShellExePath,
+                "[DBG] PowerShell Integrated Console",
+                this.log,
+                this.editorServicesArgs + "-DebugServiceOnly ",
+                sessionPath,
+                sessionSettings);
+
+        return this.debugSessionProcess;
+    }
+
     private onConfigurationUpdated() {
         var settings = Settings.load();
 
@@ -266,22 +287,29 @@ export class SessionManager implements Middleware {
             "Starting PowerShell...",
             SessionStatus.Initializing);
 
-        this.powerShellProcess =
+        var sessionFilePath =
+            utils.getSessionFilePath(
+                Math.floor(100000 + Math.random() * 900000));
+
+        this.languageServerProcess =
             new PowerShellProcess(
                 this.powerShellExePath,
+                "PowerShell Integrated Console",
                 this.log,
+                startArgs,
+                sessionFilePath,
                 this.sessionSettings);
 
-        this.powerShellProcess.onExited(
+        this.languageServerProcess.onExited(
             () => {
                 if (this.sessionStatus === SessionStatus.Running) {
                     this.setSessionStatus("Session exited", SessionStatus.Failed);
                     this.promptForRestart();
                 }
             });
 
-        this.powerShellProcess
-            .start(startArgs)
+        this.languageServerProcess
+            .start("EditorServices")
             .then(
                 sessionDetails => {
                     this.sessionDetails = sessionDetails;
@@ -612,8 +640,8 @@ export class SessionManager implements Middleware {
     }
 
     private showSessionConsole(isExecute?: boolean) {
-        if (this.powerShellProcess) {
-            this.powerShellProcess.showConsole(
+        if (this.languageServerProcess) {
+            this.languageServerProcess.showConsole(
                 isExecute && !this.focusConsoleOnExecute);
         }
     }