IronAlpine.Web.AspNetCore 2.0.0

IronAlpine.Web.AspNetCore

IronAlpine.Web.AspNetCore is the HTTP hosting package for the IronAlpine ecosystem.

It standardizes the parts that service teams usually duplicate badly:

• request metadata capture and propagation
• exception payload shape
• API versioning and Swagger
• development-safe and production-safe CORS defaults
• health endpoints
• slugified MVC route token support
• gateway/YARP propagation helpers

This package exists so services stop inventing their own middleware stack and configuration rules.

Why

Use this package when the process is an ASP.NET Core HTTP entry point:

• service APIs
• BFFs
• gateways
• internal admin APIs

Do not use it in worker-only processes that expose no HTTP pipeline.

Install

dotnet add package IronAlpine.Web.AspNetCore

Packages It Works With

Most useful combinations:

• IronAlpine.Logging.Serilog
• IronAlpine.Observability.OpenTelemetry
• IronAlpine.Messaging.*
• IronAlpine.Security.AspNetCore

When these packages are combined correctly, the same correlation context appears in:

• HTTP headers
• logs
• spans
• inbox/outbox headers
• Kafka headers

This package provides the HTTP implementation of the shared IEventMetadataAccessor contract, so messaging and logging packages can consume request metadata without depending on ASP.NET Core types.

Public Surface

Main registration methods:

• AddIronAlpineWeb(...)
• AddIronAlpineWebDefaults(...)
• AddIronAlpineHealthChecks()
• AddIronAlpineSlugifiedRoutes()

Main application methods:

• UseIronAlpineWebDefaults()
• MapIronAlpineHealthChecks()

Quick Start

using IronAlpine.Web.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddIronAlpineWebDefaults(builder.Configuration, "IdentityService")
    .AddIronAlpineHealthChecks()
    .AddControllers()
    .AddIronAlpineSlugifiedRoutes();

var app = builder.Build();

app.UseIronAlpineWebDefaults();
app.MapIronAlpineHealthChecks();
app.MapControllers();

app.Run();

Configuration

Configuration root:

{
  "IronAlpine": {
    "Web": {
      "AspNetCore": {
        "ErrorCodePrefix": "IA",
        "ServiceName": "identity-service",
        "CorsPolicyName": "IronAlpineDefaultCorsPolicy",
        "AllowedOrigins": [
          "https://app.example.com"
        ],
        "EnableSwagger": true,
        "SwaggerRoutePrefix": ""
      }
    }
  }
}

Options Deep Dive

Type: IronAlpineWebOptions

ErrorCodePrefix

• default: IA
• used by the global exception middleware
• affects the generated errorCode field returned to clients
• example output: IA-DOMAIN-0001
• change this if multiple products share the same operational estate and you want error codes to identify the product immediately

ServiceName

• default: resolved from entry assembly name if not supplied
• used by Swagger document naming and operational metadata
• best practice: set it explicitly for gateways and unusual host setups

CorsPolicyName

• default: IronAlpineDefaultCorsPolicy
• the named policy applied by UseIronAlpineWebDefaults()
• change only if you have to coexist with another named policy in the same host

AllowedOrigins

• default in Development: http://localhost:4200, http://localhost:5173, http://localhost:5000
• default outside Development: empty
• if empty outside Development, startup fails fast because production CORS must be explicit
• credentials are enabled for configured origins, so wildcard origins are intentionally not used

EnableSwagger

• default: true
• controls Swagger registration in the default web bundle
• if you host only internal worker callbacks or want zero Swagger surface, set this to false

SwaggerRoutePrefix

• default: ""
• empty string exposes Swagger UI at the application root
• use a custom value such as docs when the root path must remain application-owned

AddIronAlpineWeb(...)

This is the low-level registration surface.

It registers:

• metadata provider and middleware
• exception middleware
• options binding and validation
• request metadata runtime services

Use this when you want to build your own hosting composition and do not want CORS, Swagger, or health checks automatically included.

Example:

builder.Services.AddIronAlpineWeb(
    builder.Configuration,
    options =>
    {
        options.ErrorCodePrefix = "CRM";
        options.ServiceName = "crm-api";
    });

AddIronAlpineWebDefaults(...)

This is the recommended starter for normal APIs.

It calls the lower-level registration and also adds:

• CORS policy
• API versioning
• versioned API explorer
• Swagger generator
• endpoints API explorer

Example:

