Support debugging python modules, add flask, uvicorn debugging support, add DCP logging util (#12456)

* add additional launch configurations, dcp logs setting

* add python modules to ide spec, config

* add module example to AspireWithPython

* add file

* make cert serial number generation better

* add AddFlaskApp, add example, get uvicorn debug working

* add uvicorn example, fix flask_app

* add hot reload in development mode for uvicorn

* improve naming

* remove test class

* change 01 -> 00

* instead of AddFlaskApp do AddGunicornApp

* disable vs code gunicorn debug support in prod

* add WithDebugging to note a python resource is debuggable

* fix error

* remove gunicorn stuff, use correct path for Windows python executable

* rename WithVSCodeDebugSupport -> WithDebugSupport

* show errors when resource fails to start

* fix bug where python args were being removed when run within extension but without python extension installed

* add additional tests

* remove ide spec change for now

---------

Co-authored-by: Adam Ratzman <[email protected]>

Author: adamint

.vscode/launch.json

@@ -29,6 +29,39 @@
 			"env": {
 				"ASPIRE_CLI_STOP_ON_ENTRY": "true"
 			},
+      "cwd": "${workspaceFolder}/extension"
+		},
+		{
+			"name": "Run Extension (apphost stop on entry)",
+			"type": "extensionHost",
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}/extension"
+			],
+			"outFiles": [
+				"${workspaceFolder}/extension/dist/**/*.js"
+			],
+			"preLaunchTask": "npm: watch extension",
+			"env": {
+				"ASPIRE_APPHOST_STOP_ON_ENTRY": "true"
+			},
+      "cwd": "${workspaceFolder}/extension"
+		},
+		{
+			"name": "Run Extension (apphost AND cli stop on entry)",
+			"type": "extensionHost",
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}/extension"
+			],
+			"outFiles": [
+				"${workspaceFolder}/extension/dist/**/*.js"
+			],
+			"preLaunchTask": "npm: watch extension",
+			"env": {
+        "ASPIRE_CLI_STOP_ON_ENTRY": "true",
+				"ASPIRE_APPHOST_STOP_ON_ENTRY": "true"
+			},
       "cwd": "${workspaceFolder}/extension"
 		}
 	]

extension/loc/xlf/aspire-vscode.xlf

@@ -199,6 +199,12 @@
           "default": false,
           "description": "%configuration.aspire.enableAspireCliDebugLogging%",
           "scope": "window"
+        },
+        "aspire.enableAspireDcpDebugLogging": {
+          "type": "boolean",
+          "default": false,
+          "description": "%configuration.aspire.enableAspireDcpDebugLogging%",
+          "scope": "window"
         }
       }
     }

extension/package.json

@@ -18,6 +18,7 @@
   "configuration.aspire.enableSettingsFileCreationPromptOnStartup": "Enable apphost discovery on extension activation and prompt to setup .aspire/settings.json.appHostPath if it does not exist in the workspace.",
   "configuration.aspire.aspireCliExecutablePath": "The path to the Aspire CLI executable. If not set, the extension will attempt to use 'aspire' from the system PATH.",
   "configuration.aspire.enableAspireCliDebugLogging": "Enable console debug logging for Aspire CLI commands executed by the extension.",
+  "configuration.aspire.enableAspireDcpDebugLogging": "Enable Developer Control Plane (DCP) debug logging for Aspire applications. Logs will be stored in the workspace's .aspire/dcp/logs-{debugSessionId} folder.",
   "command.runAppHost": "Run Aspire apphost",
 	"command.debugAppHost": "Debug Aspire apphost",
 	"aspire-vscode.strings.noCsprojFound": "No apphost found in the current workspace.",
@@ -76,5 +77,10 @@
   "aspire-vscode.strings.invalidLaunchConfiguration": "Invalid launch configuration for {0}.",
   "aspire-vscode.strings.noAppHostInWorkspace": "No apphost found in the Aspire settings file.",
   "aspire-vscode.strings.dashboard": "Dashboard",
