Advanced

using Microsoft.Extensions.Options;

// Options for the middleware
public class RequestThrottleOptions
{
    public int MaxRequestsPerSecond { get; set; } = 100;
    public bool LogThrottledRequests { get; set; } = true;
}

// Middleware class - not a filter, not a policy - pure pipeline component
public class RequestThrottleMiddleware
{
    private readonly RequestDelegate _next;
    // => _next is the next middleware in the pipeline
    private readonly RequestThrottleOptions _options;
    private readonly ILogger<RequestThrottleMiddleware> _logger;
    // => Services injected via constructor (all Singleton or Transient)

    private int _requestCount = 0;
    private DateTime _windowStart = DateTime.UtcNow;
    // => In production: use proper rate limiting (Semaphore, Redis, etc.)

    public RequestThrottleMiddleware(
        RequestDelegate next,
        IOptions<RequestThrottleOptions> options,
        ILogger<RequestThrottleMiddleware> logger)
    {
        _next = next;
        _options = options.Value;
        _logger = logger;
        // => Middleware constructors receive Singleton-lifetime services
        // => Do NOT inject Scoped services here (captive dependency)
    }

    // InvokeAsync is the required method - called for every request
    public async Task InvokeAsync(HttpContext context)
    {
        // => InvokeAsync called for each request passing through
        // => Can inject Scoped services as method parameters (safe)
        var now = DateTime.UtcNow;

        if ((now - _windowStart).TotalSeconds >= 1)
        {
            Interlocked.Exchange(ref _requestCount, 0);
            // => Interlocked: thread-safe counter reset
            _windowStart = now;
        }

        var count = Interlocked.Increment(ref _requestCount);
        // => Atomic increment; count is the value after increment

        if (count > _options.MaxRequestsPerSecond)
        {
            if (_options.LogThrottledRequests)
                _logger.LogWarning("Request throttled: {Count} req/s exceeds {Max}",
                    count, _options.MaxRequestsPerSecond);
            context.Response.StatusCode = 429;
            // => 429 Too Many Requests
            await context.Response.WriteAsync("Rate limit exceeded");
            return;
            // => return without calling _next: short-circuit the pipeline
        }

        await _next(context);
        // => Call next middleware: request continues through pipeline
    }
}

// Extension method for clean registration
public static class RequestThrottleExtensions
{
    public static IApplicationBuilder UseRequestThrottle(this IApplicationBuilder app)
        => app.UseMiddleware<RequestThrottleMiddleware>();
    // => Extension method hides UseMiddleware<T>() call
    // => app.UseRequestThrottle() reads naturally in Program.cs
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<RequestThrottleOptions>(options =>
{
    options.MaxRequestsPerSecond = 50;
    // => Override default 100 to 50 req/s
});

var app = builder.Build();
app.UseRequestThrottle();
// => Registers custom middleware via extension method
app.MapGet("/", () => "OK");
app.Run();

using System.Net;
using System.Text.Json;

// Custom exception types for semantic error categorization
public class NotFoundException : Exception
{
    public NotFoundException(string message) : base(message) {}
}

public class ValidationException : Exception
{
    public Dictionary<string, string[]> Errors { get; }
    public ValidationException(Dictionary<string, string[]> errors) : base("Validation failed")
    {
        Errors = errors;
    }
}

public class ForbiddenException : Exception
{
    public ForbiddenException(string message) : base(message) {}
}

// Exception handling middleware
public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
            // => Let request proceed through pipeline normally
        }
        catch (NotFoundException ex)
        {
            await WriteErrorResponse(context, HttpStatusCode.NotFound, ex.Message);
            // => Domain not-found exceptions => 404 Not Found
        }
        catch (ValidationException ex)
        {
            context.Response.StatusCode = (int)HttpStatusCode.BadRequest;
            context.Response.ContentType = "application/problem+json";
            var problem = new
            {
                Type = "https://tools.ietf.org/html/rfc9457#section-3.1",
                Title = "Validation Error",
                Status = 400,
                Errors = ex.Errors
                // => ex.Errors = {"Name":["Name is required"],"Price":["Must be positive"]}
            };
            await context.Response.WriteAsync(JsonSerializer.Serialize(problem));
        }
        catch (ForbiddenException ex)
        {
            await WriteErrorResponse(context, HttpStatusCode.Forbidden, ex.Message);
            // => Domain forbidden exceptions => 403 Forbidden
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unhandled exception for {Method} {Path}",
                context.Request.Method, context.Request.Path);
            // => Log full exception with context
            await WriteErrorResponse(context, HttpStatusCode.InternalServerError,
                "An unexpected error occurred");
            // => Generic message hides implementation details from clients
        }
    }

    private static async Task WriteErrorResponse(HttpContext context, HttpStatusCode status, string message)
    {
        context.Response.StatusCode = (int)status;
        context.Response.ContentType = "application/problem+json";
        var body = JsonSerializer.Serialize(new
        {
            Type = $"https://httpstatuses.io/{(int)status}",
            Title = status.ToString(),
            Status = (int)status,
            Detail = message
        });
        await context.Response.WriteAsync(body);
    }
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Register FIRST - catches exceptions from all subsequent middleware
app.UseMiddleware<ExceptionHandlingMiddleware>();

app.MapGet("/products/{id:int}", (int id) =>
{
    if (id > 100)
        throw new NotFoundException($"Product {id} does not exist");
    // => Exception propagates up to ExceptionHandlingMiddleware
    // => Returns 404 {"type":"...","title":"NotFound","status":404,"detail":"Product..."}
    return Results.Ok(new { Id = id });
});

app.Run();

// Install: dotnet add package Microsoft.AspNetCore.OutputCaching
using Microsoft.AspNetCore.OutputCaching;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOutputCache(options =>
{
    // Default policy - applies to endpoints with .CacheOutput() and no policy name
    options.AddBasePolicy(policy =>
        policy.Expire(TimeSpan.FromMinutes(5)));
    // => Default: cache all responses for 5 minutes

    // Named policy for product catalog (cache longer, tag for invalidation)
    options.AddPolicy("ProductsCatalog", policy =>
        policy.Expire(TimeSpan.FromMinutes(30))
              .Tag("products")
              // => Tag enables targeted cache invalidation
              .SetVaryByQuery("category", "page", "pageSize"));
              // => Create separate cache entry for each query parameter combination
              // => GET /products?category=electronics and ?category=books are cached separately
});

