TiqriGlobalShop.Common.AspNetCore 1.1.0

GlobalShop.Common.AspNetCore

Shared ASP.NET Core infrastructure for GlobalShop web APIs.

Features

• Exception Handlers — Production-ready IExceptionHandler implementations:

  • CancellationExceptionHandler — Handles client-cancelled requests (HTTP 499)
  • ConcurrencyExceptionHandler — Handles EF Core optimistic concurrency conflicts (HTTP 409)
  • PostgresExceptionHandler — Maps PostgreSQL error codes to appropriate HTTP responses
  • DatabaseExceptionHandler — Handles general database connectivity errors (HTTP 503)
  • GlobalExceptionHandler — Catch-all for unhandled exceptions (HTTP 500), with dev-mode details

• Middleware

  • RequestContextLoggingMiddleware — Extracts/generates X-Correlation-Id and pushes it into the Serilog LogContext

• Minimal API Endpoints

  • IEndpoint — Interface for discoverable minimal API endpoints
  • EndpointExtensions — Auto-discovers and maps IEndpoint implementations from an assembly

• Problem Details

  • AddCommonProblemDetails() — Configures RFC 9457 Problem Details with traceId, timestamp, and instance

• API Versioning

  • AddCommonApiVersioning() — Header-based API versioning with sensible defaults
  • ConfigureSwaggerVersioningOptions — Auto-generates versioned Swagger documents

• Swagger / OpenAPI

  • SwaggerDefaultValues — Populates default API version parameters, deprecation markers, and response content types
  • ApiVersionHeaderOperationFilter — Adds x-api-version header parameter to all Swagger operations
  • ServiceCollectionExtensions.AddSwaggerGenWithJwtAuth() — Configures Swagger with JWT Bearer authentication
  • ApplicationBuilderExtensions.UseSwaggerWithUi() — Enables Swagger + Swagger UI middleware
  • ApplicationBuilderExtensions.UseSwaggerWithVersionedUi() — Enables Swagger UI with per-version endpoints

• Database Migrations

  • ApplyMigrations<TDbContext>() — Resilient EF Core migration runner with Polly retry (exponential backoff + jitter)

• Health Checks

  • MapCommonHealthChecks() — Maps a health check endpoint with detailed JSON response

• Result Pattern Helpers

  • ResultExtensions.Match() — Pattern-match on Result / Result<T> for railway-oriented endpoint handlers
  • CustomResults.Problem() — Converts Result failures to RFC 9457 Problem Details responses

• JSON Patch

  • JsonPatchBinder<TModel> — Base class for model-binding JsonPatchDocument<T>

Installation

dotnet add package GlobalShop.Common.AspNetCore

Quick Start

Register Exception Handlers

// In Program.cs or ConfigureServices
builder.Services.AddCommonProblemDetails();   // RFC 9457 with traceId, timestamp, instance
builder.Services.AddCommonExceptionHandlers(); // registers all 5 handlers

// ...
app.UseExceptionHandler();

API Versioning

// Header-based versioning with x-api-version header
builder.Services.AddCommonApiVersioning();

// Versioned Swagger docs
builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>>(sp =>
    new ConfigureSwaggerVersioningOptions(
        sp.GetRequiredService<IApiVersionDescriptionProvider>(),
        apiTitle: "My API",
        apiDescription: "My API description"
    ));
builder.Services.AddSwaggerGenWithJwtAuth();

// In dev mode
app.UseSwaggerWithVersionedUi();

Resilient Database Migrations

if (app.Environment.IsDevelopment())
{
    app.ApplyMigrations<MyDbContext>(); // Polly retry for NpgsqlException
}

Health Checks

app.MapCommonHealthChecks(); // maps /health endpoint

Use Correlation ID Middleware

app.UseRequestContextLogging(); // adds X-Correlation-Id to Serilog LogContext
app.UseSerilogRequestLogging();

Discover Minimal API Endpoints

// Register
builder.Services.AddEndpoints(Assembly.GetExecutingAssembly());

// Map
app.MapEndpoints();

Result Pattern Helpers

using GlobalShop.Common.AspNetCore.Extensions;
using GlobalShop.Common.AspNetCore.Results;

// In a minimal API endpoint handler
return result.Match(Results.Ok, CustomResults.Problem);

Dependencies

License

MIT