-  "aspire-vscode.strings.codespaces": "Codespaces"
+  "aspire-vscode.strings.codespaces": "Codespaces",
+  "aspire-vscode.strings.encounteredErrorStartingResource": "Encountered an error starting resource: {0}.",
+  "aspire-vscode.strings.invalidOrMissingToken": "Invalid or missing token in Authorization header.",
+  "aspire-vscode.strings.invalidTokenLength": "Invalid token length in Authorization header.",
+  "aspire-vscode.strings.authorizationHeaderMustStartWithBearer": "Authorization header must start with 'Bearer '.",
+  "aspire-vscode.strings.authorizationAndDcpHeadersRequired": "Authorization and Microsoft-Developer-DCP-Instance-ID headers are required."
 }

extension/package.nls.json

@@ -1,13 +1,15 @@
 import express, { Request, Response, NextFunction } from 'express';
 import https from 'https';
 import WebSocket, { WebSocketServer } from 'ws';
+import * as vscode from 'vscode';
 import { createSelfSignedCertAsync, generateToken } from '../utils/security';
 import { extensionLogOutputChannel } from '../utils/logging';
 import { AspireResourceDebugSession, DcpServerConnectionInfo, ErrorDetails, ErrorResponse, ProcessRestartedNotification, RunSessionNotification, RunSessionPayload, ServiceLogsNotification, SessionMessageNotification, SessionTerminatedNotification } from './types';
 import { AspireDebugSession } from '../debugger/AspireDebugSession';
 import { createDebugSessionConfiguration, ResourceDebuggerExtension } from '../debugger/debuggerExtensions';
 import { timingSafeEqual } from 'crypto';
 import { getRunSessionInfo, getSupportedCapabilities } from '../capabilities';