builder.Services.AddIronAlpineWebDefaults(
    builder.Configuration,
    serviceName: "personnel-service",
    configure: options =>
    {
        options.AllowedOrigins = ["https://admin.example.com"];
        options.SwaggerRoutePrefix = "docs";
    });

Middleware Order

UseIronAlpineWebDefaults() installs middleware in deterministic order:

1. metadata capture
2. exception handling
3. CORS
4. Swagger UI in development, when enabled

This order matters.

If you place your own correlation or exception middleware ahead of it, expect drift in trace ids and response payload shape.

Metadata Behavior

Request metadata sources:

• traceparent
• Activity.Current
• X-Correlation-ID
• X-Causation-ID
• X-Tenant-ID

Response behavior:

• X-Correlation-ID is always written back

Trace fallback resolution:

1. Activity.Current.TraceId
2. HttpContext.TraceIdentifier
3. generated GUID in N format

Tags written to the active activity:

• correlation.id
• causation.id
• tenant.id

CORS Behavior

Development

If AllowedOrigins is empty in development, the package enables these defaults:

• http://localhost:4200
• http://localhost:5173
• http://localhost:5000

This keeps local Angular, React, and gateway development moving without per-service ceremony.

Production

If AllowedOrigins is empty outside development, startup fails.

That is intentional. Production CORS must be explicit.

SignalR / WebSocket Alignment

Configured CORS origins use:

• AllowAnyHeader()
• AllowAnyMethod()
• AllowCredentials()

This preserves the credentialed-origin behavior SignalR typically requires. Pair this with IronAlpine.Security.AspNetCore.WithSignalR(...) for token extraction from hub requests.

Swagger and Versioning

Defaults:

• default API version: 1.0
• UrlSegmentApiVersionReader
• versioned explorer with group names like v1
• Swagger UI wired against discovered API versions

Best practice:

• keep Swagger enabled in development
• decide explicitly whether it should be exposed in non-development environments

Slugified Routes

AddIronAlpineSlugifiedRoutes() is intentionally opt-in. Route token policy is an API surface decision, not a hidden host side effect.

Example:

builder.Services
    .AddControllers()
    .AddIronAlpineSlugifiedRoutes();

This turns route tokens such as GetUserProfile into get-user-profile.

Health Checks

Registration

builder.Services.AddIronAlpineHealthChecks();

Endpoint Mapping

app.MapIronAlpineHealthChecks();

Endpoints

• /health/live
• /health/ready

Capability-Aware Checks

The package inspects registered services and adds checks only when relevant runtime capabilities exist:

• EF Core
• Redis connection multiplexer
• Kafka producer / consumer

This avoids empty or misleading readiness surfaces.

YARP / Gateway Use

For reverse proxy entry points:

builder.Services
    .AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
    .AddIronAlpineGatewayTransforms();

The transforms keep traceparent and X-Correlation-ID aligned across the gateway edge.

Combinations

Web + Logging

Use IronAlpine.Logging.Serilog so request metadata appears in logs without per-request enrichment code.

Web + OpenTelemetry

Use IronAlpine.Observability.OpenTelemetry so spans receive the same correlation context already present in middleware.

Web + Messaging

Use IronAlpine.Messaging.* so correlation and causation metadata propagate from HTTP requests into inbox/outbox rows and broker headers.

Web + Security

Use IronAlpine.Security.AspNetCore for JWT validation, permission policy wiring, and SignalR token support.

Troubleshooting

Startup fails because CORS origins are missing

Cause:

• non-development environment
• no explicit AllowedOrigins

Fix:

• configure IronAlpine:Web:AspNetCore:AllowedOrigins

Correlation id is missing in responses

Cause:

• UseIronAlpineWebDefaults() not installed
• custom middleware order is wrong

Fix:

• call UseIronAlpineWebDefaults() before custom exception/correlation middleware

Swagger UI does not load

Cause:

• EnableSwagger is false
• middleware not installed
• environment-specific UI assumption is wrong

Fix:

• verify registration and middleware
• verify route prefix

Health endpoints return 404

Cause:

• MapIronAlpineHealthChecks() not called

Fix:

• map health endpoints after builder.Build()

SignalR authentication works but browser connections fail

Cause:

• CORS origins are not aligned with the browser origin
• credentialed requests blocked by origin mismatch

Fix:

• explicitly configure AllowedOrigins
• verify SignalR hub origin and JWT query-token settings together