var app = builder.Build();
app.UseOutputCache();
// => UseOutputCache must be added before endpoints that use caching

// Cache individual endpoint response
app.MapGet("/products", (string? category) =>
    Results.Ok(new[] { new { Id = 1, Name = "Widget", Category = category } }))
    .CacheOutput("ProductsCatalog");
// => Response cached per "ProductsCatalog" policy
// => First request: handler executes, response stored in cache
// => Subsequent requests (same query params): cached response returned instantly

// Cache with custom duration override
app.MapGet("/hot-deals", () =>
    Results.Ok(new { Deals = new[] { "50% off Widget" } }))
    .CacheOutput(policy => policy.Expire(TimeSpan.FromSeconds(30)));
// => Inline policy: cache hot deals for only 30 seconds (changes frequently)

// Endpoint that invalidates cached entries
app.MapPost("/products", async (object product, IOutputCacheStore cacheStore, CancellationToken ct) =>
{
    // Simulate saving product to database
    await Task.Delay(10, ct);

    await cacheStore.EvictByTagAsync("products", ct);
    // => Evict ALL cached responses tagged "products"
    // => Next request to /products fetches fresh data from handler
    // => Without this: stale cache serves old product list after creation

    return Results.Created("/products/1", product);
});

// No caching for frequently changing data
app.MapGet("/prices/live", () =>
    Results.Ok(new { Price = Random.Shared.NextDouble() * 100 }))
    .CacheOutput(policy => policy.NoCache());
// => NoCache: bypass output cache entirely for this endpoint

app.Run();

using Microsoft.AspNetCore.ResponseCompression;
using System.IO.Compression;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    // => Compress HTTPS responses (disabled by default due to CRIME/BREACH attacks)
    // => Evaluate BREACH risk before enabling; mitigate with per-request tokens

    options.Providers.Add<BrotliCompressionProvider>();
    // => Brotli: better compression ratio than gzip (10-20% smaller)
    // => Supported by all modern browsers (Chrome, Firefox, Safari, Edge)

    options.Providers.Add<GzipCompressionProvider>();
    // => Gzip: universal support including legacy clients
    // => Framework picks Brotli if client accepts it, falls back to Gzip

    options.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(new[]
    {
        "application/json",
        // => Add JSON to compressed types (default includes text/html, text/css, etc.)
        "application/xml",
        "text/csv"
    });
    // => Only compress specified MIME types; binary types (images, video) already compressed
});

builder.Services.Configure<BrotliCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Fastest;
    // => CompressionLevel.Fastest: minimum compression, fastest CPU
    // => CompressionLevel.Optimal: balanced (default)
    // => CompressionLevel.SmallestSize: maximum compression, slowest CPU
    // => For JSON APIs: Fastest is usually best (CPU is cheaper than bandwidth)
});

builder.Services.Configure<GzipCompressionProviderOptions>(options =>
{
    options.Level = CompressionLevel.Fastest;
});

var app = builder.Build();

app.UseResponseCompression();
// => Must be added BEFORE endpoints that return compressible responses
// => And BEFORE UseStaticFiles if serving text assets

app.MapGet("/large-dataset", () =>
{
    // Generate a large JSON response to demonstrate compression
    var data = Enumerable.Range(1, 1000)
        .Select(i => new { Id = i, Name = $"Item {i}", Description = $"Description for item {i}" });
    // => ~70KB uncompressed JSON
    // => ~10KB with Brotli compression (~85% reduction)
    return Results.Ok(data);
});
// => Client sends Accept-Encoding: br, gzip => Framework chooses Brotli
// => Response includes Content-Encoding: br header
// => Without compression: 70KB transfer
// => With Brotli: ~10KB transfer

app.Run();

// Install: dotnet add package Grpc.AspNetCore

// greet.proto (placed in Protos/ folder):
// syntax = "proto3";
// option csharp_namespace = "MyApp";
// package greet;
//
// service Greeter {
//   rpc SayHello (HelloRequest) returns (HelloReply);
//   rpc SayHelloStream (HelloRequest) returns (stream HelloReply);
// }
//
// message HelloRequest {
//   string name = 1;
// }
//
// message HelloReply {
//   string message = 1;
// }

// Add to .csproj:
// <ItemGroup>
//   <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
// </ItemGroup>

using Grpc.Core;

// Generated base class from .proto file
// public class GreeterService : Greeter.GreeterBase
// {
//     private readonly ILogger<GreeterService> _logger;
//
//     public GreeterService(ILogger<GreeterService> logger)
//     {
//         _logger = logger;
//     }
//
//     // Unary RPC - one request, one response
//     public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
//     {
//         // => request.Name from protobuf message
//         _logger.LogInformation("Greeting {Name}", request.Name);
//         return Task.FromResult(new HelloReply
//         {
//             Message = $"Hello, {request.Name}!"
//             // => Protobuf serializes this to binary (not JSON)
//             // => Typically 3-5x smaller than equivalent JSON
//         });
//     }
//
//     // Server-streaming RPC - one request, multiple responses
//     public override async Task SayHelloStream(
//         HelloRequest request,
//         IServerStreamWriter<HelloReply> responseStream,
//         ServerCallContext context)
//     {
//         // => IServerStreamWriter sends multiple responses
//         for (int i = 1; i <= 5; i++)
//         {
//             if (context.CancellationToken.IsCancellationRequested)
//                 break;
//             // => Check cancellation in streaming loops
//
//             await responseStream.WriteAsync(new HelloReply
//             {
//                 Message = $"Hello {request.Name}! (message {i})"
//             });
//             // => Each WriteAsync sends one streaming response
//             await Task.Delay(500, context.CancellationToken);
//             // => Simulate work between messages
//         }
//     }
// }

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGrpc(options =>
{
    options.EnableDetailedErrors = builder.Environment.IsDevelopment();
    // => Detailed errors include exception messages in gRPC status
    // => Disable in production to avoid leaking internals
    options.MaxReceiveMessageSize = 4 * 1024 * 1024; // 4MB
    // => Maximum incoming message size
    options.MaxSendMessageSize = null;
    // => No limit on outgoing message size (null = unlimited)
});