+import { authorizationAndDcpHeadersRequired, authorizationHeaderMustStartWithBearer, encounteredErrorStartingResource, invalidOrMissingToken, invalidTokenLength } from '../loc/strings';
 
 export default class AspireDcpServer {
     private readonly app: express.Express;
@@ -48,26 +50,26 @@ export default class AspireDcpServer {
                 const auth = req.header('Authorization');
                 const dcpId = req.header('microsoft-developer-dcp-instance-id');
                 if (!auth || !dcpId) {
-                    res.status(401).json({ error: { code: 'MissingHeaders', message: 'Authorization and Microsoft-Developer-DCP-Instance-ID headers are required.' } });
+                    respondWithError(res, 401, { error: { code: 'MissingHeaders', message: authorizationAndDcpHeadersRequired, details: [] } });
                     return;
                 }
 
                 if (auth.split('Bearer ').length !== 2) {
-                    res.status(401).json({ error: { code: 'InvalidAuthHeader', message: 'Authorization header must start with "Bearer "' } });
+                    respondWithError(res, 401, { error: { code: 'InvalidAuthHeader', message: authorizationHeaderMustStartWithBearer, details: [] } });
                     return;
                 }
 
                 const bearerTokenBuffer = Buffer.from(auth.split('Bearer ')[1]);
                 const expectedTokenBuffer = Buffer.from(token);
 
                 if (bearerTokenBuffer.length !== expectedTokenBuffer.length) {
-                    res.status(401).json({ error: { code: 'InvalidToken', message: 'Invalid token length in Authorization header.' } });
+                    respondWithError(res, 401, { error: { code: 'InvalidToken', message: invalidTokenLength, details: [] } });
                     return;
                 }
 
                 // timingSafeEqual is used to verify that the tokens are equivalent in a way that mitigates timing attacks
                 if (timingSafeEqual(bearerTokenBuffer, expectedTokenBuffer) === false) {
-                    res.status(401).json({ error: { code: 'InvalidToken', message: 'Invalid or missing token in Authorization header.' } });
+                    respondWithError(res, 401, { error: { code: 'InvalidToken', message: invalidOrMissingToken, details: [] } });
                     return;
                 }
 
@@ -99,7 +101,7 @@ export default class AspireDcpServer {
 
                     extensionLogOutputChannel.error(`Error creating debug session ${runId}: ${error.message}`);
                     const response: ErrorResponse = { error };
-                    res.status(400).json(response).end();
+                    respondWithError(res, 400, response);
                     return;
                 }
 
@@ -115,7 +117,7 @@ export default class AspireDcpServer {
 
                     extensionLogOutputChannel.error(`Error creating debug session ${runId}: ${error.message}`);
                     const response: ErrorResponse = { error };
-                    res.status(400).json(response).end();
+                    respondWithError(res, 400, response);
                     return;
                 }
 
@@ -129,7 +131,7 @@ export default class AspireDcpServer {
 
                     extensionLogOutputChannel.error(`Error creating debug session ${runId}: ${error.message}`);
                     const response: ErrorResponse = { error };
-                    res.status(500).json(response).end();
+                    respondWithError(res, 500, response);
                     return;
                 }
 
@@ -145,7 +147,7 @@ export default class AspireDcpServer {
 
                     extensionLogOutputChannel.error(`Error creating debug session ${runId}: ${error.message}`);
                     const response: ErrorResponse = { error };
-                    res.status(500).json(response).end();
+                    respondWithError(res, 500, response);
                     return;
                 }
 
@@ -311,3 +313,8 @@ function getDcpIdPrefix(dcpId: string): string | null {
 
     return null;
 }
+
+function respondWithError(res: Response, statusCode: number, message: ErrorResponse): void {
+    res.status(statusCode).json(message).end();
+    vscode.window.showErrorMessage(encounteredErrorStartingResource(message.error.message));
+}

extension/src/dcp/AspireDcpServer.ts

@@ -30,8 +30,13 @@ export function isProjectLaunchConfiguration(obj: any): obj is ProjectLaunchConf
 
 export interface PythonLaunchConfiguration extends ExecutableLaunchConfiguration {
     type: "python";
+
+    // legacy fields
+    project_path?: string;
     program_path?: string;
-    project_path?: string; // leftover from 9.5 usage of project path
+
+    module?: string;
+    interpreter_path?: string;
 }
 
 export function isPythonLaunchConfiguration(obj: any): obj is PythonLaunchConfiguration {

extension/src/dcp/types.ts

@@ -82,6 +82,10 @@ export class AspireDebugSession implements vscode.DebugAdapter {
         args.push('--cli-wait-for-debugger');
       }
 
+      if (process.env[EnvironmentVariables.ASPIRE_APPHOST_STOP_ON_ENTRY] === 'true') {
+        args.push('--wait-for-debugger');
+      }
+
       if (isDirectory(appHostPath)) {
         this.sendMessageWithEmoji("📁", launchingWithDirectory(appHostPath));
 

extension/src/debugger/AspireDebugSession.ts

@@ -6,13 +6,14 @@ import { extensionLogOutputChannel } from "../utils/logging";
 import { projectDebuggerExtension } from "./languages/dotnet";
 import { isCsharpInstalled, isPythonInstalled } from "../capabilities";
 import { pythonDebuggerExtension } from "./languages/python";
+import { isDirectory } from "../utils/io";
 
 // Represents a resource-specific debugger extension for when the default session configuration is not sufficient to launch the resource.
 export interface ResourceDebuggerExtension {
     resourceType: string;
     debugAdapter: string;
     extensionId: string | null;
-    displayName: string;
+    getDisplayName: (launchConfig: ExecutableLaunchConfiguration) => string;
     getProjectFile: (launchConfig: ExecutableLaunchConfiguration) => string;
     getSupportedFileTypes: () => string[];
     createDebugSessionConfigurationCallback?: (launchConfig: ExecutableLaunchConfiguration, args: string[] | undefined, env: EnvVar[], launchOptions: LaunchOptions, debugConfiguration: AspireResourceExtendedDebugConfiguration) => Promise<void>;
@@ -24,15 +25,14 @@ export async function createDebugSessionConfiguration(debugSessionConfig: Aspire
     }
 
     const projectPath = debuggerExtension.getProjectFile(launchConfig);
-    const displayName = `${debuggerExtension.displayName ?? launchConfig.type}: ${path.basename(projectPath)}`;
 
     const configuration: AspireResourceExtendedDebugConfiguration = {
         type: debuggerExtension.debugAdapter || launchConfig.type,
         request: 'launch',
-        name: launchOptions.debug ? debugProject(displayName) : runProject(displayName),
+        name: launchOptions.debug ? debugProject(debuggerExtension.getDisplayName(launchConfig)) : runProject(debuggerExtension.getDisplayName(launchConfig)),
         program: projectPath,
         args: args,
-        cwd: path.dirname(projectPath),
+        cwd: await isDirectory(projectPath) ? projectPath : path.dirname(projectPath),
         env: mergeEnvs(process.env, env),
         justMyCode: false,
         stopAtEntry: false,

extension/src/debugger/debuggerExtensions.ts

@@ -7,7 +7,7 @@ import * as path from 'path';
 import * as readline from 'readline';
 import * as os from 'os';
 import { doesFileExist } from '../../utils/io';
-import { AspireResourceExtendedDebugConfiguration, isProjectLaunchConfiguration } from '../../dcp/types';
+import { AspireResourceExtendedDebugConfiguration, ExecutableLaunchConfiguration, isProjectLaunchConfiguration, ProjectLaunchConfiguration } from '../../dcp/types';
 import { ResourceDebuggerExtension } from '../debuggerExtensions';
 import {
     readLaunchSettings,
@@ -184,7 +184,7 @@ export function createProjectDebuggerExtension(dotNetService: IDotNetService): R
         resourceType: 'project',
         debugAdapter: 'coreclr',
         extensionId: 'ms-dotnettools.csharp',
-        displayName: 'C#',
+        getDisplayName: (launchConfig: ExecutableLaunchConfiguration) => `C#: ${path.basename((launchConfig as ProjectLaunchConfiguration).project_path)}`,
         getSupportedFileTypes: () => ['.cs', '.csproj'],
         getProjectFile: (launchConfig) => {
             if (isProjectLaunchConfiguration(launchConfig)) {

extension/src/debugger/languages/dotnet.ts

@@ -1,21 +1,44 @@
-import { isPythonLaunchConfiguration } from "../../dcp/types";
+import { AspireResourceExtendedDebugConfiguration, ExecutableLaunchConfiguration, isPythonLaunchConfiguration } from "../../dcp/types";
 import { invalidLaunchConfiguration } from "../../loc/strings";
+import { extensionLogOutputChannel } from "../../utils/logging";
 import { ResourceDebuggerExtension } from "../debuggerExtensions";
+import * as vscode from 'vscode';
+
+function getProjectFile(launchConfig: ExecutableLaunchConfiguration): string {
+    if (isPythonLaunchConfiguration(launchConfig)) {
+        const programPath = launchConfig.program_path || launchConfig.project_path;
+        if (programPath) {
+            return programPath;
+        }
+    }
+
+    throw new Error(invalidLaunchConfiguration(JSON.stringify(launchConfig)));
+}
 
 export const pythonDebuggerExtension: ResourceDebuggerExtension = {
     resourceType: 'python',
     debugAdapter: 'debugpy',
     extensionId: 'ms-python.python',
-    displayName: 'Python',
+    getDisplayName: (launchConfiguration: ExecutableLaunchConfiguration) => `Python: ${vscode.workspace.asRelativePath(getProjectFile(launchConfiguration))}`,
     getSupportedFileTypes: () => ['.py'],
-    getProjectFile: (launchConfig) => {
-        if (isPythonLaunchConfiguration(launchConfig)) {
-            const programPath = launchConfig.program_path || launchConfig.project_path;
-            if (programPath) {
-                return programPath;
-            }
+    getProjectFile: (launchConfig) => getProjectFile(launchConfig),
+    createDebugSessionConfigurationCallback: async (launchConfig, args, env, launchOptions, debugConfiguration: AspireResourceExtendedDebugConfiguration): Promise<void> => {
+        if (!isPythonLaunchConfiguration(launchConfig)) {
+            extensionLogOutputChannel.info(`The resource type was not python for ${JSON.stringify(launchConfig)}`);
+            throw new Error(invalidLaunchConfiguration(JSON.stringify(launchConfig)));
         }
 
-        throw new Error(invalidLaunchConfiguration(JSON.stringify(launchConfig)));
+        if (launchConfig.interpreter_path) {
+            debugConfiguration.python = launchConfig.interpreter_path;
+        }
+
+        // By default, activate support for Jinja debugging
+        debugConfiguration.jinja = true;
+
+        // If module is specified, remove program from the debug configuration
+        if (!!launchConfig.module) {
+            delete debugConfiguration.program;
+            debugConfiguration.module = launchConfig.module;
+        }
     }
 };