C# .NET Stalker Debugger

All-in-One C# .NET (5+ and Core) and JavaScript/TypeScript Debugger

Use this debugger, instead of dotnet/coreclr, in launch configurations in launch.json. It provides the same debugging experience plus additional functionality all in a single debug session.

.NET Stalker Debugger: VS Code debug console output

Primary Features

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

There are 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 session connects with Google Chrome, Mozilla Firefox or Microsoft Edge remote debugger for client-side debugging
3. ⌚️ WATCH-RELOAD/REBUILD-REATTACH — Watch for changes
   • Watch TypeScript files to "hot transpile" to JavaScript when needed
   • Watch other client-side files to reload browser on changes
   • 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

TL;DR

1. Install this extension
2. Check out the example C# project for an example of use, specifically:
   • VS Code launch configuration .NET Stalker in .vscode/launch.json
   • TypeScript, ESLint and Webpack configuration files
3. Set breakpoint in jQuery document-ready function of src/TotalStalker/scripts/common.ts (to demonstrate client-side debugging)
4. Set breakpoint in OnGet() method of src/TotalStalker/Pages/Index.cshtml.cs (to demonstrate backend debugging)
5. Debug with .NET Stalker launch configuration 🚀

👨🏼‍💻 Use Cases for Developers

All use cases of .NET Stalker Debugger have all primary features (Build, Debug and Watch-Reload/Rebuild-Reattach) in a single debug session that is native to Visual Studio Code and its tooling.

🔙 Backend Developer

Backend: C#/.NET breakpoint in VS Code

• Example Project: C# ASP.NET Web App/API
• Debug Session:
  • Debug/breakpoints of C# ASP.NET Web App/API
  • Watch, re-build and re-attach to project's new process automatically

🌕 Full-Stack & 📄 Front-End Developers (Similar Launch Configurations)

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

Front-end: JavaScript/TypeScript debug console in VS Code

• Example Project: C# ASP.NET Web App/API with client-side HTML/CSS and JavaScript and/or TypeScript
• Debug Session:
  • Debug/breakpoints of C# ASP.NET Web App/API
  • Watch, re-build and re-attach to project's new process automatically
  • Debug/breakpoints of client-side JavaScript/TypeScript (in Google Chrome, Mozilla Firefox or Microsoft Edge)
  • Watch and transpile TypeScript to JavaScript (if using TypeScript and Webpack)
  • Watch and reload browser on front-end changes (HTML/CSS, JavaScript/TypeScript, etc.)

🕵 The .NET Stalker Debugger Life-Cycle

.NET Stalker Debugger: VS Code debugger call stack

Phases and Tooling

Logical order of phases within the three primary features. Depending on the launch configuration, some phases may not be used.

Requirements

Supported OS's (at least tested on)

Works on modern versions of linux (Ubuntu), macOS and Windows, where the requirements can be installed.

Requirements

• .NET SDK 6.0 or later
• Visual Studio Code 1.96.0 or later
• Visual Studio Code C# and C# Dev Kit extensions

Requirements for Client-Side Debugging

• Node.js and NPM
• Google Chrome, Mozilla Firefox and/or Microsoft Edge
  • If using Mozilla Firefox:
    • Use Firefox Developer Edition
    • Install Visual Studio Code Debugger for Firefox extension
  • If using Microsoft Edge:
    • Optionally install Visual Studio Code Debugger for Microsoft Edge extension for additional features

Launch Configurations

Launch configuration snippets available in launch.json

When adding/modifying a launch configuration in launch.json, after setting type to stalker and request to launch, VS Code IntelliSense will assist in providing the necessary properties and values.

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/net9.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": "net9.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 (or Mozilla Firefox or Microsoft Edge) client-side debugging

{
    "name": ".NET Stalker (Full)",
    "type": "stalker",
    "request": "launch",
    "vars": {
        "framework": "net9.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 --color ./scripts"
            },
            {
                "name": "Webpack",
                "commandLine": "npx webpack --watch --node-env ${env:NODE_ENV} --mode ${env:NODE_ENV} --devtool source-map --color",
                "isBackground": true,
                "waitFor": false,
                "problemMatcher": "$stalker-webpack-watch"
            }
        ]
    },
    "attachOptions": {
        "action": "debugWithChrome",
        "urlPath": "/swagger"
    }
}

Note: Set attachOptions.action to debugWithFirefox to debug with Mozilla Firefox or debugWithEdge to debug with Microsoft Edge.

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. Supported browser (Google Chrome, Mozilla Firefox or Microsoft Edge)
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.

Supported Browsers

• Google Chrome: Download here.
• Mozilla Firefox: Use Firefox Developer Edition.
• Microsoft Edge: If not pre-installed, download here.

Note: Safari does not support remote debugging thus it is not supported by this extension.

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/bootstrap @types/glob @types/jquery @types/node @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint glob path ts-loader ts-node typescript webpack webpack-cli
npm i --save @popperjs/core bootstrap jquery

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
    },
    "exclude": ["./node_modules/", "./wwwroot/", "./webpack.config.ts"],
    "include": ["./scripts/**/*.ts"],
    "compileOnSave": true
}

ESLint Files

${workspaceFolder}/src/(projectName)/eslint.config.mjs

import typescriptEslint from "@typescript-eslint/eslint-plugin";
import tsParser from "@typescript-eslint/parser";

export default [
    {
        files: ["**/*.ts"],

        ignores: ["./node_modules/**"],
    },
    {
        plugins: {
            "@typescript-eslint": typescriptEslint,
        },

        languageOptions: {
            parser: tsParser,
            ecmaVersion: 2022,
            sourceType: "module",
        },

        rules: {
            "@typescript-eslint/naming-convention": [
                "warn",
                {
                    selector: "import",
                    format: ["camelCase", "PascalCase"],
                },
            ],
            curly: ["warn", "multi-line"],
            eqeqeq: "warn",
            "no-throw-literal": "warn",
            semi: "warn",
            "no-unused-vars": "warn",
            "no-unreachable": "warn",
            "no-unused-expressions": "warn",
        },
    },
];

${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", "");
        path = "./" + path;
        entries[entry] = path;
        return entries;
    }, {} as { [key: string]: string }),
    output: {
        path: resolve(__dirname, "wwwroot/js"),
        filename: "[name].js",
        devtoolModuleFilenameTemplate: "[absolute-resource-path]",
    },
    infrastructureLogging: { level: "log" },
    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 --color ./scripts",
        }
    ]
}

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} --devtool source-map --color",
            "isBackground": true,
            "waitFor": false,
            "problemMatcher": "$stalker-webpack-watch"
        }
    ]
}

To disable the Webpack watch mode (i.e. no "hot transpiles" on file changes), remove --watch from the commandLine property.

Extension Settings

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