Core Code
Core Code Modern Dev Handbook
DOTNET Contents
Foundations (Hosting, DI, Config)
Hosting Model & Kestrel Reality DI Lifetimes (This Will Leak/Break) Options Pattern & Config Binding Env Config & Secrets (Don't Bake) Logging Basics with ILogger Health Checks: Readiness vs Liveness Graceful Shutdown Basics
Web Services Basics (ASP.NET Core)
Controllers vs Minimal APIs (Tradeoffs in Prod) Middleware Pipeline Order (Bugs You Deserve) Routing Basics (Endpoints That Bite) Endpoint Filters Basics Request/Response Streaming (Backpressure Matters) Static Files (Security Foot-guns) Shutdown Draining (Don't Drop In-Flight)
Routing, Binding & Validation
Model Binding Gotchas Validation with FluentValidation (Basics) Input Validation: What to Validate Where File Upload Basics & Hardening Querystring Filtering & Limits Multipart Size Limits (Stop Zip Bombs)
Errors & Problem Details (RFC 7807)
Exception Handling Middleware (Correctly) Problem Details (RFC 7807) Done Right Validation Errors as Problem Details Error Codes & API Contracts Global JSON Settings (Safe Defaults) 404 vs Validation (Client UX & Semantics)
Authentication & Authorization
Cookie vs Bearer Auth (Don't Mix Blindly) JWT Validation Basics (What Actually Matters) JWT Key Rotation & kid Handling AuthZ Policies, Roles, Claims Resource-Based Authorization ASP.NET Identity: When to Use It mTLS Client Certs (Basics)
Security Basics (Production)
CORS Misconfigurations (Real Impact) Security Headers (Baseline) CSRF: SameSite vs Token Defenses XSS: Output Encoding & HTML Safety Deserialization Hardening SSRF & Egress Controls Rate Limiting Basics (Server-Side) Request Size Limits (Abuse Prevention) Secrets Management for .NET Apps Dependency Vulnerability Scanning
Data Access (EF Core in Prod)
DbContext Lifetime & Pooling (Prod-Safe) Migrations Safe Rollout (No Downtime) Transactions & Isolation Levels N+1 Detection & Fix Query Performance & Index Reality Optimistic Concurrency Tokens Outbox Pattern (Basics) Soft Delete & Global Query Filters Connection Resiliency (Retries Without Lies)
HTTP Clients & Integrations
HttpClientFactory: Pooling & DNS Reality Timeouts & Deadlines (Stop Hanging Threads) Retries & Backoff Policies (When It's Okay) Circuit Breakers (Basics That Matter) Idempotency Keys for Outbound Calls Headers/Auth Forwarding (Don't Leak) HTTP/2 and HTTP/3 Considerations
Reliability Patterns
Timeouts & CancellationTokens (Correct Wiring) Retries: When NOT To (Thundering Herd) Idempotency for APIs (You Need This) Server-Side Rate Limiting (Fairness & Abuse) Bulkheads & Concurrency Limits Backpressure in Streaming (Don't OOM) Graceful Degradation & Fallbacks Saga & Compensation (Basics)
Background Jobs & Hosting
HostedService Basics (The Safe Way) Background Queue with Channels Cron Scheduling: Hangfire vs Built-in Worker Service Deploy Patterns Message Consumers & Idempotency Shutdown: Cancellation & Job Draining
Observability (Logs, Metrics, Traces)
Structured Logging with Serilog Correlation IDs & Trace Context OpenTelemetry Tracing (ASP.NET Core) OpenTelemetry Metrics (SLI-first) Health Checks Deep Dive (Readiness Done Right) Log PII Redaction (Don't Get Sued) Alerting & SLO Basics (Actionable Only) Debugging in Prod (Dumps, Traces)
Performance & Tuning
ThreadPool Starvation (Symptoms & Fix) Async Pitfalls (Deadlocks, Fire-and-Forget) Allocations & GC (What Actually Hurts) Kestrel Tuning & Limits JSON Serialization Performance EF Core Perf Hotspots (How to See Them) Caching: Response/Output Strategies
Testing & Quality Gates
Unit Testing with xUnit (Basics) Integration Tests with WebApplicationFactory Contract Tests (Basics) Mocking HTTP and Time Safely Testcontainers Basics (Real Dependencies) Coverage & Quality Gates (No Theatre) Load Testing with k6 (Basics)
Build, Release & Deploy
Build/Publish, Trimming, AOT (Basics) Dockerizing ASP.NET Core (Production) Config & Secrets in Deploy (No Baking) Blue/Green & Canary (Basics) Migrations & Deploy Order (Avoid Locking) Rollbacks vs Forward-Fix (When Each Wins) Versioning & SemVer (APIs Included) CI/CD Basics (Build, Test, Scan, Ship)
Production Runbooks
Incident Triage Playbook (First 15 Minutes) Dependency Outage Playbook (Third-Party Down) DB Latency Playbook (EF Core Included) Memory Leak Playbook (OOM Hunting) CPU Saturation Playbook (Hot Paths) Timeout Storm Playbook (Cascading Failure) Deploy Failure Playbook (Rollback Safely) Production Readiness Checklist

Rollbacks vs Forward-Fix (When Each Wins)

Rollbacks are not a strategy unless they are fast, safe, and rehearsed. Many incidents cannot be rolled back because migrations are destructive or data is already written in the new format. Learn when to roll back and when to forward-fix.
On this page

Production incident

A new release introduces a bug. The team tries to roll back, but the migration dropped a column. Old version crashes. Now rollback is impossible. You must forward-fix under pressure. Another incident: rollback would have been safe, but it took 30 minutes because image tags were not immutable and the pipeline was slow. A rollback that takes an hour is not rollback, it is a second incident.

Symptoms

  • Rollback fails due to schema incompatibility.
  • Rollback is slow and manual; people hesitate and waste time.
  • Forward-fix is rushed and risky because rollback was not viable.

Root causes

  • Destructive migrations in the same release.
  • No expand/contract discipline.
  • No immutable artifact versioning.
  • No rehearsed rollback procedure.

Decision rule: rollback vs forward-fix

  • Rollback when: bug is clearly introduced by the release, data compatibility is safe, and rollback is fast (< minutes).
  • Forward-fix when: schema/data has changed incompatibly, or the bug requires a quick patch without reverting state.
  • Mitigate first: reduce blast radius (feature flags off, rate limits, disable endpoint) while you decide.

Anti-pattern

  • “We’ll just roll back” without verifying schema compatibility.
  • Rolling back repeatedly, flapping versions, causing cache storms and unstable behavior.
  • Forward-fixing without canary, causing a second regression.

Correct pattern

  • Make rollback possible: immutable versions, blue/green traffic switch, non-destructive migrations.
  • Have feature flags to disable risky paths without deploy.
  • Rehearse rollback quarterly; treat it like a fire drill.

Operational notes

  • Monitoring: rollback success rate, time-to-rollback, and incident recurrence after rollback.
  • Rollout: canary releases reduce the need for rollbacks.
  • Postmortem: every rollback failure is a design failure. Fix the process and the deployment model.

Checklist

  • Rollback is a traffic switch, not a rebuild.
  • Artifacts are immutable and versioned.
  • Migrations are compatible with rollback (expand/contract).
  • Feature flags exist for high-risk behaviors.
  • Rollback is rehearsed and documented.
Versioning & SemVer (APIs Included) →