var app = builder.Build();
// app.MapGrpcService<GreeterService>();
// => Registers gRPC service at /greet.Greeter/SayHello
// => Clients use generated gRPC stubs to call this endpoint

// gRPC reflection for development tooling (grpcurl, Postman)
// app.MapGrpcReflectionService();
// => Enables runtime service discovery for gRPC tools

app.Run();

// Install: dotnet add package OpenTelemetry.Extensions.Hosting
// Install: dotnet add package OpenTelemetry.Instrumentation.AspNetCore
// Install: dotnet add package OpenTelemetry.Instrumentation.Http
// Install: dotnet add package OpenTelemetry.Exporter.Console (dev) or Otlp (prod)

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using System.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

// Configure OpenTelemetry tracing
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource =>
        resource.AddService(
            serviceName: "products-api",
            // => serviceName appears in trace visualization tools
            serviceVersion: "1.0.0"))
            // => serviceVersion helps correlate traces with deployments
    .WithTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation(options =>
            {
                options.RecordException = true;
                // => Record exceptions as trace events with full stack trace
                options.EnrichWithHttpRequest = (activity, request) =>
                {
                    activity.SetTag("http.client_ip", request.HttpContext.Connection.RemoteIpAddress?.ToString());
                    // => Add custom tag to every HTTP request span
                };
            })
            // => Automatically creates spans for every HTTP request
            .AddHttpClientInstrumentation()
            // => Creates spans for outgoing HTTP requests (HttpClient)
            .AddEntityFrameworkCoreInstrumentation(options =>
            {
                options.SetDbStatementForText = true;
                // => Include SQL query text in database spans
                // => Disable in production if queries contain sensitive data
            })
            // => Creates spans for every EF Core database operation
            .AddConsoleExporter();
            // => Export traces to console (development)
            // => In production: .AddOtlpExporter() to send to Jaeger, Tempo, etc.
    });

var app = builder.Build();

// Custom trace spans within handlers
app.MapGet("/products/{id:int}", async (int id) =>
{
    using var activity = Activity.Current;
    // => Activity.Current is the current span created by AddAspNetCoreInstrumentation

    activity?.SetTag("product.id", id);
    // => Add custom tag to the HTTP request span
    // => Appears in trace viewer as product.id: 42

    // Simulate business logic
    using var dbActivity = new ActivitySource("products-api").StartActivity("database.lookup");
    // => Create a child span for the database operation
    dbActivity?.SetTag("db.query", $"SELECT * FROM Products WHERE Id = {id}");
    await Task.Delay(10); // Simulate DB query
    dbActivity?.Stop();
    // => Stop records the span duration in the trace

    return Results.Ok(new { Id = id, Name = $"Product {id}" });
});

app.Run();

// Install: dotnet add package OpenTelemetry.Instrumentation.Runtime
// Install: dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore

using System.Diagnostics.Metrics;
using OpenTelemetry.Metrics;

// Service with custom business metrics
public class OrderMetrics : IDisposable
{
    private readonly Meter _meter;
    private readonly Counter<long> _ordersCreated;
    // => Counter: monotonically increasing count (orders placed, errors, etc.)
    private readonly Histogram<double> _orderProcessingDuration;
    // => Histogram: distribution of values (latency, order value, etc.)
    private readonly ObservableGauge<int> _pendingOrders;
    // => ObservableGauge: snapshot of current state (queue depth, connections, etc.)

    private int _pendingOrderCount = 0;

    public OrderMetrics()
    {
        _meter = new Meter("MyApp.Orders", "1.0.0");
        // => Meter identifies the instrumentation library
        // => Name conventionally: "CompanyName.ServiceName.ComponentName"

        _ordersCreated = _meter.CreateCounter<long>(
            "orders.created",
            unit: "{orders}",
            // => Unit uses UCUM notation: {orders} is a custom unit
            description: "Total number of orders created");
        // => Metric name: orders.created; appears in Prometheus as orders_created_total

        _orderProcessingDuration = _meter.CreateHistogram<double>(
            "orders.processing_duration",
            unit: "ms",
            description: "Duration of order processing in milliseconds");
        // => Histogram generates: _count, _sum, _bucket metrics in Prometheus

        _pendingOrders = _meter.CreateObservableGauge<int>(
            "orders.pending",
            () => _pendingOrderCount,
            // => Callback called when metrics are collected (pull-based)
            unit: "{orders}",
            description: "Current number of pending orders");
    }

    public void RecordOrderCreated(string region, string tier)
    {
        _ordersCreated.Add(1,
            new KeyValuePair<string, object?>("region", region),
            // => Tag dimensions for filtering/grouping in dashboards
            new KeyValuePair<string, object?>("tier", tier));
        // => Recorded as: orders.created{region="us-east",tier="premium"}++
        Interlocked.Increment(ref _pendingOrderCount);
    }

    public void RecordProcessingComplete(double durationMs)
    {
        _orderProcessingDuration.Record(durationMs);
        // => Adds value to histogram distribution
        Interlocked.Decrement(ref _pendingOrderCount);
    }

    public void Dispose() => _meter.Dispose();
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<OrderMetrics>();
// => Singleton: metrics state shared across all requests

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics =>
    {
        metrics
            .AddMeter("MyApp.Orders")
            // => Register custom meter to collect its metrics
            .AddAspNetCoreInstrumentation()
            // => HTTP request rate, latency, error rate
            .AddRuntimeInstrumentation()
            // => .NET runtime: GC pauses, thread pool, heap size
            .AddPrometheusExporter();
            // => Expose metrics at /metrics in Prometheus format
    });

