DRN.Framework.Hosting 0.7.0-preview058

DRN.Framework.Hosting

DRN.Framework.Hosting provides the application shell for DRN web applications. It abstracts away the boilerplate of configuring reliable, secure, and observable ASP.NET Core applications.

Table of Contents

• TL;DR
• Directory Structure
• QuickStart
• Lifecycle & Execution Flow
• DrnProgramBase Deep Dive
• Configuration
• Security Features
• Endpoint Management
• Razor TagHelpers
• Local Development
• Global Usings

TL;DR

• Secure by Default: Enforces MFA, strict CSP with Nonces, and HSTS automatically.
• Opinionated Startup: DrnProgramBase creates a predictable lifecycle for all services.
• Type-Safe Routing: Replaces "magic strings" with typed Endpoint and Page accessors.
• Frontend Synergy: Includes TagHelpers for Vite integration and secure asset loading.

Directory Structure

DRN.Framework.Hosting/
├── DrnProgram/       # DrnProgramBase, options, conventions
├── Endpoints/        # EndpointCollectionBase, EndpointForBase
├── Auth/             # Policies, MFA configuration
├── Middlewares/      # HttpScopeLogger, security middlewares
├── TagHelpers/       # Razor TagHelpers (Script, CSP, etc.)
└── wwwroot/          # Static files (JS/CSS)

QuickStart

1. Basic Program

All DRN web apps inherit from DrnProgramBase<TProgram> to inherit the lifecycle hooks and default behaviors.

using DRN.Framework.Hosting.DrnProgram;

namespace Sample.Hosted;

public class Program : DrnProgramBase<Program>, IDrnProgram
{
    // Entry Point
    public static async Task Main(string[] args) => await RunAsync(args);

    // Service Registration
    protected override Task AddServicesAsync(WebApplicationBuilder builder, IAppSettings appSettings, IScopedLog scopedLog)
    {
        builder.Services.AddSampleInfraServices();
        builder.Services.AddSampleApplicationServices();
        return Task.CompletedTask;
    }
}

2. Testing Integration

You can easily test your application using DRN.Framework.Testing.

[Theory, DataInline]
public async Task StatusController_Should_Return_Status(DrnTestContext context, ITestOutputHelper outputHelper)
{
  // Arrange: Create authenticated client for the Program
  var client = await context.ApplicationContext.CreateClientAsync<Program>(outputHelper);
  var status = await client.GetFromJsonAsync<ConfigurationDebugViewSummary>("Status");
  status?.ApplicationName.Should().Be("Sample.Hosted");
}

Lifecycle & Execution Flow

DrnProgramBase orchestrates the application startup to ensure security headers, logging scopes, and validation logic run in the correct order.

graph TD
    Start["RunAsync()"] --> CAB["CreateApplicationBuilder()"]
    
    subgraph "1. Builder Phase"
    CAB --> CSO["ConfigureSwaggerOptions()"]
    CAB --> CDSH["ConfigureDefaultSecurityHeaders()"]
    CAB --> ASA["AddServicesAsync()"]
    end

    ASA --> ABC["ApplicationBuilderCreatedAsync"]
    ABC --> Build["builder.Build()"]
    
    subgraph "2. Application Phase"
    Build --> CA["ConfigureApplication()"]
    CA --> CAPS["ConfigureApplicationPipelineStart() (HSTS/Headers)"]
    CA --> LOG["HttpScopeMiddleware (TraceId)"]
    CA --> UR["UseRouting()"]
    CA --> UA["UseAuthorization()"]
    CA --> MAE["MapApplicationEndpoints()"]
    end

    MAE --> ABA["ApplicationBuiltAsync"]
    ABA --> VE["ValidateEndpoints()"]
    VE --> VSA["ValidateServicesAsync()"]
    VSA --> Run["application.RunAsync()"]

DrnProgramBase Deep Dive

This section details every overrideable hook and internal behavior of the base class.

1. Configuration Hooks (Protected Virtual)

Override these methods to customize specific subsystems without breaking the overall logical flow.

2. Pipeline Hooks

