debug-dotnet_skill

Overview

This skill helps you debug ASP.NET Core and .NET applications using a systematic, four-phase diagnostic methodology. It focuses on common failure classes—dependency injection, middleware pipeline, EF Core queries, configuration binding, authentication/authorization, and startup/hosting failures. The skill integrates IDE debugging (Visual Studio, VS Code) with runtime tools (dotnet-trace, dotnet-dump, dotnet-counters) and logging strategies (Serilog, Application Insights).

How this skill works

The skill inspects runtime failures, configuration and DI registration, middleware ordering, EF Core query patterns, and authentication flows. It prescribes targeted diagnostics: enable detailed errors, add tracing middleware, collect traces/dumps/counters, and examine logs and claims. Practical fixes, code patterns, and tool commands are provided so you can reproduce, isolate, and resolve issues efficiently.

When to use it

• When services fail to resolve or you see circular/captive dependency errors
• When requests return unexpected status codes, headers, or response-started errors
• When EF Core shows N+1 queries, tracking conflicts, or slow SQL
• When configuration values are missing, environment files don’t load, or options fail validation
• When authentication/authorization yields 401/403 or tokens/claims are incorrect
• When the app fails to start, shows process failures, or crashes in hosting environments

Best practices

• Follow a four-phase debug loop: reproduce, collect diagnostics, isolate root cause, apply and verify fix
• Enable detailed DI and EF Core diagnostics in development, but avoid sensitive logging in production
• Keep middleware in the recommended order and add lightweight request/response tracing middleware for pipeline inspection
• Use AsNoTracking and Include/AsSplitQuery to control EF Core behavior and avoid N+1 problems
• Collect traces/dumps/counters for production-only incidents and combine with structured logging (Serilog) and telemetry (Application Insights)

Example use cases

• Resolve an InvalidOperationException by locating a missing or incorrectly scoped service registration and fixing lifetimes
• Track down a middleware ordering bug causing authentication to be skipped and restore correct UseAuthentication/UseAuthorization placement
• Diagnose EF Core N+1 behavior by enabling query logging and adding Include or AsSplitQuery
• Capture a CPU profile with dotnet-trace and visualize it to identify hot paths in production
• Analyze a memory leak using dotnet-dump heap commands and gcroot to find retained objects