IceCoffee.AspNetCore 2.0.1

IceCoffee.AspNetCore

A lightweight, opinionated ASP.NET Core library that provides a StartupBase class and a set of utilities to bootstrap web API applications with sensible defaults — authentication, Swagger (NSwag), CORS, Serilog structured logging, Mapster object mapping, and response caching — all driven by configuration flags.

Package	NuGet Stable	Downloads
IceCoffee.AspNetCore

Features

Installation

dotnet add package IceCoffee.AspNetCore

Quick Start

1. Derive from StartupBase

using IceCoffee.AspNetCore;

public class Startup : StartupBase
{
    public Startup(WebApplicationBuilder builder) : base(builder) { }

    public override void ConfigureServices(IServiceCollection services)
    {
        base.ConfigureServices(services); // apply all defaults

        // Register your own services here
        services.AddScoped<IMyService, MyService>();
    }

    public override void Configure(WebApplication app, IServiceProvider services)
    {
        base.Configure(app, services); // apply default middleware pipeline

        // Add your own middleware / endpoints here
    }
}

2. Wire it up in Program.cs

var builder = WebApplication.CreateBuilder(args);

var startup = new Startup(builder);
startup.ConfigureServices(builder.Services);

var app = builder.Build();
startup.Configure(app, app.Services);

app.Run();

Extensibility

StartupBase exposes three protected virtual hooks for the most common customisation points:

Example — replacing Basic Auth with JWT Bearer

using Microsoft.AspNetCore.Authentication.JwtBearer;
using NSwag;
using NSwag.Generation.AspNetCore;
using NSwag.Generation.Processors.Security;

public class Startup : StartupBase
{
    public Startup(WebApplicationBuilder builder) : base(builder) { }

    protected override bool ConfigureAuthentication(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddJwtBearer(options =>
                {
                    options.Authority = Configuration["Jwt:Authority"];
                    options.Audience  = Configuration["Jwt:Audience"];
                });
        // AddAuthorization() is handled by the base class automatically.
        return true;
    }

    protected override void ConfigureSwaggerSecurity(AspNetCoreOpenApiDocumentGeneratorSettings config)
    {
        config.AddSecurity("Bearer", new OpenApiSecurityScheme
        {
            Type         = OpenApiSecuritySchemeType.Http,
            Scheme       = "bearer",
            BearerFormat = "JWT"
        });
        config.OperationProcessors.Add(new OperationSecurityScopeProcessor("Bearer"));
    }
}

Configuration Reference

All flags are read from appsettings.json (or any registered IConfiguration provider).

{
  // Enable Serilog per-request HTTP logging
  "EnableRequestLog": true,

  // Mount the application under a sub-path (e.g. "/api")
  "PathBase": "",

  // Expose NSwag Swagger UI at /swagger
  "EnableSwagger": true,

  // Enable the CORS policy
  "EnableCors": true,

  // Allowed origins for CORS; omit or leave empty to allow any origin
  "AllowedOrigins": [ "https://example.com" ],

  // HTTP Basic Authentication
  "BasicAuthOptions": {
    "Enabled": false,
    "Realm": "Basic Authentication",
    "UserName": "<set via secrets / env var>",
    "Password": "<set via secrets / env var>"
  },

  // Serilog configuration (standard Serilog.AspNetCore schema)
  "Serilog": {
    "MinimumLevel": { "Default": "Information" },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.txt",
          "rollingInterval": "Day",
          "hooks": "IceCoffee.AspNetCore.SerilogHooks::ArchiveHooks, IceCoffee.AspNetCore"
        }
      }
    ]
  }
}

Security note: Never store BasicAuthOptions:UserName or BasicAuthOptions:Password in source-controlled appsettings.json. Use .NET user-secrets in development and environment variables or a secrets manager in production.

Exception detail note: feature?.Error.ToString() (full stack trace) is written to ProblemDetails.detail only when the hosting environment is Development. In all other environments detail is omitted to avoid information disclosure.

Utilities

CustomExceptionHandler

An IExceptionHandler implementation that logs every unhandled exception (including the distributed trace ID) and writes an RFC 7807 ProblemDetails 500 response. Register it alongside the built-in handler for structured per-exception log entries:

// In your Startup.ConfigureServices override:
services.AddExceptionHandler<CustomExceptionHandler>();

The detail field is populated with the full Exception.ToString() output only in the Development environment.

SerilogHooks.ArchiveHooks

A pre-built ArchiveHooks instance (180-day retention, smallest compression) ready to attach to a Serilog rolling-file sink.

DateTimeConverter

Registered globally in ConfigureServices. Serialises DateTime as yyyy-MM-ddTHH:mm:ss.fffZ; deserialises any ISO 8601 string.

HttpContextExtension

License

Copyright © 2026 IceCoffee. See LICENSE for details.