These methods insert middleware into key slots of the request pipeline.

3. Internal Wiring (Automatic)

• Service Validation: Calls ValidateServicesAsync to scan [Attribute]-registered services and ensure they are resolvable at startup.
• Secure JSON: Enforces HtmlSafeWebJsonDefaults to prevent XSS via JSON serialization.
• Endpoint Accessor: Registers IEndpointAccessor for typed access to EndpointCollectionBase.

4. Properties

Configuration

Layering

1. appsettings.json
2. appsettings.{Environment}.json
3. User Secrets (Development only)
4. Environment Variables (ASPNETCORE_, DOTNET_)
5. Mounted Directories (e.g. /app/config)
6. Command Line Arguments

Reference Configurations

NLog (Logging)

Standard configuration for Console and Graylog output.

{
  "NLog": {
    "throwConfigExceptions": true,
    "targets": {
      "async": true,
      "console": {
        "type": "Console",
        "layout": "${longdate}|${level:uppercase=true}|${logger}|${message} ${exception:format=tostring}"
      }
    },
    "rules": [
      { "logger": "*", "minLevel": "Info", "writeTo": "console" }
    ]
  }
}

Kestrel (Server)

{
  "Kestrel": {
    "EndpointDefaults": { "Protocols": "Http1" },
    "Endpoints": {
      "All": { "Url": "http://*:5988" }
    }
  }
}

Security Features

DRN Hosting enforces "Security by Default":

1. MFA by Default (Fail-Closed)

The FallbackPolicy is set to require MFA. Any controller not marked with [AllowAnonymous] or [Authorize(Policy = AuthPolicy.MfaExempt)] will reject requests without a verified MFA session. Configured in ConfigureAuthorizationOptions by setting FallbackPolicy.

2. Content Security Policy (CSP)

• Nonce-based: A cryptographic nonce is generated per request.
• TagHelpers: The NonceTagHelper automatically injecting nonce="{current_nonce}" into scripts and styles.

3. Strict Headers

• Strict-Transport-Security (HSTS)
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Referrer-Policy: strict-origin-when-cross-origin

4. GDPR Compliance

• Built-in consent cookie SameSite=Strict.

Opting-Out

// Public landing page
[AllowAnonymous]
public class HomeController : Controller { ... }

// Login Page (Single Factor Allowed)
[Authorize(Policy = AuthPolicy.MfaExempt)]
public class LoginController : Controller { ... }

Endpoint Management

Avoid "magic strings" for routes. Use EndpointCollectionBase and PageCollectionBase for type-safe endpoint references.

// Usage in Code
ApiEndpoint endpoint = Get.Endpoint.User.Login;
string url = endpoint.Path();

Razor TagHelpers

Local Development Infrastructure

Use DRN.Framework.Testing to provision infrastructure (Postgres, RabbitMQ) during local development.

Setup

1. Add Conditional Reference:

   <ItemGroup Condition="'$(Configuration)' == 'Debug'">
       <ProjectReference Include="..\DRN.Framework.Testing\DRN.Framework.Testing.csproj" />
   </ItemGroup>
   

2. Configure Startup Actions:

   #if DEBUG
   public class SampleProgramActions : DrnProgramActions
   {
       public override async Task ApplicationBuilderCreatedAsync<TProgram>(
           TProgram program, WebApplicationBuilder builder,
           IAppSettings appSettings, IScopedLog scopedLog)
       {
           // Auto-starts containers if not running
           await builder.LaunchExternalDependenciesAsync(scopedLog, appSettings);
       }
   }
   #endif
   

Global Usings

Standard global usings for Hosted applications:

global using DRN.Framework.Hosting.DrnProgram;
global using DRN.Framework.Hosting.Endpoints;
global using DRN.Framework.Utils.DependencyInjection;
global using Microsoft.AspNetCore.Mvc;

Semper Progressivus: Always Progressive

Commit Info

Author: Duran Serkan KILIÇ
Date: 2026-01-25 19:57:06 +0300
Hash: f166fafb824fc08532b5c8d4c1f34b8786eb2300