Step-by-Step Debugging ASP.NET Core in VS Code

Visual Studio Code is a lightweight yet powerful editor that fully supports step-by-step debugging for ASP.NET Core applications. With the correct setup, you can debug controllers, services, middleware, and Web APIs just like you would in Visual Studio.

This guide walks you through everything you need to know, from prerequisites to advanced debugging scenarios.

1. Prerequisites

Before debugging ASP.NET Core in VS Code, make sure you have the following installed:

1.1 Install .NET SDK

You must install the .NET SDK, not just the runtime.

Verify the installation:

1.2 Install Visual Studio Code

Download and install the latest version of Visual Studio Code.

1.3 Install the C# Extension

In VS Code, install:

• C# Dev Kit (Microsoft)
  This includes OmniSharp and debugging support for .NET.

2. Open Your ASP.NET Core Project

Open the root folder of your ASP.NET Core project in VS Code (the folder containing .csproj).

If this is your first time opening a C# project, VS Code will ask to restore dependencies — allow it.

3. Create Debug Configuration (launch.json)

3.1 Generate launch.json Automatically

1. Open Run & Debug panel (Ctrl + Shift + D)

2. Click Create a launch.json file

3. Choose .NET Core

4. Select ASP.NET Core

VS Code will generate a .vscode/launch.json file.

3.2 Sample launch.json Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "ASP.NET Core",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/bin/Debug/net8.0/YourProject.dll",
      "args": [],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "serverReadyAction": {
        "action": "openExternally",
        "pattern": "\\bNow listening on:\\s+(https?://\\S+)"
      },
      "env": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  ]
}

⚠️ Make sure:

• net8.0 matches your project target framework

• YourProject.dll matches your project name

4. Set Breakpoints

Open any C# file and click next to the line number to set a breakpoint.

Example in a controller:

Breakpoints can be placed in:

• Controllers

• Services

• Repositories

• Middleware

• Minimal API endpoints

5. Start Debugging

Press F5 or click Start Debugging.

VS Code will:

• Build the project

• Launch the ASP.NET Core application

• Open the browser automatically (if configured)

Trigger an API request using:

• Browser

• Swagger UI

• Postman

• Frontend application

When the request hits your breakpoint, execution will pause.

6. Step-by-Step Debugging Controls

While paused, you can use:

• Step Over (F10) – execute the next line

• Step Into (F11) – go inside a method

• Step Out (Shift + F11) – exit the current method

• Continue (F5) – resume execution

You can also inspect:

• Local variables

• Parameters

• Call Stack

• Watch expressions

7. Debugging Web APIs

VS Code works perfectly for debugging Web APIs.

Typical workflow:

1. Start debugging with F5

2. Open Swagger or Postman

3. Send an HTTP request

4. Breakpoint is hit

5. Inspect request data and logic step by step

This is especially useful for:

• Authentication / Authorization issues

• Business logic validation

• Database interaction debugging

8. Attach Debugger to a Running App

If your application is already running using:

You can still debug it:

1. Open Run & Debug

2. Choose .NET Core Attach

3. Select the correct dotnet process

This is useful for:

• Docker containers

• Background services

• Long-running processes

9. Common Issues and Fixes

Breakpoints Not Being Hit

• Ensure you are running in Debug, not Release

• Check that program path in launch.json is correct

• Clean and rebuild the project

OmniSharp Not Working

• Restart OmniSharp (Ctrl + Shift + P → Restart OmniSharp)

• Ensure only one .NET SDK is active

10. VS Code vs Visual Studio

VS Code is ideal when you:

• Build Web APIs

• Work with microservices

• Prefer a lightweight editor

• Use cross-platform development

Visual Studio may be better when you:

• Work heavily with Razor Pages

• Use advanced EF tooling

• Prefer GUI-based scaffolding

Conclusion

Visual Studio Code provides full step-by-step debugging support for ASP.NET Core. With breakpoints, variable inspection, and API debugging, it is a powerful choice for modern .NET development—especially for backend and Web API projects.

If you prefer speed, flexibility, and cross-platform support, VS Code is an excellent option for ASP.NET Core debugging.