Indiko.Hosting.Web 2.1.0

Indiko.Hosting.Web

Web API hosting implementation for building ASP.NET Core Web APIs with the Indiko framework.

Overview

This package provides a complete hosting solution for ASP.NET Core Web APIs, including standardized startup configuration, CORS policies, API versioning, caching, health checks, and seamless integration with Indiko Blocks.

Features

• Web Host Bootstrapper: Specialized bootstrapper for Web API applications
• Base Web Startup: Abstract startup class with common Web API configurations
• CORS Configuration: Environment-aware CORS policies (permissive in dev, restrictive in production)
• API Versioning: Built-in API versioning support (development environment)
• Response Caching: Configurable response caching with cache profiles
• Health Checks: Built-in health check endpoint at /healthz
• HTTPS Support: Optional HTTPS redirection and HSTS
• Forwarded Headers: Support for reverse proxy scenarios
• JSON Configuration: Reference cycle handling in JSON serialization
• Request Metadata: Service for accessing HTTP request context

Installation

dotnet add package Indiko.Hosting.Web

Quick Start

Minimal Setup

using Indiko.Hosting.Web;

// Create your startup class
public class Startup : WebStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    protected override bool AddControllersWithViews => false; // Set to true for MVC
    protected override bool EnableForwardedHeaderOptions => false;
    protected override bool ForceHttps => true;

    public override void ConfigureServices(IServiceCollection services)
    {
        base.ConfigureServices(services); // Call base first
        
        // Add your services
        services.AddScoped<IMyService, MyService>();
    }

    public override void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILoggerFactory logger)
    {
        base.Configure(app, env, logger); // Call base first
        
        // Add custom middleware if needed
    }
}

// Program.cs
class Program
{
    static async Task<int> Main(string[] args)
    {
        return await WebHostBootstrapper.Instance.RunAsync<Startup>(args);
    }
}

Configuration (appsettings.json)

{
  "AllowOrigins": "https://example.com,https://app.example.com",
  "CacheProfiles": {
    "Default": {
      "Duration": 60,
      "Location": "Any"
    },
    "Never": {
      "Duration": 0,
      "Location": "None",
      "NoStore": true
    }
  }
}

Key Components

WebHostBootstrapper

Singleton bootstrapper for Web API applications.

// Run the application
await WebHostBootstrapper.Instance.RunAsync<Startup>(args);

WebStartup

Abstract base class providing common Web API configuration.

public class MyStartup : WebStartup
{
    public MyStartup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    // Configure behavior
    protected override bool AddControllersWithViews => false;
    protected override bool EnableForwardedHeaderOptions => true; // For reverse proxy
    protected override bool ForceHttps => true; // Force HTTPS redirect
}

RequestMetadataService

Access HTTP request context information.

public class MyController : ControllerBase
{
    private readonly IRequestMetadataService _requestMetadata;

    public MyController(IRequestMetadataService requestMetadata)
    {
        _requestMetadata = requestMetadata;
    }

    [HttpGet]
    public IActionResult Get()
    {
        var userAgent = _requestMetadata.GetUserAgent();
        var ipAddress = _requestMetadata.GetClientIpAddress();
        // ...
    }
}

Features in Detail

CORS Configuration

Development Environment:

• Allows any origin, method, and header (permissive for testing)

Production Environment:

• Reads AllowOrigins from configuration
• Supports multiple origins (comma-separated)
• Enables credentials
• Supports wildcard subdomains

Response Caching

Configure cache profiles in appsettings.json:

{
  "CacheProfiles": {
    "Short": {
      "Duration": 30,
      "Location": "Any",
      "VaryByHeader": "Accept"
    },
    "Long": {
      "Duration": 3600,
      "Location": "Any"
    }
  }
}

Use in controllers:

[HttpGet]
[ResponseCache(CacheProfileName = "Short")]
public IActionResult GetData()
{
    // ...
}

API Versioning

Enabled automatically in development:

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UsersController : ControllerBase
{
    // ...
}

Health Checks

Built-in endpoint at /healthz:

curl https://your-api.com/healthz

Add custom health checks:

public override void ConfigureServices(IServiceCollection services)
{
    base.ConfigureServices(services);
    
    services.AddHealthChecks()
        .AddDbContextCheck<MyDbContext>()
        .AddUrlGroup(new Uri("https://external-api.com"), "External API");
}

Environment-Specific Behavior

Development

• Developer exception page
• Permissive CORS
• API versioning enabled
• Forwarded headers (if enabled)

Production

• HTTPS redirection
• HSTS enabled
• Configured CORS policies
• Forwarded headers (if enabled)

Target Framework

• .NET 10

Dependencies

• Indiko.Hosting.Abstractions
• Indiko.Blocks.Common.Abstractions
• Indiko.Blocks.Common.Management
• Microsoft.AspNetCore.App
• Asp.Versioning.Mvc.ApiExplorer

License

See LICENSE file in the repository root.

Related Packages

• Indiko.Hosting.Abstractions - Core hosting abstractions
• Indiko.Hosting.Mvc - MVC application hosting
• Indiko.Blocks.API.Swagger - Swagger/OpenAPI documentation
• Indiko.Blocks.API.Compression - Response compression
• Indiko.Blocks.Security.Authentication.ASPNetCore - Authentication