var app = builder.Build();
app.MapPrometheusScrapingEndpoint();
// => Prometheus endpoint at /metrics
// => Prometheus server scrapes this every 15-60 seconds

app.MapPost("/orders", async (OrderMetrics metrics) =>
{
    var sw = System.Diagnostics.Stopwatch.StartNew();
    metrics.RecordOrderCreated("us-east", "premium");
    // => Counter incremented with dimension tags

    await Task.Delay(Random.Shared.Next(10, 100)); // Simulate processing

    sw.Stop();
    metrics.RecordProcessingComplete(sw.Elapsed.TotalMilliseconds);
    // => Histogram records actual processing duration

    return Results.Created("/orders/1", new { Id = 1 });
});

app.Run();

using Microsoft.AspNetCore.Server.Kestrel.Core;
using System.Security.Authentication;

var builder = WebApplication.CreateBuilder(args);

// Configure Kestrel with production settings
builder.WebHost.ConfigureKestrel((context, options) =>
{
    // Limits to prevent resource exhaustion
    options.Limits.MaxConcurrentConnections = 1000;
    // => Maximum simultaneous connections; null = unlimited
    // => Set to prevent connection pool exhaustion under attack
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    // => WebSocket connections are "upgraded"; track separately
    options.Limits.MaxRequestBodySize = 10 * 1024 * 1024; // 10MB
    // => Maximum request body size; override per-endpoint for file upload
    options.Limits.RequestHeadersTimeout = TimeSpan.FromSeconds(30);
    // => Maximum time to receive request headers; prevents Slowloris attacks
    options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    // => How long to keep idle connection alive
    // => Balance: longer = more memory, shorter = more reconnections

    // HTTP/1.1 endpoint on port 5000
    options.ListenAnyIP(5000, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
        // => Accept both HTTP/1.1 (REST clients) and HTTP/2 (gRPC clients)
        // => HTTP/2 without TLS requires special client configuration
    });

    // HTTPS endpoint on port 5001 with TLS configuration
    options.ListenAnyIP(5001, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            httpsOptions.SslProtocols = SslProtocols.Tls12 | SslProtocols.Tls13;
            // => Only TLS 1.2 and 1.3; disables older insecure versions
            httpsOptions.ServerCertificateSelector = (context, hostName) =>
            {
                // => SNI-based certificate selection (Server Name Indication)
                // => Different certificate per domain on same IP/port
                if (hostName == "api.myapp.com")
                    return LoadCertificate("api.myapp.com.pfx");
                return LoadCertificate("default.pfx");
            };
        });
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
        // => HTTP/3 (QUIC) on HTTPS endpoint for latest clients
    });
});

System.Security.Cryptography.X509Certificates.X509Certificate2 LoadCertificate(string name)
{
    // In production: load from Azure Key Vault, AWS Certificate Manager, etc.
    return new System.Security.Cryptography.X509Certificates.X509Certificate2(name, "password");
}

var app = builder.Build();
app.MapGet("/", () => "Kestrel production configuration active");
app.Run();

# Dockerfile - multi-stage build for ASP.NET Core 8

# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# => SDK image includes build tools, compilers, and CLI
# => Only used during build; NOT included in final image

WORKDIR /src
# => Set working directory in container

# Copy project files first to cache NuGet restore
COPY ["MyApp.csproj", "."]
# => Copy only .csproj to leverage Docker layer caching
# => If .csproj unchanged, dotnet restore is cached
RUN dotnet restore "MyApp.csproj"
# => Restore NuGet packages; cached if .csproj unchanged

# Copy source code and build
COPY . .
# => Copy all source files
RUN dotnet build "MyApp.csproj" -c Release -o /app/build
# => -c Release: optimize for production (no debug symbols, trim IL)
# => -o /app/build: output directory

# Stage 2: Publish (trim and optimize)
FROM build AS publish
RUN dotnet publish "MyApp.csproj" -c Release -o /app/publish \
    --no-restore \
    /p:UseAppHost=false
# => dotnet publish: creates deployable output
# => --no-restore: skip restore (already done in build stage)
# => UseAppHost=false: don't create OS-specific executable (use dotnet command)

# Stage 3: Runtime (minimal production image)
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
# => aspnet image: .NET runtime only (not SDK)
# => Much smaller than SDK image (~200MB vs ~700MB)
# => Does not include build tools, compiler, or CLI

WORKDIR /app

# Security: run as non-root user
USER app
# => Switch to non-root user before copying files
# => app user pre-created in aspnet base image with restricted permissions

COPY --from=publish /app/publish .
# => Copy published output from publish stage
# => Only application files; build tools excluded from final image

# Expose port for documentation (does not publish port)
EXPOSE 8080
# => EXPOSE documents the intended port; actual port binding happens at docker run

# Health check for container orchestrators
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8080/health/live || exit 1
# => Docker/Kubernetes uses this to detect unhealthy containers
# => --start-period=5s: give app time to start before checking

ENTRYPOINT ["dotnet", "MyApp.dll"]
# => Start the ASP.NET Core application
# => dotnet MyApp.dll uses the runtime from aspnet base image

// Program.cs - Configure for containerized deployment
var builder = WebApplication.CreateBuilder(args);

// Configure port from environment (12-factor app pattern)
builder.WebHost.UseUrls(
    Environment.GetEnvironmentVariable("ASPNETCORE_URLS") ?? "http://+:8080");
// => ASPNETCORE_URLS env var overrides default port
// => http://+:8080 means listen on all interfaces, port 8080
// => Kubernetes sets this via container env vars

var app = builder.Build();
app.MapHealthChecks("/health/live");
app.MapGet("/", () => "Container running");
app.Run();

// Install: dotnet add package Asp.Versioning.Http (for minimal APIs)
// Install: dotnet add package Asp.Versioning.Mvc (for controllers)

