CShells.AspNetCore

ASP.NET Core integration for CShells providing middleware and shell resolution based on HTTP context.

Purpose

This package provides ASP.NET Core middleware, shell resolution strategies, and extensions for building multi-tenant web applications with CShells.

Key Features

• HTTP middleware for shell resolution - Automatic per-request tenant/shell detection
• Host-based tenant resolution - Route requests based on hostname
• Path-based tenant resolution - Route requests based on URL path prefix
• MapShells() extension - Automatically register endpoints from all shell features
• Web routing configuration - Configure path prefixes and routing options per shell
• Custom shell resolvers - Extensibility for custom resolution strategies

Installation

dotnet add package CShells
dotnet add package CShells.AspNetCore

Quick Start

1. Create a Web Feature

using CShells.AspNetCore.Features;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

[ShellFeature("Weather", DisplayName = "Weather API")]
public class WeatherFeature : IWebShellFeature
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<IWeatherService, WeatherService>();
    }

    public void MapEndpoints(IEndpointRouteBuilder endpoints, IHostEnvironment? environment)
    {
        endpoints.MapGet("weather", (IWeatherService weatherService) =>
            weatherService.GetForecast());
    }
}

2. Configure Shells with Web Routing

{
  "CShells": {
    "Shells": {
      "Default": {
        "Features": { "Weather": {} },
        "Configuration": {
          "WebRouting": {
            "Path": ""
          }
        }
      },
      "Admin": {
        "Features": { "Admin": {} },
        "Configuration": {
          "WebRouting": {
            "Path": "admin",
            "RoutePrefix": "api/v1"
          }
        }
      }
    }
  }
}

3. Register CShells in Program.cs

Simple setup:

var builder = WebApplication.CreateBuilder(args);

// Register CShells from configuration
builder.AddShells();

var app = builder.Build();

// Configure middleware and endpoints for all shells
app.MapShells();

app.Run();

Explicit feature assembly selection:

Use From* members to select discovery sources, and WithAssemblyProvider(...) when attaching a provider that contributes assemblies.

var builder = WebApplication.CreateBuilder(args);

builder.AddShells(cshells =>
{
    cshells.WithConfigurationProvider(builder.Configuration);
    cshells.FromAssemblies(typeof(Program).Assembly);
    cshells.FromHostAssemblies();
});

var app = builder.Build();
app.MapShells();
app.Run();

If you do not call an assembly-source method, CShells uses the same host-derived feature assembly set as the default discovery behavior. Once you call FromAssemblies(...), FromHostAssemblies(), or WithAssemblyProvider(...), discovery switches to explicit provider mode and uses only the assemblies contributed by those appended providers.

Advanced setup with custom resolvers:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCShellsAspNetCore(cshells =>
{
    cshells.WithConfigurationProvider(builder.Configuration);
    cshells.WithWebRoutingResolver(options =>
    {
        options.ExcludePaths = new[] { "/api", "/health" };
        options.HeaderName = "X-Tenant-Id";
    });
});

var app = builder.Build();
app.MapShells();
app.Run();

Shell Resolution Strategies

Path-Based Resolution

Shells are resolved based on the URL path prefix:

{
  "Configuration": {
    "WebRouting": {
      "Path": "admin"
    }
  }
}

Requests to /admin/* will be routed to this shell.

Host-Based Resolution

Configure shells to respond to specific hostnames:

{
  "Configuration": {
    "WebRouting": {
      "Host": "admin.example.com"
    }
  }
}

Route Prefix

Apply a route prefix to all endpoints in a shell:

{
  "Configuration": {
    "WebRouting": {
      "Path": "tenant1",
      "RoutePrefix": "api/v1"
    }
  }
}

With this configuration, an endpoint mapped at weather will be accessible at /tenant1/api/v1/weather.

Custom Resolution

Implement IShellResolver for custom resolution logic:

public class CustomShellResolver : IShellResolver
{
    public Task<string?> ResolveShellIdAsync(HttpContext context)
    {
        // Custom logic to determine shell ID from HTTP context
        var shellId = context.Request.Headers["X-Tenant-Id"].FirstOrDefault();
        return Task.FromResult(shellId);
    }
}

builder.Services.AddCShellsAspNetCore(cshells =>
{
    cshells.WithResolver<CustomShellResolver>();
});

Web Routing Options

Configure routing behavior:

builder.Services.AddCShellsAspNetCore(cshells =>
{
    cshells.WithWebRoutingResolver(options =>
    {
        // Exclude paths from shell resolution
        options.ExcludePaths = new[] { "/api", "/health", "/swagger" };

        // Use custom header for tenant ID
        options.HeaderName = "X-Tenant-Id";

        // Configure default shell
        options.DefaultShell = "Default";
    });
});

Learn More

• Main Documentation
• Sample Application
• CShells Package - Core runtime