.NET Exception Handling Quality Improvement

Purpose

Systematic investigation and remediation of .NET exception handling anti-patterns. Detects, documents, and fixes the 10 most common exception handling mistakes in .NET applications.

Use when: Preparing for production, code quality audits, security reviews, or onboarding to a .NET codebase.

Usage

Investigation only (default)

/dotnet-exception-handling <path-to-dotnet-project>

Filter by severity

/dotnet-exception-handling <project-path> --priority critical

Auto-implement all fixes

/dotnet-exception-handling <project-path> --fix-all

Arguments:

• project-path : Directory containing .csproj or .sln (default: current directory)

• --priority : critical | high | medium | low | all (default: all )

• --fix-all : Implement fixes automatically (default: investigate only)

The 10 Common Mistakes

• Catching Exception Too Broadly - Base Exception instead of specific types

• Swallowing Exceptions Silently - Empty catch blocks hiding errors

• Using throw ex;

• Resets stack traces (use throw; )

• Wrapping Everything in Try/Catch - Defensive coding clutter

• Exceptions for Control Flow - Performance overhead for expected conditions

• Forgetting to Await Async - Unhandled exceptions on background threads

• Ignoring Background Task Exceptions - Fire-and-forget losing errors

• Generic Exception Types - Vague new Exception() instead of specific types

• Losing Inner Exceptions - Breaking exception chains

• Missing Global Handler - No centralized error handling (stack traces exposed)

Detailed descriptions, detection patterns, and fix templates → see reference.md

Execution Workflow

Phase 1: Investigation (6 Steps)

Step 1: Project Detection

• Scan for .csproj, .sln files

• Identify project types (ASP.NET Core, worker services, libraries)

• Count C# files for scope estimation

Step 2: Parallel Analysis

• Deploy 5 specialized agents:

• Background Worker Specialist

• API Layer Specialist

• Service Layer Specialist

• Data Layer Specialist

• Infrastructure Specialist

Step 3: Violation Detection

Use rg -P (ripgrep PCRE mode) for pattern matching:

Mistake #1: Broad catches

rg -P 'catch\s*(Exception\b' --glob '*.cs'

Mistake #2: Empty catches

rg -P 'catch[^{]{\s(//[^\n])?\s}' --glob '*.cs'

Mistake #3: throw ex

rg 'throw\s+ex;' --glob '*.cs'

See reference.md for complete pattern list

Step 4: Severity Classification

• CRITICAL: Security (stack trace exposure, missing global handler)

• HIGH: Reliability (swallowed exceptions, broad catches)

• MEDIUM: Code quality (excessive try/catch)

• LOW: Style issues

Step 5: Findings Report

• Generate markdown with file:line references

• Code snippets + recommended fixes

• Priority-based roadmap

Step 6: Knowledge Capture

• Store in .claude/runtime/logs/EXCEPTION_INVESTIGATION_YYYY-MM-DD.md

• Update project memory

Phase 2: Development (If --fix-all)

Step 7: Orchestrate Default Workflow

• Create GitHub issue with findings

• Set up worktree for fixes

• Implement GlobalExceptionHandler, Result, etc.

• Write comprehensive tests (TDD)

• Three-agent review (reviewer, security, philosophy)

Step 8: Validation

• All tests pass

• Security: Zero stack traces

• Performance: <5ms p99 overhead

Quick Start Examples

Example 1: Investigation Only

/dotnet-exception-handling ./src/MyApi

Output: Investigation report with 23 violations (1 CRITICAL, 8 HIGH, 12 MEDIUM, 2 LOW)

Example 2: Fix Critical Only

/dotnet-exception-handling ./src/MyApi --priority critical --fix-all

Output: GitHub issue + PR implementing GlobalExceptionHandler + 15 tests

Example 3: Complete Fix

/dotnet-exception-handling ./src/MyApi --fix-all

Output: 23 violations fixed, 67 tests, PR ready (CI passing)

Core Architecture Patterns

GlobalExceptionHandler (IExceptionHandler)

Centralized exception-to-HTTP mapping for ASP.NET Core:

public class GlobalExceptionHandler : IExceptionHandler { public async ValueTask<bool> TryHandleAsync( HttpContext httpContext, Exception exception, CancellationToken cancellationToken) { var (statusCode, title) = exception switch { ArgumentException => (400, "Invalid request"), NotFoundException => (404, "Not found"), ConflictException => (409, "Conflict"), _ => (500, "Internal server error") };

    httpContext.Response.StatusCode = statusCode;
    await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
    {
        Status = statusCode,
        Title = title,
        Detail = statusCode >= 500
            ? "An error occurred"
            : exception.Message
    }, cancellationToken);

    return true;
}

}

// Registration in Program.cs builder.Services.AddExceptionHandler<GlobalExceptionHandler>(); app.UseExceptionHandler();

Benefits: Zero stack traces, consistent responses, no try/catch in controllers

Result Pattern

Railway-oriented programming for validation (no exceptions for expected conditions):

public Result<Order> ValidateOrder(CreateOrderDto dto) { if (dto.Items.Count == 0) return Result<Order>.Failure("Order must have items");

return Result<Order>.Success(new Order(dto));

}

// Controller usage var result = await _service.ValidateOrder(dto); return result.Match( onSuccess: order => Ok(order), onFailure: error => BadRequest(error) );

Benefits: 100x faster than exceptions, explicit error handling, better composition

Complete implementations → see examples.md

Navigation Guide

When to Read Supporting Files

reference.md - Read when you need:

• Detailed descriptions of all 10 exception handling mistakes

• Complete detection patterns for ripgrep/grep

• Fix templates for each mistake type

• Security considerations (OWASP compliance, stack trace prevention)

• Severity classification reference

• Integration patterns (Azure SDK, EF Core, Service Bus)

examples.md - Read when you need:

• Before/after code examples for each mistake

• Complete working implementations (GlobalExceptionHandler, Result, DbContextExtensions)

• Real-world scenarios (order processing, payment systems)

• Unit and integration testing patterns

• Copy-paste ready code

patterns.md - Read when you need:

• Architecture decision trees (global handler vs try/catch, Result vs exceptions)

• Background worker exception handling patterns

• Azure SDK exception translation patterns

• EF Core concurrency and transaction patterns

• Performance benchmarks (Result vs exceptions)

• Anti-patterns to avoid

Workflow Integration

This skill orchestrates two canonical workflows:

• Investigation Workflow (Phase 1): Scope → Explore → Analyze → Classify → Report → Capture

• Default Workflow (Phase 2, if --fix-all): Requirements → Architecture → TDD → Implementation → Review → CI/CD

References

• Article: Top 10 Exception Handling Mistakes in .NET

• Microsoft: Best Practices for Exceptions

• ASP.NET Core: Handle Errors in Web APIs

• Investigation Workflow: ~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md

• Default Workflow: ~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md

Version History

• v1.0.0 (2026-02-10): Initial implementation based on CyberGym investigation (52 violations fixed, 87 tests)

Known Limitations

• Requires .NET 6+ for IExceptionHandler

• Result pattern targets C# 7.0+ (struct readonly, expression-bodied members)

• Patterns specific to ASP.NET Core (may not apply to class libraries)