using Asp.Versioning;
using Asp.Versioning.Builder;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // => Default version when client does not specify: v1.0
    options.AssumeDefaultVersionWhenUnspecified = true;
    // => Unversioned requests get the default version (backward compatible)
    options.ReportApiVersions = true;
    // => Add api-supported-versions and api-deprecated-versions headers to every response
    // => Clients can discover available versions from response headers
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        // => /api/v1/products - URL segment versioning (most visible)
        new QueryStringApiVersionReader("api-version"),
        // => /api/products?api-version=1.0 - query string versioning
        new HeaderApiVersionReader("X-API-Version")
        // => X-API-Version: 1.0 header versioning
        // => Combine: tries all three; first match wins
    );
});

var app = builder.Build();
var apiGroup = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    // => Declare that version 1.0 exists
    .HasApiVersion(new ApiVersion(2, 0))
    // => Declare that version 2.0 exists
    .HasDeprecatedApiVersion(new ApiVersion(0, 9))
    // => Version 0.9 is deprecated (still works, triggers warning header)
    .ReportApiVersions()
    .Build();

// Version 1 endpoint
var v1 = app.MapGroup("/api/v{version:apiVersion}/products")
    .WithApiVersionSet(apiGroup)
    .MapToApiVersion(new ApiVersion(1, 0));
// => This group handles requests for version 1.0

v1.MapGet("/", () =>
{
    return Results.Ok(new[] { new { Id = 1, Name = "Widget" } });
    // => V1 response: basic product fields
    // => GET /api/v1/products
});

// Version 2 endpoint - richer response
var v2 = app.MapGroup("/api/v{version:apiVersion}/products")
    .WithApiVersionSet(apiGroup)
    .MapToApiVersion(new ApiVersion(2, 0));
// => This group handles requests for version 2.0

v2.MapGet("/", () =>
{
    return Results.Ok(new[] { new
    {
        Id = 1,
        Name = "Widget",
        Sku = "WDG-001",
        // => V2 adds SKU and category (new in v2)
        Category = "Electronics"
    }});
    // => GET /api/v2/products - extended response
});

app.Run();

using Microsoft.AspNetCore.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails(options =>
{
    // Customize problem details for specific exception types
    options.CustomizeProblemDetails = ctx =>
    {
        // Add request correlation ID to all problem details responses
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
        // => traceId in every error response for support correlation

        ctx.ProblemDetails.Extensions["requestPath"] = ctx.HttpContext.Request.Path.Value;
        // => Include request path for easier log correlation

        // Add more context for 500 errors in development
        if (ctx.Exception is not null && ctx.HttpContext.RequestServices
            .GetRequiredService<IWebHostEnvironment>().IsDevelopment())
        {
            ctx.ProblemDetails.Extensions["exceptionType"] = ctx.Exception.GetType().Name;
            // => exceptionType: "InvalidOperationException" (development only)
            ctx.ProblemDetails.Extensions["exceptionMessage"] = ctx.Exception.Message;
            // => exceptionMessage: "..." (development only - never in production)
        }
    };
});

var app = builder.Build();

// UseExceptionHandler with problem details integration
app.UseExceptionHandler();
// => When AddProblemDetails registered, UseExceptionHandler produces problem JSON
// => All unhandled exceptions => RFC 9457 problem details response

app.UseStatusCodePages();
// => 404 for unknown routes, 405 Method Not Allowed => problem details JSON

app.MapGet("/products/{id:int}", (int id, IProblemDetailsService problemDetailsService, HttpContext context) =>
{
    if (id <= 0)
    {
        // Explicit problem details with custom type
        context.Response.StatusCode = 400;
        return problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = context,
            ProblemDetails = new Microsoft.AspNetCore.Mvc.ProblemDetails
            {
                Type = "https://api.example.com/problems/invalid-id",
                Title = "Invalid Product ID",
                Status = 400,
                Detail = $"Product ID must be positive, got: {id}"
            }
        }).AsTask().ContinueWith(_ => Results.Empty);
        // => Returns problem details JSON with custom type URI
    }

    if (id > 1000)
        throw new InvalidOperationException("Database connection failed");
    // => Unhandled exception => UseExceptionHandler catches
    // => Returns 500 problem details JSON with traceId

    return Task.FromResult(Results.Ok(new { Id = id }));
});

app.Run();

var builder = WebApplication.CreateBuilder(args);

// Define interface and multiple implementations
public interface IPaymentProcessor
{
    Task<string> ProcessAsync(decimal amount);
}

public class StripePaymentProcessor : IPaymentProcessor
{
    public async Task<string> ProcessAsync(decimal amount)
    {
        await Task.Delay(50); // Simulate API call
        return $"Stripe: processed ${amount:F2}";
        // => Returns Stripe transaction ID format
    }
}

public class PayPalPaymentProcessor : IPaymentProcessor
{
    public async Task<string> ProcessAsync(decimal amount)
    {
        await Task.Delay(75); // Simulate API call
        return $"PayPal: processed ${amount:F2}";
        // => Returns PayPal transaction reference format
    }
}

// Register keyed services - .NET 8 feature
builder.Services.AddKeyedScoped<IPaymentProcessor, StripePaymentProcessor>("stripe");
// => "stripe" is the service key - used to resolve specific implementation
builder.Services.AddKeyedScoped<IPaymentProcessor, PayPalPaymentProcessor>("paypal");
// => "paypal" key resolves PayPalPaymentProcessor

var app = builder.Build();

// Resolve keyed service in minimal API
app.MapPost("/payments/{provider}", async (
    string provider,
    PaymentRequest request,
    [FromKeyedServices("stripe")] IPaymentProcessor stripeProcessor,
    // => [FromKeyedServices] resolves the implementation with key "stripe"
    IServiceProvider serviceProvider) =>
{
    IPaymentProcessor processor;

    if (provider == "stripe")
        processor = stripeProcessor;
    else if (provider == "paypal")
        processor = serviceProvider.GetRequiredKeyedService<IPaymentProcessor>("paypal");
        // => GetRequiredKeyedService<T>(key) resolves keyed service dynamically
    else
        return Results.BadRequest($"Unknown payment provider: {provider}");

    var result = await processor.ProcessAsync(request.Amount);
    // => Delegates to the correct payment implementation
    return Results.Ok(new { Provider = provider, Result = result });
});

record PaymentRequest(decimal Amount);
app.Run();

