🚧 This extension is in early development. Please report any issues. 🚧

.NET Stalker Debugger

3-in-1 ASP.NET (5+ and Core) debugger for Visual Studio Code

(Replaces default debugger in launch configurations in launch.json)

.NET Stalker Debugger

🛠️ Typical Dev Stack

Full-stack development. Backend of a C# ASP.NET Web App/API project and front-end client-side HTML, CSS, JavaScript (transpiled from TypeScript), etc.

🔥 Active Hot Reloads and Transpiles

Actively "hot reload" backend changes and "hot transpile" front-end changes (TypeScript to JavaScript).

🪲 Dual-Debugging

Debugging of backend and front-end (using Google Chrome's developer tool) both within Visual Studio Code simultaneously.

🚀 Continuous Re-Attaching

Automatically re-attaches to the project's new process (on "hot reload" builds).

🚫 No need to manually stop, re-attach or restart debuggers or run multiple tasks 🚫

🎉 All in a single debug session within Visual Studio Code 🎉

.NET Stalker Debugger: VS Code debug console output

Backend: C#/.NET breakpoint in VS Code

Front-end: TypeScript breakpoint in VS Code (though running transpiled as JavaScript on client-side)

Launch configuration snippets available in launch.json

Table of Contents

• Primary Three Features
  • Phases and Tooling
• Requirements
• Launch Configurations
  • Properties
  • Examples
• Client-Side JavaScript/TypeScript Debugging
  • Google Chrome
  • Node.js
  • Node Package Dependencies
  • TypeScript, ESLint and Webpack Configuration Files
  • Launch Configuration Modifications
• Extension Settings
• Known Issues
• Release Notes / Changelog

Primary Three Features

The three primary features of .NET Stalker Debugger.

1. 🛠️ BUILD — Build and run project
   • Lint JavaScript and TypeScript files
   • Transpile TypeScript to JavaScript for client-side use
   • Build and run the .NET project
2. 🪲 DEBUG — Debug both backend and front-end
   • Attach to the .NET project process for backend debugging
   • Debug with Google Chrome's developer tools for client-side debugging
3. ⌚️ WATCH — Watch for changes
   • Watch TypeScript files to "hot transpile" to JavaScript when needed
   • Watch .NET project files to perform "hot reloads" when possible
   • Rebuild and re-attach to project's new process when a "hot reload" build is needed

Phases and Tooling

Logical order of phases within the three primary features.

Misc Screen Shots

.NET Stalker Debugger: VS Code debugger call stack

JavaScript/TypeScript debug console in VS Code

Requirements

• macOS, possibly Linux (not yet Windows)
• .NET SDK 6.0 or later
• Visual Studio Code 1.80.0 or later
• Visual Studio Code extensions C# and C# Dev Kit
• Google Chrome
• Node.js

Launch Configurations

Properties

Type attachOptions Properties

Options for attaching to child process started by .NET Watch.

Type buildOptions Properties

Options relating to building.

Type preBuildTask Properties

Type processOptions Properties

Options for child process started by .NET Watch.

Type watchOptions Properties

Options for .NET Watch.

If the browser is not refreshing on detected changes, see the usePollingFileWatcher property and dotnet-watch browser refresh.

See dotnet-watch configuration for more information on some of these watch options.

Examples

Minimum launch configuration

{
    "name": ".NET Stalker",
    "type": "stalker",
    "request": "launch",
    "project": "${workspaceFolder}/src/MyWebApp/MyWebApp.csproj",
    "process": "${workspaceFolder}/src/MyWebApp/bin/Debug/net8.0/MyWebApp",
    "cwd": "${workspaceFolder}/src/MyWebApp",
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development"
    }
}

Minimum launch configuration with specific URL and use of variables

{
    "name": ".NET Stalker",
    "type": "stalker",
    "request": "launch",
    "vars": {
        "framework": "net8.0",
        "projectDir": "${workspaceFolder}/src/${var:projectName}",
        "projectName": "MyWebApp"
    },
    "project": "${var:projectDir}/${var:projectName}.csproj",
    "process": "${var:projectDir}/bin/Debug/${var:framework}/${var:projectName}",
    "cwd": "${var:projectDir}",
    "url": "http://localhost:8080",
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development"
    }
}

Full launch configuration with ESLint, Webpack (watch mode) and Google Chrome client-side debugging

{
    "name": ".NET Stalker (Full)",
    "type": "stalker",
    "request": "launch",
    "vars": {
        "framework": "net8.0",
        "projectDir": "${workspaceFolder}/src/${var:projectName}",
        "projectName": "<PROJECTNAME>"
    },
    "project": "${var:projectDir}/${var:projectName}.csproj",
    "process": "${var:projectDir}/bin/Debug/${var:framework}/${var:projectName}",
    "cwd": "${var:projectDir}",
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "NODE_ENV": "development"
    },
    "url": "http://localhost:5001",
    "webRoot": "${var:projectDir}/wwwroot",
    "buildOptions": {
        "preBuildTasks": [
            {
                "name": "ESLint",
                "commandLine": "npx eslint --ext .ts --color ./scripts",
                "isBackground": false,
                "waitFor": true,
                "failOnNonZeroExitCode": true
            },
            {
                "name": "Webpack",
                "commandLine": "npx webpack --watch --node-env ${env:NODE_ENV} --mode ${env:NODE_ENV} -d source-map --color",
                "isBackground": false,
                "waitFor": false,
                "failOnNonZeroExitCode": true
            }
        ]
    },
    "attachOptions": {
        "action": "debugWithChrome"
    }
}

