"Minimal hosting" for ASP.NET Core applications

[davidfowl]

Summary

We want to introduce a new "direct hosting" model for ASP.NET Core applications. This is a more focused, low ceremony way of creating a web application.

Motivation and goals

Introducing a lower ceremony replacement for the WebHost to remove some of the ceremony in hosting ASP.NET Core applications. We've received lots of feedback over the years about how much ceremony it is to get a simple API up and running and we have a chance to improve that with the deprecation of the WebHost.

In scope

• Build on the same primitives as ASP.NET Core
• Take advantage of existing ASP.NET Core middleware and frameworks built on top
• Ability to use existing extension methods on the IServiceCollection, IHostBuilder and IWebHostBuilder

Out of scope

• Changing the DI registration model
• Testability - While this is possible makes it very hard to reduce some of the ceremony

Risks / unknowns

• Having multiple ways to build a web application.
• Tools are broken
  • EF Core Tools (for example, migration) try to invoke Program.CreateHostBuilder() which no longer exists
  • Unit testing with Test Server

Strawman proposal

The idea is to reduce the number of concepts while keeping compatibility with the ecosystem we have today. Some core ideas in this new model is to:

• Reduce the number of callbacks used to configure top level things
• Expose the number of top level properties for things people commonly resolve in Startup.Configure. This allows them to avoid using the service locator pattern for IConfiguration, ILogger, IHostApplicationLifetime.
• Merge the IApplicationBuilder, the IEndpointRouteBuilder and the IHost into a single object. This makes it easy to register middleware and routes without needed an additional level of lambda nesting (see the first point).
• Merge the IConfigurationBuilder, IConfiguration, and IConfigurationRoot into a single Configuration type so that we can access configuration while it's being built. This is important since you often need configuration data as part of configuring services.
• UseRouting and UseEndpoints are called automatically (if they haven't already been called) at the beginning and end of the pipeline.

public class WebApplicationBuilder
{
    public IWebHostEnvironment Environment { get; }
    public IServiceCollection Services { get; }
    public Configuration Configuration { get; }
    public ILoggingBuilder Logging { get; }

    // Ability to configure existing web host and host
    public ConfigureWebHostBuilder WebHost { get; }
    public ConfigureHostBuilder Host { get; }

    public WebApplication Build();
}

public class Configuration : IConfigurationRoot, IConfiguration, IConfigurationBuilder { }

// The .Build() methods are explicitly implemented interface method that throw NotSupportedExceptions
public class ConfigureHostBuilder : IHostBuilder { }
public class ConfigureWebHostBuilder : IWebHostBuilder { }

public class WebApplication : IHost, IApplicationBuilder, IEndpointRouteBuilder, IAsyncDisposable
{
    // Top level properties to access common services
    public ILogger Logger { get; }
    public IEnumerable<string> Addresses { get; }
    public IHostApplicationLifetime Lifetime { get; }
    public IServiceProvider Services { get; }
    public IConfiguration Configuration { get; }
    public IWebHostEnvironment Environment { get; }

    // Factory methods
    public static WebApplication Create(string[] args);
    public static WebApplication Create();
    public static WebApplicationBuilder CreateBuilder();
    public static WebApplicationBuilder CreateBuilder(string[] args);

    // Methods used to start the host
    public void Run(params string[] urls);
    public void Run();
    public Task RunAsync(params string[] urls);
    public Task RunAsync(CancellationToken cancellationToken = default);
    public Task StartAsync(CancellationToken cancellationToken = default);
    public Task StopAsync(CancellationToken cancellationToken = default);

    public void Dispose();
    public ValueTask DisposeAsync();
}

Examples

Hello World

using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

var app = WebApplication.Create(args);

app.MapGet("/", async http =>
{
    await http.Response.WriteAsync("Hello World");
});

await app.RunAsync();

Hello MVC

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();

await app.RunAsync();

public class HomeController
{
    [HttpGet("/")]
    public string HelloWorld() => "Hello World";
}

Integrated with 3rd party ASP.NET Core based frameworks (Carter)

using Carter;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCarter();

var app = builder.Build();

app.Listen("http://localhost:3000");

app.MapCarter();

await app.RunAsync();

public class HomeModule : CarterModule
{
    public HomeModule()
    {
        Get("/", async (req, res) => await res.WriteAsync("Hello from Carter!"));
    }
}

More complex, taking advantage of the existing ecosystem of extension methods

using System.Threading.Tasks;
using Autofac;
using Autofac.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Serilog;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddYamlFile("appsettings.yml", optional: true);

builder.Host.UseSerilog((context, configuration)
    => configuration
        .Enrich
        .FromLogContext()
        .WriteTo
        .Console()
    );

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

builder.Host.ConfigureContainer<ContainerBuilder>(b =>
{
    // Register services using Autofac specific methods here
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

app.MapGet("/", async http =>
{
    await http.Response.WriteAsync("Hello World");
});

await app.RunAsync("http://localhost:3000");

cc @LadyNaggaga @halter73 @shirhatti

[gfoidl]

For MVC why not

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;

var app = WebApplication.CreateMvc(args);

await app.RunAsync();

public class HomeController
{
    [HttpGet("/")]
    public string HelloWorld() => "Hello World";
}

where CreateMvc does the necessary steps?
The app could be configured further.

Looking through "beginner eyes":

• Why do I need to create a "builder" and what is a builder?
• Why do I need to get "services" and add "controllers" which I need to map then?

[davidfowl]

I don't think it scales well. You need to undo CreateMvc or create more concepts if you want to do anything (like adding other features, or setting configuration options, or configuring pretty much anything). The key to this is not just making it simple to start but simple to grow up. We don't want to fork the framework concepts of ideas or make something that doesn't work with the existing ecosystem. That's why its super important to design something right in the middle that achieves the code brevity and reduces the concept count at the same time.

Now we could consider including AddControllers and MapControllers in Create or CreateBuilder. My only problem with that is that MVC scans assemblies by default which I think is unintuitive for this scenario.

[gfoidl]

reduces the concept count at the same time

The current proposal for MVC adds builder, services and controllers.
This should be abstracted away.

undo CreateMvc or create more concepts if you want to do anything (like adding other features, or setting configuration options, or configuring pretty much anything)

Good point. So maybe make CreateMvc as sugar-extension for fast start, when only MVC-controllers are needed?

[davidfowl]

One of the goals is to reduce "unlearning". That is, the amount of code you need to undo once you need to do something additive. Also The MVC name doesn't mean much, o don't think it needs to be in the method. We'll experiment with what on by default would mean

[Tratcher]

We'll have to figure out what to do with tools like EF migrations and WebApplicationFactory that depend on the current Program.CreateHostBuilder pattern.

[davidfowl]

We'll have to figure out what to do with tools like EF migrations and WebApplicationFactory that depend on the current Program.CreateHostBuilder pattern.

I'm not sure those are in scope (that's why testing is out of scope in the description above), or better put, we have to make a tradeoff somewhere and I'm ok if that's what needs to be traded off.

[Tratcher]

Would we change the templates to use this new pattern? It would be problematic if EF migrations didn't work in the templates.

[Tratcher]

Also, even for non-template scenarios, we should at least update the migration tool to recognize the new scenario enough to give a better error message.

[davidfowl]

Would we change the templates to use this new pattern? It would be problematic if EF migrations didn't work in the templates.

Undecided, I would like to but there are obviously problems beyond EF migrations (and other tools like it).

Also, even for non-template scenarios, we should at least update the migration tool to recognize the new scenario enough to give a better error message.

I think it does this today, if not, it should since that method can be easily removed.

Thanks for contacting us.
We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We will evaluate the request when we are planning the work for the next milestone. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[pranavkm]

API Review:

• public IWebHostBuilder Server { get; } -> WebHost
• Configuration - Should this move to the runtime repo? Maybe add IConfigurationBuilder.Peek()
• Missing IAsyncDisposable.DisposeAsync