// Service that manages an expensive, disposable resource
public class ReportGeneratorService : IDisposable, IAsyncDisposable
{
    private readonly ILogger<ReportGeneratorService> _logger;
    private bool _disposed = false;
    // => Track disposal state to prevent use-after-dispose

    // Expensive resource that must be released
    private readonly System.IO.MemoryStream _buffer;

    public ReportGeneratorService(ILogger<ReportGeneratorService> logger)
    {
        _logger = logger;
        _buffer = new System.IO.MemoryStream(capacity: 1024 * 1024); // 1MB buffer
        // => Allocate 1MB buffer on construction
        // => Must release this when service is done
        _logger.LogInformation("ReportGeneratorService created with 1MB buffer");
    }

    public async Task<byte[]> GenerateReportAsync(string reportType)
    {
        ObjectDisposedException.ThrowIf(_disposed, nameof(ReportGeneratorService));
        // => Guard against use after disposal
        // => ObjectDisposedException is the correct exception for this scenario

        _buffer.SetLength(0); // Reset buffer for new report
        // => Reuse buffer instead of allocating new one per report

        var reportData = System.Text.Encoding.UTF8.GetBytes($"Report: {reportType}\nGenerated: {DateTime.UtcNow}");
        await _buffer.WriteAsync(reportData);
        // => Write report content to buffer

        return _buffer.ToArray();
        // => Return buffer contents as byte array
    }

    // Synchronous disposal
    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
        // => Tell GC not to call finalizer (already cleaned up)
    }

    protected virtual void Dispose(bool disposing)
    {
        if (!_disposed)
        {
            if (disposing)
            {
                _buffer.Dispose();
                // => Release managed resource (MemoryStream)
                _logger.LogInformation("ReportGeneratorService disposed");
            }
            _disposed = true;
        }
    }

    // Async disposal (preferred for async cleanup)
    public async ValueTask DisposeAsync()
    {
        await _buffer.DisposeAsync();
        // => DisposeAsync for async resource cleanup (flush, close)
        GC.SuppressFinalize(this);
    }
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<ReportGeneratorService>();
// => Scoped: created per request, DISPOSED at end of request automatically
// => DI container calls Dispose()/DisposeAsync() when scope ends

var app = builder.Build();

app.MapGet("/reports/{type}", async (string type, ReportGeneratorService generator) =>
{
    var bytes = await generator.GenerateReportAsync(type);
    // => Generator Dispose() called by DI container when request ends
    // => 1MB buffer released back to memory pool
    return Results.File(bytes, "application/pdf", $"{type}-report.pdf");
});

app.Run();

using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Configure graceful shutdown timeout
builder.Host.ConfigureHostOptions(options =>
{
    options.ShutdownTimeout = TimeSpan.FromSeconds(30);
    // => Wait up to 30 seconds for active requests to complete
    // => Default is 5 seconds; increase for slow operations (DB transactions, file uploads)
    // => After timeout: force shutdown regardless of active requests
});

var app = builder.Build();

// Access application lifetime events
var lifetime = app.Lifetime;
// => IHostApplicationLifetime provides shutdown notification

lifetime.ApplicationStarted.Register(() =>
    app.Logger.LogInformation("Application started at {Time}", DateTime.UtcNow));
// => Fires when application is fully started and accepting requests

lifetime.ApplicationStopping.Register(() =>
    app.Logger.LogInformation("Application stopping - draining requests"));
// => Fires when SIGTERM received; requests still processing
// => Register cleanup logic here: stop accepting new work, drain queues

lifetime.ApplicationStopped.Register(() =>
    app.Logger.LogInformation("Application stopped at {Time}", DateTime.UtcNow));
// => Fires when all cleanup complete; no more requests

// Long-running endpoint that demonstrates graceful shutdown
app.MapPost("/process", async (HttpContext context) =>
{
    using var cts = CancellationTokenSource.CreateLinkedTokenSource(
        context.RequestAborted);
    // => context.RequestAborted fires when client disconnects
    // => CreateLinkedTokenSource also fires on shutdown

    try
    {
        // Simulate a database transaction that should not be interrupted
        app.Logger.LogInformation("Processing started");
        await Task.Delay(TimeSpan.FromSeconds(5), cts.Token);
        // => 5-second operation; cancelled if shutdown occurs during this
        app.Logger.LogInformation("Processing completed");
        return Results.Ok("Processed");
    }
    catch (OperationCanceledException)
    {
        app.Logger.LogWarning("Processing cancelled due to shutdown");
        return Results.StatusCode(503);
        // => 503 Service Unavailable: request was in progress during shutdown
        // => Client can retry after deployment completes
    }
});

app.Run();
// => On SIGTERM (Kubernetes scale-down or pod eviction):
// => 1. ApplicationStopping fires immediately
// => 2. Kestrel stops accepting new connections
// => 3. Waits up to ShutdownTimeout for active requests
// => 4. ApplicationStopped fires
// => 5. Process exits with code 0

// Endpoint filter for request idempotency enforcement
public class IdempotencyFilter : IEndpointFilter
{
    private static readonly HashSet<string> ProcessedKeys = new();
    // => In production: use Redis to share across instances and persist

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var httpContext = context.HttpContext;

        // Check for idempotency key header
        var idempotencyKey = httpContext.Request.Headers["Idempotency-Key"].FirstOrDefault();
        // => Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
        // => Clients send unique key per logical operation

        if (idempotencyKey is null)
            return await next(context);
        // => No key provided: process normally (not enforcing idempotency)

        if (ProcessedKeys.Contains(idempotencyKey))
        {
            // Already processed: return cached response
            httpContext.Response.StatusCode = 200;
            httpContext.Response.Headers["X-Idempotent-Replayed"] = "true";
            // => Header signals to client this is a replayed response
            return Results.Ok(new { Message = "Already processed", Key = idempotencyKey });
            // => Return same logical result without re-processing
        }

        // Process the request
        var result = await next(context);
        // => Execute the actual route handler

        // Mark as processed
        ProcessedKeys.Add(idempotencyKey);
        // => In production: store in Redis with expiration (e.g., 24 hours)

