ASP.NET Core 2.2 Roadmap

[glennc]

We have grouped the ASP.NET Core 2.2 release into a few themes:

• APIs & Services
• Server improvements
• SignalR

Rough Schedule

We are currently planning to have 3 previews before RTM:

• August – Preview 1
• September - Preview 2
• October - Preview 3
• Before End-of-year – RTM

As with our previous roadmap posts this is what we intend right now, but it's subject to change as we continue development.

APIs and Services

The 'north star' for this version is to generate better metadata about your app and use that data to make your dev experience better and more productive. This is the main focus for 2.2.

API Controller conventions

In 2.1 we added controller specific conventions that make Web API development more convenient with the ApiController attribute. In 2.2 we want to expand on this concept to provide metadata for API Explorer and provide a better end-to-end API documentation experience.

We want to make it possible for all MVC Core applications to have a good Swagger/OpenAPI definition by default. By following common patterns, your actions will produce rich metadata without falling into 'attribute soup' where you list every possible status code that every action in your app could return. We will include a default set of conventions that match what ASP.NET Core scaffolding generations. It will also be possible to write and share your own conventions to reflect your desired contracts.

We will include a set of analyzers that will help you find cases where code that doesn't match the API Explorer metadata, and a code-fix that provides options to explicitly specify the response type metadata, create a new convention with a different pattern, or just let you write code to satisfy the convention.

As a concrete example, you could write a convention that says "every action method that starts with 'Create' will return an HTTP 201". If you wrote the following code, then you would receive a warning.

[HttpPost("/orders")]
public ActionResult<Order> CreateOrder(OrderData orderData)
{
    ....
    return Ok(new Order() {...});
}

This code doesn't match your Swagger/OpenAPI metadata (from the convention) - which says that this action returns a 201. Once you see this, you could ctrl + . to add the attributes for what we do know about this method, opting out of conventions, or you could change the code.

The analyzer will also be able to 'check your work' if you are being explicit about status codes and results using the existing attributes - it does not require you to use the conventions. Details for how this will all work can be discussed here: aspnet/Mvc#7802

Let's look at a more fleshed-out out example. The following code snippet is what is required to generate a reasonable Open API document for an action method that will get an item by ID or return a 404:

[ApiController]
public class CatalogController : ControllerBase
{
    [HttpGet]
    [Route("items/{id:int}")]
    [ProducesResponseType((int)HttpStatusCode.NotFound)]
    [ProducesResponseType(typeof(CatalogItem),(int)HttpStatusCode.OK)]
    public async Task<ActionResult<CatalogItem>> GetItemById(int id)
    {
    }
    ...
}

In 2.2 with the default conventions the following code should generate the same Open API document that the above code sample does, and this shipped analyzers will give you hints when you do something that doesn't match so you know to go and add attributes or change the conventions:

[ApiController]
public class CatalogController : ControllerBase
{
    [HttpGet]
    [Route("items/{id:int}")]
    public async Task<ActionResult<CatalogItem>> GetItemById(int id)
    {
    }
    ...
}

OpenAPI generation

With the conventions described above it will be possible for code that uses the API Explorer to generate Open API documents to be better by default, since the code you write will either follow the conventions or have attributes allowing generators to create better documents.

Dispatcher

In 2.2 we will introduce a new routing system that will expand the set of scenarios where routing is useful – tentatively called Dispatcher.

The current routing system was designed to support MVC’s historical scenarios without much thought to how routing and the composable middleware pipeline will work together. The Dispatcher is designed to run the URL matching step very early in the pipeline so that middleware can see the Endpoint that was selected as well as metadata that is associated with that endpoint. Like existing routing, the dispatcher will branch and call the actual endpoint at the end of the pipeline.

A concrete example of how this helps us is with CORS. Today there is both a CORS middleware AND a CORS feature of MVC (https://docs.microsoft.com/en-us/aspnet/core/security/cors?view=aspnetcore-2.1). Because routing information is deeply integrated with MVC we can't apply CORS policies that only apply to specific controllers until after we know what controller has been selected. However, if you also want CORS policies to apply to other parts of your pipeline then you need the middleware. This has been a source of confusion for many and we can simplify it if all of the middleware pipeline can have as much information about routing as MVC does today.

We’re also using this opportunity to make improvements to the performance of routing and dispatching for MVC and other scenarios.

HTTP API REPL tooling

Today there are no tools built into Visual Studio or the dotnet CLI to help you execute HTTP verbs against your API. We have a great language, debugger, and framework but they are somewhat limited when it's difficult to send a POST to my app to see what happens. In 2.2 we want to build a CLI experience for exploring HTTP APIs to imcrease your API inner loop productivity. The CLI builds on all the features we've talked about above as some of its advanced features, like listing all routes in your app, are enabled by consuming the metadata we have about your app via Open API documents. That means the CLI should be useful for executing any HTTP verb, but really shines when you feed it more data like Open API docs. We intend to start by shipping this as a standalone global tool while we explore its feature set and potential.

You can see a demo and description of this in Scott Hunter and Scott Hanselman's BUILD talk here: https://youtu.be/KAIJ3ezQb3c?t=18m

API client generation (C# & TypeScript)

Once you have an API with rich metadata and done exploring and testing it, then you need to go and write some client code to call and make use of your API. We are going to build an experience for generating this code based on the same data and documentation described above. We envision a few pieces for this story, one part is a dotnet tool that can generate code from an Open API document, the other is MSBuild SDK work to allow a ServiceReference to another project in a solution. That reference will cause build time client code generation to happen via the tool that can generate code. We expect this to work in a similar way to the EF Core tooling experience, where your application is built and most of your startup code executed but instead of running it we use the data we have about your code to generate a client.

Authorization Server

One of the largest gaps we’ve had has been around authorization for applications beyond a simple forms based login. We plan to fill that gap with a simple to use OpenID Connect based authorization server, which will allow your ASP.NET application to act as an authentication point for your projects, be they web site to API, SPA to API, native application to an API or, for distributed applications API to API. As we are concentrating on first party applications we can make the code you need to plumb in trivial, getting as close to zero configuration as you can, we’re not aiming to replace the excellent third-party solutions out there which enable richer scenarios like third-party applications or which provide a flexibility in configuration and authentication flow.

Server Improvements

Health Checks

This feature is a way to trivially setup an endpoint in your application that can be used to check the health of your application, potentially taking into account things like memory consumption or database availability as well as just "can I accept a HTTP request".

HTTP/2 in Kestrel & HttpClient

The title says it all in this case. HTTP/2 support for all. We started this work some time ago, and have had the protocol mostly implemented for a while but not compiled into the product since it wasn't ready. This version we will finish that work and implement the missing features.

In-proc ANCM

Running ASP.NET Core applications in-process in IIS, giving a significant performance boost.

SignalR

Add Java & C++ clients

Allow customers using Java or C++ to connect to SignalR servers, and the Azure SignalR Service.

Other

As with all releases there is a large tail of bug fixes, performance improvements, small features, and community PRs that we will also work on. You can see the full list of work by browsing the 2.2 milestones on the various repositories.

For discussion on the roadmap in general, use dotnet/aspnetcore#3265