Client-Side JavaScript/TypeScript Debugging

For .NET Stalker Debugger to support client-side JavaScript/TypeScript debugging (i.e. hit breakpoints within Visual Studio Code), some configuration is needed.

While there are many ways to configure a project for client-side debugging, this section provides an example setup using both ESLint and Webpack. You're free to use any other configuration that suits your needs.

Requirements:

1. Google Chrome
2. Node.js
3. Node package dependencies
4. TypeScript, ESLint and Webpack configuration files
5. .NET Stalker Debugger launch configuration modifications

Note that client-side debugging is not required for .NET Stalker Debugger to work. It is only needed if you want to debug client-side code within Visual Studio Code. Also, use of TypeScript (and Webpack) is not required for client-side debugging, but it is used in this example.

Google Chrome

See Google Chrome for installation.

Node.js

See Node.js for installation.

Node Package Dependencies

In the project directory (i.e. ${workspaceFolder}/src/(projectName)), run:

npm i --save-dev @types/glob @types/node @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint path ts-loader ts-node typescript webpack webpack-cli

TypeScript, ESLint and Webpack Configuration Files

TypeScript File

An noteworthy values here is compilerOptions.outDir which is referenced by the Webpack configuration.

${workspaceFolder}/src/(projectName)/tsconfig.json

{
    "compilerOptions": {
        "noEmitOnError": true,
        "noImplicitAny": true,
        "sourceMap": true,
        "outDir": "wwwroot/js",
        "esModuleInterop": true,
        "target": "ESNext",
        "module": "commonjs",
        "allowJs": true,
        "checkJs": true,
        "types": ["node"]
    },
    "exclude": ["./node_modules", "./wwwroot"],
    "include": ["**/*.ts"],
    "compileOnSave": true
}

ESLint Files

${workspaceFolder}/src/(projectName)/.eslintrc

{
    "root": true,
    "parser": "@typescript-eslint/parser",
    "plugins": ["@typescript-eslint"],
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/eslint-recommended",
        "plugin:@typescript-eslint/recommended"
    ],
    "rules": {}
}

${workspaceFolder}/src/(projectName)/.eslintignore

**/node_modules/*
**/webpack.config.ts
**/wwwroot/js/*

Webpack File

Two noteworthy values here are entry and output.path which are used to transpile TypeScript files in directory ./script to JavaScript to the wwwroot/js directory.

${workspaceFolder}/src/(projectName)/webpack.config.ts

import glob from "glob";
import { resolve } from "path";
import { Configuration } from "webpack";

const config: Configuration = {
    entry: glob.sync("./scripts/**/*.ts").reduce((entries, path) => {
        const entry = path.replace("./scripts/", "").replace(".ts", "");
        entries[entry] = path;
        return entries;
    }, {} as { [key: string]: string }),
    output: {
        path: resolve(__dirname, "wwwroot/js"),
        filename: "[name].js",
        devtoolModuleFilenameTemplate: "[absolute-resource-path]",
    },
    devtool: "source-map",
    target: "web",
    resolve: {
        extensions: [".ts", ".js"],
    },
    module: {
        rules: [
            {
                test: /\.ts$/,
                use: "ts-loader",
            },
        ],
    },
};

export default config;

Launch Configuration Modifications

Before starting the .NET Stalker Debugger, pre-build tasks are needed to:

1. (Optionally) Run ESLint
2. (Required) Use Webpack to transpile TypeScript files to JavaScript to the wwwroot/js directory

Important: Pre-build tasks are executed in the order they are defined. Ensure ESLint is run before Webpack.

Pre-Build Task: ESLint

Editing an existing .NET Stalker Debugger launch configuration, append to root level:

"buildOptions": {
    "preBuildTasks": [
        {
            "name": "ESLint",
            "commandLine": "npx eslint --ext .ts --color ./scripts",
            "isBackground": false,
            "waitFor": true,
            "failOnNonZeroExitCode": true
        }
    ]
}

Pre-Build Task: Webpack

Editing an existing .NET Stalker Debugger launch configuration, append to root level:

"env": {
    "NODE_ENV": "development"
}

As well as:

"buildOptions": {
    "preBuildTasks": [
        {
            "name": "Webpack",
            "commandLine": "npx webpack --watch --node-env ${env:NODE_ENV} --mode ${env:NODE_ENV} -d source-map --color",
            "isBackground": false,
            "waitFor": false,
            "failOnNonZeroExitCode": true
        }
    ]
}

To disable the Webpack watch mode (i.e. no "hot transpiles" on file changes), do the following:

1. Remove --watch from the commandLine property
2. Set waitFor to true

Extension Settings

There are no global/user extension settings. All settings are configured on a project-level in a launch.json file.

Known Issues

This extension is in early development. Please report any issues.

Release Notes / Changelog

2024-09-09 — 0.0.3

• Fixed configuration snippets.
• Added configuration snippet that includes debugging with Google Chrome.

2024-07-23 — 0.0.2

• Minor grammar correction.
• Minor updates to README.md.

2024-07-23 — 0.0.1

• First public release. Probably buggy. No pun intended.