        return result;
    }
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Apply idempotency filter to payment endpoint
app.MapPost("/payments", (PaymentRequest req) =>
    Results.Created("/payments/1", new { Id = 1, req.Amount }))
    .AddEndpointFilter<IdempotencyFilter>();
// => AddEndpointFilter<T> adds filter to this specific endpoint
// => First POST with key => processes and records key
// => Second POST with same key => returns cached 200 without processing

// Chain multiple filters (executed in registration order)
app.MapPost("/orders", (object order) =>
    Results.Created("/orders/1", order))
    .AddEndpointFilter<IdempotencyFilter>()
    .AddEndpointFilter(async (context, next) =>
    {
        // Inline filter: add processing timestamp to response
        var result = await next(context);
        context.HttpContext.Response.Headers["X-Processed-At"] =
            DateTime.UtcNow.ToString("O");
        // => ISO 8601 timestamp on every response
        return result;
    });

record PaymentRequest(decimal Amount, string Currency);
app.Run();

// WebApplication.CreateSlimBuilder - minimal feature set for microservices
// Use when targeting AOT (Ahead-of-Time) compilation or minimal containers

var builder = WebApplication.CreateSlimBuilder(args);
// => CreateSlimBuilder omits features not needed for minimal API servers:
// => - No IIS integration (IISIntegration removed)
// => - No HTTPS certificate development tool
// => - No UseStaticFiles (add explicitly if needed)
// => - Registers minimal set of middleware
// => Results in smaller publish size and faster startup

// Configure JSON for AOT-compatible serialization
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
    // => AOT requires explicit type info; TypeInfoResolverChain provides it
    // => AppJsonSerializerContext.Default is source-generated (see below)
});

var app = builder.Build();

app.MapGet("/products", () => new[] { new Product(1, "Widget"), new Product(2, "Gadget") });
// => Returns JSON; serialized via source-generated serializer (AOT compatible)

app.MapPost("/products", (Product product) =>
{
    // => Product deserialized from JSON request body
    // => Source-generated deserializer: no runtime reflection
    return Results.Created($"/products/{product.Id}", product);
});

app.Run();

// Source-generated JSON serializer context
[System.Text.Json.Serialization.JsonSerializable(typeof(Product))]
[System.Text.Json.Serialization.JsonSerializable(typeof(Product[]))]
// => [JsonSerializable] registers types for AOT-compatible code generation
// => Compiler generates serialization/deserialization code at build time
// => Eliminates System.Text.Json reflection at runtime
internal partial class AppJsonSerializerContext : System.Text.Json.Serialization.JsonSerializerContext {}

record Product(int Id, string Name);

// Install: dotnet add package Microsoft.Extensions.Caching.Hybrid

using Microsoft.Extensions.Caching.Hybrid;

var builder = WebApplication.CreateBuilder(args);

// Register HybridCache (requires .NET 9 / Microsoft.Extensions.Caching.Hybrid)
builder.Services.AddHybridCache(options =>
{
    options.MaximumPayloadBytes = 1024 * 1024; // 1MB max per entry
    // => Entries larger than this are not cached
    options.MaximumKeyLength = 512;
    // => Maximum cache key string length
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(5),
        // => L2 (distributed) cache expiration
        LocalCacheExpiration = TimeSpan.FromMinutes(1)
        // => L1 (in-memory) cache expiration; shorter than L2
        // => L1 hit: sub-millisecond, no serialization
        // => L2 hit: Redis fetch + deserialization, few milliseconds
        // => Cache miss: handler executes, result stored in both L1 and L2
    };
});

// Also register distributed cache (Redis) for L2
builder.Services.AddStackExchangeRedisCache(options =>
    options.Configuration = builder.Configuration.GetConnectionString("Redis"));

var app = builder.Build();

app.MapGet("/products/{id:int}", async (int id, HybridCache cache, CancellationToken ct) =>
{
    var product = await cache.GetOrCreateAsync(
        key: $"product:{id}",
        // => Cache key; L1 checked first, then L2, then factory
        factory: async (key, ct) =>
        {
            // => Factory only called on cache miss (both L1 and L2)
            // => StampedeProtection: factory called ONCE even under concurrent misses
            // => All concurrent requests for same key wait for single factory execution
            await Task.Delay(100, ct); // Simulate DB query
            return new ProductDto(id, $"Product {id}", id * 9.99m);
            // => Result stored in both L1 (1 min) and L2 Redis (5 min)
        },
        cancellationToken: ct);

    return Results.Ok(product);
    // => Response time:
    // => L1 hit: < 1ms (in-process memory)
    // => L2 hit: 2-5ms (Redis fetch)
    // => Cache miss: 100ms+ (factory execution)
});

// Invalidate from both L1 and L2
app.MapDelete("/products/{id:int}/cache", async (int id, HybridCache cache, CancellationToken ct) =>
{
    await cache.RemoveAsync($"product:{id}", ct);
    // => RemoveAsync evicts from both L1 and L2 simultaneously
    return Results.NoContent();
});

record ProductDto(int Id, string Name, decimal Price);
app.Run();

using Microsoft.AspNetCore.HttpLogging;

var builder = WebApplication.CreateBuilder(args);

// Configure HTTP request/response logging
builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.All;
    // => HttpLoggingFields.All: logs method, path, headers, status, duration
    // => Use specific flags in production to avoid logging sensitive data:
    // => HttpLoggingFields.RequestMethod | HttpLoggingFields.RequestPath | HttpLoggingFields.Duration

    logging.RequestHeaders.Add("X-Correlation-Id");
    // => Include specific custom headers in logs
    logging.ResponseHeaders.Add("Content-Type");
    // => Log Content-Type in responses

    logging.RequestBodyLogLimit = 4096; // 4KB
    // => Maximum bytes of request body to log (avoid logging huge uploads)
    logging.ResponseBodyLogLimit = 4096;
    // => Maximum bytes of response body to log

    logging.CombineLogs = true;
    // => Combine request + response into single log entry
    // => Easier to correlate request and response in log viewer
});

