dotnet-pro

Overview

.NET (formerly .NET Core) is Microsoft's cross-platform runtime for C#, F#, and VB.NET, and ASP.NET Core is its high-performance web framework. The modern stack is opinionated in the right places: built-in dependency injection, strongly-typed configuration, Entity Framework Core for data access, and first-class container support. This skill covers building .NET services idiomatically — minimal APIs vs controllers, EF Core without N+1s, and production configuration.

When to use

• Building an API or backend service in C# on .NET 8/9+.
• Choosing between minimal APIs and controller-based ASP.NET Core.
• Taming EF Core query behavior (N+1, tracking, migrations).
• Structuring DI, configuration, and logging the .NET way.
• Containerizing and deploying .NET services.
• Adding background processing (hosted services, Hangfire, Quartz).
• Migrating .NET Framework apps to modern .NET.

Core concepts

• Minimal APIs vs controllers. Minimal APIs (app.MapGet(...)) suit small services and microservices with less ceremony; controllers suit large APIs needing filters, versioning, and conventions. Both run on the same pipeline — pick per service size, not per trend.
• Built-in DI container. Services registered as Singleton/Scoped/Transient in Program.cs. Rules that matter: never inject a scoped service into a singleton (use IServiceScopeFactory), prefer constructor injection, and keep registration near composition root.
• Configuration stack. appsettings.json → appsettings.{Environment}.json → environment variables → secret stores. Bind to strongly-typed options classes with validation (ValidateDataAnnotations); secrets never live in json files committed to git.
• EF Core. Code-first with migrations (dotnet ef migrations add). Query pitfalls mirror every ORM: N+1 via lazy loading (use .Include() / projections with .Select()), change tracking overhead on read-only queries (use .AsNoTracking()), and client-side evaluation surprises.
• Middleware pipeline. app.Use... ordering matters: exception handling → HSTS/HTTPS → static files → routing → auth → endpoints. Write custom middleware for cross-cutting concerns (correlation IDs, request logging).
• Logging and observability. ILogger<T> with structured templates (LogInformation("Order {OrderId} created", id)); OpenTelemetry packages for traces/metrics; health checks via AddHealthChecks() wired to your orchestrator.
• Hosted services. IHostedService/BackgroundService for background work inside the API process (queue consumers, schedulers); for heavy or critical workloads, prefer a separate worker process or external queue.
• Options validation. ValidateDataAnnotations() + ValidateOnStart() fail fast on bad config at startup — much better than a null-reference at 3am.
• Native AOT. Compile to a single native binary with fast startup and small footprint — excellent for containers and serverless, with trimmability constraints (reflection-heavy code needs annotations).
• Problem details. Results.Problem() / ProblemDetails for RFC-compliant error responses; consistent shape across the API via a global exception handler.
• Source generators. Compile-time code generation (JSON serialization, logging, regex) with zero runtime reflection cost — prefer them over reflection in hot paths.
• Channels. System.Threading.Channels for in-process producer/consumer pipelines — the right primitive for background work without standing up external queue infrastructure.

Practical workflow

1. Scaffold. dotnet new webapi -n Shop (or web for minimal API); target the latest LTS; keep the SDK version pinned with global.json.

2. Structure. Controllers/endpoints thin → application services (business logic) → repositories or direct DbContext → DTOs/records at the boundary; entities never serialized directly.

   app.MapPost("/orders", async (CreateOrderRequest req, IOrderService svc) => {
       var order = await svc.PlaceOrderAsync(req);
       return Results.Created($"/orders/{order.Id}", order);
   });
   

3. Configure. Options pattern for settings; appsettings.Production.json for non-secret overrides; secrets via environment or Azure Key Vault / similar; validate required settings at startup so misconfiguration fails fast.

4. Data access. EF Core migrations in source control; .AsNoTracking() for reads; project to DTOs with .Select() instead of returning entities; index FK and filtered columns; use explicit transactions for multi-write operations.

   await using var tx = await db.Database.BeginTransactionAsync();
   // ... writes via db ...
   await tx.CommitAsync();
   

5. Harden the API. Authentication (JWT bearer / OIDC), authorization policies (not just [Authorize] — check resource ownership), rate limiting middleware, input validation (FluentValidation or data annotations), and problem-details error responses.

6. Test. xUnit + WebApplicationFactory for integration tests against the real pipeline; unit-test services with mocked dependencies; Testcontainers for database-backed tests.

7. Add background work. BackgroundService for in-process workers; separate worker project for anything critical; ensure graceful shutdown via the host's lifetime events.

8. Ship. Multi-stage Dockerfile with the SDK image for build and the ASP.NET runtime image for run; DOTNET_ENVIRONMENT=Production; health check endpoints; readiness/liveness probes pointing at them.

   builder.Services.AddOptions<ShopSettings>()
       .BindConfiguration("Shop")
       .ValidateDataAnnotations()
       .ValidateOnStart();
   
   builder.Services.AddHealthChecks()
       .AddNpgSql(builder.Configuration.GetConnectionString("Default"));
   

Common pitfalls

• Captive dependencies — scoped DbContext injected into a singleton service; it silently shares one context across requests until it breaks.
• N+1 in EF Core — lazy-loaded navigations during serialization; .Include() or project with .Select().
• Tracking on read-heavy endpoints — change tracking on thousands of entities wastes memory and CPU; .AsNoTracking() by default for reads.
• Synchronous blocking on async (.Result / .Wait()) — deadlocks under load; async all the way.
• Secrets in appsettings.json committed to git — use user-secrets locally and a vault in real environments.
• No migration strategy — EnsureCreated() in production instead of migrations; schema drifts and data loss follow.
• Ignoring GC/container memory — set DOTNET_GCHeapHardLimitPercent or container-aware defaults so the runtime respects cgroup limits.
• Returning entities from endpoints — lazy loading during serialization, circular references; project to DTOs.
• Missing ValidateOnStart — bad config discovered at first request instead of at boot; validate eagerly.
• No request timeouts — HttpClient without timeouts hanging threads; configure HttpClientFactory with Polly policies.
• Not using IHttpClientFactory — new HttpClient() per request causes socket exhaustion; register typed or named clients once.
• Ignoring CancellationToken — endpoints that can't be cancelled hold threads after clients disconnect; thread the token through to async calls.
• Overusing dynamic — kills compile-time safety and JIT performance; use records and DTOs instead.