// Customize logging per route to exclude sensitive paths
builder.Services.AddHttpLoggingInterceptor<SensitivePathInterceptor>();

var app = builder.Build();
app.UseHttpLogging();
// => Must be added before endpoints to capture request information

app.MapGet("/api/products", () => new[] { new { Id = 1 } });
// => Logged: GET /api/products 200 5ms

app.MapPost("/auth/login", () => Results.Ok("token"));
// => SensitivePathInterceptor suppresses body logging for this path

app.Run();

// Custom interceptor to suppress logging for sensitive endpoints
public class SensitivePathInterceptor : IHttpLoggingInterceptor
{
    public ValueTask OnRequestAsync(HttpLoggingInterceptorContext logContext)
    {
        // => Called before request is logged
        if (logContext.HttpContext.Request.Path.StartsWithSegments("/auth"))
        {
            logContext.Disable(HttpLoggingFields.RequestBody);
            // => Do not log request body for /auth paths (contains passwords)
        }
        return ValueTask.CompletedTask;
    }

    public ValueTask OnResponseAsync(HttpLoggingInterceptorContext logContext)
    {
        // => Called before response is logged
        if (logContext.HttpContext.Request.Path.StartsWithSegments("/auth"))
        {
            logContext.Disable(HttpLoggingFields.ResponseBody);
            // => Do not log response body for /auth (contains tokens)
        }
        return ValueTask.CompletedTask;
    }
}

// Install: dotnet add package Microsoft.Extensions.Http.Resilience

using Microsoft.Extensions.Http.Resilience;

var builder = WebApplication.CreateBuilder(args);

// Configure resilient HTTP client for external API calls
builder.Services.AddHttpClient("ExternalApi", client =>
{
    client.BaseAddress = new Uri("https://api.external.com");
    // => Base address for all requests from this named client
    client.Timeout = TimeSpan.FromSeconds(30);
    // => Overall timeout including retries
})
.AddStandardResilienceHandler(options =>
{
    // Standard resilience pipeline: retry + circuit breaker + timeout
    options.Retry.MaxRetryAttempts = 3;
    // => Retry failed requests up to 3 times
    options.Retry.Delay = TimeSpan.FromMilliseconds(200);
    // => Initial retry delay; doubled with jitter on each attempt
    options.Retry.BackoffType = Polly.DelayBackoffType.Exponential;
    // => Exponential backoff: 200ms, 400ms, 800ms between retries
    // => Prevents thundering herd when downstream is overloaded

    options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(60);
    // => Evaluate failure rate over 60-second window
    options.CircuitBreaker.FailureRatio = 0.5;
    // => Open circuit when >50% of requests fail in sampling window
    options.CircuitBreaker.MinimumThroughput = 10;
    // => Minimum requests before circuit breaker evaluates failure rate
    // => Prevents false positives on low traffic

    options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(5);
    // => Individual attempt timeout (before retry); 5s per try
});

var app = builder.Build();

app.MapGet("/weather", async (IHttpClientFactory httpClientFactory) =>
{
    var client = httpClientFactory.CreateClient("ExternalApi");
    // => Creates HttpClient with resilience pipeline from registration

    try
    {
        var response = await client.GetAsync("/weather/current");
        // => On network failure: retries up to 3 times with backoff
        // => If circuit open: fails immediately with BrokenCircuitException
        response.EnsureSuccessStatusCode();
        var weather = await response.Content.ReadAsStringAsync();
        return Results.Ok(weather);
    }
    catch (Polly.CircuitBreaker.BrokenCircuitException)
    {
        // => Circuit is open: external API is unhealthy
        return Results.StatusCode(503);
        // => 503 Service Unavailable: dependency is down
        // => Client should retry after some time
    }
});

app.Run();

// Install: dotnet add package Serilog.AspNetCore
// Install: dotnet add package Serilog.Sinks.Console
// Install: dotnet add package Serilog.Sinks.File
// Install: dotnet add package Serilog.Enrichers.Environment

using Serilog;
using Serilog.Events;

// Configure Serilog before building the host
Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    // => Global minimum log level
    .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
    // => Override: only log Warning+ from Microsoft namespace
    // => Reduces noisy framework logs in production
    .MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Information)
    // => But keep EF Core at Information to see SQL queries
    .Enrich.FromLogContext()
    // => FromLogContext: adds properties pushed with LogContext.PushProperty()
    .Enrich.WithMachineName()
    // => Adds MachineName property to every log event
    // => Essential for identifying which server produced a log in distributed systems
    .Enrich.WithEnvironmentName()
    // => Adds EnvironmentName (Development/Production) to every event
    .WriteTo.Console(
        outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}")
    // => Console output with custom template
    .WriteTo.File(
        "logs/app-.log",
        rollingInterval: RollingInterval.Day,
        // => New file each day: logs/app-20240315.log
        retainedFileCountLimit: 7,
        // => Keep 7 days of log files; older files deleted automatically
        outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{Properties:j}{NewLine}{Exception}")
    // => JSON properties appended to each file log line
    .CreateLogger();

var builder = WebApplication.CreateBuilder(args);
builder.Host.UseSerilog();
// => Replace default ILogger with Serilog implementation

var app = builder.Build();

// Request logging middleware from Serilog
app.UseSerilogRequestLogging(options =>
{
    options.MessageTemplate = "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms";
    // => Custom format for request log messages
    options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
    {
        diagnosticContext.Set("RequestHost", httpContext.Request.Host.Value);
        diagnosticContext.Set("UserAgent", httpContext.Request.Headers["User-Agent"]);
        // => Enrich request log with additional properties
    };
});

app.MapGet("/api/data", (ILogger<Program> logger) =>
{
    using (LogContext.PushProperty("OperationId", Guid.NewGuid().ToString("N")))
    {
        // => LogContext.PushProperty adds property to all logs within this using block
        logger.LogInformation("Processing data request with {OperationId}");
        // => Log: Processing data request with OperationId=abc123
        // => OperationId automatically removed from context when block exits
    }
    return Results.Ok(new { Data = "structured and enriched" });
});

app.Run();