DEV Community: Andrew Lock "Sock"

Exploring the code behind IHttpClientFactory in depth

Andrew Lock "Sock" — Tue, 04 Aug 2020 10:00:00 +0000

In this post I take a look at the code in the default implementation of IHttpClientFactory in ASP.NET Core—DefaultHttpClientFactory. We'll see how it ensures that HttpClient instances created with the factory prevent socket exhaustion, while also ensuring that DNS changes are respected.

This post assumes you already have a general idea of IHttpClientFactory and what it's used for, so if it's new to you, take a look at Steve Gordon's series on IHttpClientFactory, or see the docs.

The code in this post is based on the HEAD of the master branch of https://github.com/dotnet/runtime at the time of writing, after .NET 5 preview 7. But the code hasn't changed significantly for 2 years, so I don't expect it to change much soon!

I've taken a couple of liberties with the code by removing null checks, in-lining some trivial methods, and removing some code that's tangential to this discussion. For the original code, see GitHub.

A brief overview of IHttpClientFactory

IHttpClientFactory allows you to create HttpClient instances for interacting with HTTP APIs, using best practices to avoid common issues. Before IHttpClientFactory, it was common to fall into one of two traps when creating HttpClient instances:

Create and dispose of new HttpClient instances as required. This can lead to socket exhaustion due to the TIME_WAIT period required after closing a connection.
Create a singleton HttpClient for the lifetime of the application. This can lead to issues when the DNS record for the HTTP API you're using changes—the changes will not be respected by the HttpClient.

IHttpClientFactory was added in .NET Core 2.1, and solves this issue by separating the management of HttpClient, from the the HttpMessageHandler chain that is used to send the message. In reality, it is the lifetime of the HttpClientHandler at the end of the pipeline that is the important thing to manage, as this is the handler that actually makes the connection

In addition to simply managing the handler lifetimes, IHttpClientFactory also makes it easy to customise the generated HttpClient and message handler pipeline using an IHttpClientBuilder. This allows you to "pre-configure" a named of typed HttpClient that is created using the factory, for example to set the base address or add default headers:

public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient("github", c =>
    {
        c.BaseAddress = new Uri("https://api.github.com/");
    })
    .ConfigureHttpClient(c => 
    {
        c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
        c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample");
    });
}

You can add multiple configuration functions at the HttpClient level, but you can also add additional HttpMessageHandlers to the pipeline. Steve shows how you can create your own handlers in in his series. To add message handlers to a named client, use IHttpClientBuilder.AddHttpMessageHandler<>, and register the handler with the DI container:

public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient("github", c =>
    {
        c.BaseAddress = new Uri("https://api.github.com/");
    })
    .AddHttpMessageHandler<TimingHandler>() // This handler is on the outside and executes first on the way out and last on the way in.
    .AddHttpMessageHandler<ValidateHeaderHandler>(); // This handler is on the inside, closest to the request.

    // Add the handlers to the service collection
    services.AddTransient<TimingHandler>();
    services.AddTransient<ValidateHeaderHandler>();
}

When you call ConfigureHttpClient() or AddHttpMessageHandler() to configure your HttpClient, you're actually adding configuration messages to a named IOptions instance, HttpClientFactoryOptions. You can read more about named options here, but the details aren't too important for this post.

That handles configuring the IHttpClientFactory. To use the factory, and create an HttpClient, you first obtain an instance of the singleton IHttpClientFactory, and then you call CreateClient(name), providing the name of the client to create.

If you don't provide a name to CreateClient(), the factory will use the default name, "" (the empty string).

public class MyService
{
    // IHttpClientFactory is a singleton, so can be injected everywhere
    private readonly IHttpClientFactory _factory;
    public MyService(IHttpClientFactory factory)
    {
        _factory = factory;
    }

    public async Task DoSomething()
    {
        // Get an instance of the typed client
        HttpClient client = _factory.CreateClient("github");

        // Use the client...
    }
}

The remainder of this post focus on what happens behind the scenes when you call CreateClient().

Creating an HttpClient and HttpMessageHandler

The CreateClient() method, shown below, is how you typically interact with the IHttpClientFactory. I discuss this method below.

// Injected in constructor
private readonly IOptionsMonitor<HttpClientFactoryOptions> _optionsMonitor

public HttpClient CreateClient(string name)
{
    HttpMessageHandler handler = CreateHandler(name);
    var client = new HttpClient(handler, disposeHandler: false);

    HttpClientFactoryOptions options = _optionsMonitor.Get(name);
    for (int i = 0; i < options.HttpClientActions.Count; i++)
    {
        options.HttpClientActions[i](client);
    }

    return client;
}

This is a relatively simple method on the face of it. We start by creating the HttpMessageHandler pipeline by calling CreateHandler(name), and passing in the name of the client to create. We'll look into that method shortly, as it's where most of the magic happens around handler pooling and lifetimes.

Once you have a handler, a new instance of HttpClient is created and passed to the handler. The important thing to note is the disposeHandler: false argument. This ensures that disposing the HttpClient doesn't dispose the handler pipeline, as the IHttpClientFactory will handle that itself.

Finally, the latest HttpClientFactoryOptions for the named client are fetched from the IOptionsMonitor instance. This contains the configuration functions for the HttpClient that were added in Startup.ConfigureServices(), and sets things like the BaseAddress and default headers.

I discussed using IOptionsMonitor in a previous post. It is useful when you want to load named options in a singleton context, where you can't use the simpler IOptionsSnapshot interface. It also has other change-detection capabilities that aren't used in this case.

Finally, the HttpClient is returned to the caller. Let's look at the CreateHandler() method now and see how the HttpMessageHandler pipeline is created. There's quite a few layers to get through, so we'll walk through it step-by-step.

// Created in the constructor
readonly ConcurrentDictionary<string, Lazy<ActiveHandlerTrackingEntry>> _activeHandlers;;

readonly Func<string, Lazy<ActiveHandlerTrackingEntry>> _entryFactory = (name) =>
    {
        return new Lazy<ActiveHandlerTrackingEntry>(() =>
        {
            return CreateHandlerEntry(name);
        }, LazyThreadSafetyMode.ExecutionAndPublication);
    };

public HttpMessageHandler CreateHandler(string name)
{
    ActiveHandlerTrackingEntry entry = _activeHandlers.GetOrAdd(name, _entryFactory).Value;

    entry.StartExpiryTimer(_expiryCallback);

    return entry.Handler;
}

The CreateHandler() method does two things:

It gets or creates an ActiveHandlerTrackingEntry
It stars a timer on the entry

The _activeHandlers field is a ConcurrentDictionary<>, keyed on the name of the client (e.g. "gitHub"). The dictionary values are Lazy<ActiveHandlerTrackingEntry>. Using Lazy<> here is a neat trick I've blogged about previously to make the GetOrAdd function thread safe. The job of actually creating the handler occurs in CreateHandlerEntry (which we'll see shortly) which creates an ActiveHandlerTrackingEntry.

The ActiveHandlerTrackingEntry is mostly an immutable object containing an HttpMessageHandler and a DI IServiceScope. In reality it also contains an internal timer that is used with the StartExpiryTimer() method to call the provided callback when the timer of length Lifetime expires.

internal class ActiveHandlerTrackingEntry
{
    public LifetimeTrackingHttpMessageHandler Handler { get; private set; }
    public TimeSpan Lifetime { get; }
    public string Name { get; }
    public IServiceScope Scope { get; }
    public void StartExpiryTimer(TimerCallback callback)
    {
        // Starts the internal timer
        // Executes the callback after Lifetime has expired.
        // If the timer has already started, is noop
    }
}

So the CreateHandler method either creates a new ActiveHandlerTrackingEntry, or retrieves the entry from the dictionary, and starts the timer. In the next section we'll look at how the CreateHandlerEntry() method creates the ActiveHandlerTrackingEntry instances:

Creating and tracking HttpMessageHandlers in CreateHandlerEntry

The CreateHandlerEntry method is where the HttpClient handler pipelines are created. It's a somewhat complex method, so I'll show it first, and then talk through it afterwards. The version shown below is somewhat simplified compared to the real version, but it maintains all the salient points.

// The root service provider, injected into the constructor using DI
private readonly IServiceProvider _services;

// A collection of IHttpMessageHandler "configurers" that are added to every handler pipeline
private readonly IHttpMessageHandlerBuilderFilter[] _filters;

private ActiveHandlerTrackingEntry CreateHandlerEntry(string name)
{
    IServiceScope scope = _services.CreateScope(); 
    IServiceProvider services = scope.ServiceProvider;
    HttpClientFactoryOptions options = _optionsMonitor.Get(name);

    HttpMessageHandlerBuilder builder = services.GetRequiredService<HttpMessageHandlerBuilder>();
    builder.Name = name;

    // This is similar to the initialization pattern in:
    // https://github.com/aspnet/Hosting/blob/e892ed8bbdcd25a0dafc1850033398dc57f65fe1/src/Microsoft.AspNetCore.Hosting/Internal/WebHost.cs#L188
    Action<HttpMessageHandlerBuilder> configure = Configure;
    for (int i = _filters.Length - 1; i >= 0; i--)
    {
        configure = _filters[i].Configure(configure);
    }

    configure(builder);

    // Wrap the handler so we can ensure the inner handler outlives the outer handler.
    var handler = new LifetimeTrackingHttpMessageHandler(builder.Build());

    return new ActiveHandlerTrackingEntry(name, handler, scope, options.HandlerLifetime);

    void Configure(HttpMessageHandlerBuilder b)
    {
        for (int i = 0; i < options.HttpMessageHandlerBuilderActions.Count; i++)
        {
            options.HttpMessageHandlerBuilderActions[i](b);
        }
    }
}

There's quite a lot to unpack here. The method starts by creating a new IServiceScope using the root DI container. This creates a DI scope, so that scoped services can be sourced from the associated IServiceProvider. We also retrieve the HttpClientFactoryOptions for the requested HttpClient name, which contains the specific handler configuration for this instance.

The next item retrieved from the container is an HttpMessageHandlerBuilder, which by default is a DefaultHttpMessageHandlerBuilder. This is used to build the handler pipeline, by creating a "primary" handler, which is the HttpClientHandler that is responsible for making the socket connection and sending the request. You can add additional DelegatingHandlers that wrap the primary server, creating a pipeline for requests and responses.

The DelegatingHandlers are added to the builder using a slightly complicated arrangement, that is very reminiscent of how the middleware pipeline in an ASP.NET Core app is built:

The Configure() local method builds a pipeline of DelegatingHandlers, based on the configuration you provided in Startup.ConfigureServices().
IHttpMessageHandlerBuilderFilter are filters that are injected into the IHttpClientFactory constructor. They are used to add additional handlers into the DelegatingHandler pipeline.

IHttpMessageHandlerBuilderFilter are directly analogous to the IStartupFilters used by the ASP.NET Core middleware pipeline, which I've talked about previously. A single IHttpMessageHandlerBuilderFilter is registered by default, the LoggingHttpMessageHandlerBuilderFilter. This filter adds two additional handlers to the DelegatingHandler pipeline:

LoggingScopeHttpMessageHandler at the start (outside) of the pipeline, which starts a new logging scope.
A LoggingHttpMessageHandler at the end (inside) of the pipeline, just before the request is sent to the primary HttpClientHandler, which records logs about the request and response.

Finally, the whole pipeline is wrapped in a LifetimeTrackingHttpMessageHandler, which is a "noop" DelegatingHandler. We'll come back to the purpose of this handler later.

The code (and probably my description) for CreateHandlerEntry is definitely somewhat hard to follow, but the end result for an HttpClient configured with two custom handlers (as demonstrated at the start of this post) is a handler pipeline that looks something like the following:

Once the handler pipeline is complete, it is saved in a new ActiveHandlerTrackingEntry instance, along with the DI IServiceScope used to create it, and given the lifetime defined in HttpClientFactoryOptions (two minutes by default).

This entry is returned to the caller (the CreateHandler() method), added to the ConcurrentDictionary<> of handlers, added to a new HttpClient instance (in the CreateClient() method), and returned to the original caller.

For the next two minutes, every time you call CreateClient(), you will get a new instance of HttpClient, but which has the same handler pipeline as was originally created.

Each named or typed client gets its own message handler pipeline. i.e. two instances of the "github" named client will have the same handler chain, but the "api" named client would have a different handler chain.

The next challenge is cleaning up and disposing the handler chain once the two minute timer has expired. This requires some careful handling, as you'll see in the next section.

Cleaning up expired handlers.

After two minutes, the timer stored in the ActiveHandlerTrackingEntry entry will expire, and fire the callback method passed into StartExpiryTimer(): ExpiryTimer_Tick().

ExpiryTimer_Tick is responsible for removing the active handler entry from the ConcurrentDictionary<> pool, and adding it to a queue of expired handlers:

// Created in the constructor
readonly ConcurrentQueue<ExpiredHandlerTrackingEntry> _expiredHandlers;

// The Timer instance in ActiveHandlerTrackingEntry calls this when it expires
internal void ExpiryTimer_Tick(object state)
{
    var active = (ActiveHandlerTrackingEntry)state;

     _activeHandlers.TryRemove(active.Name, out Lazy<ActiveHandlerTrackingEntry> found);

    var expired = new ExpiredHandlerTrackingEntry(active);
    _expiredHandlers.Enqueue(expired);

    StartCleanupTimer();
}

Once the active handler is removed from the _activeHandlers collection, it will no longer be handed out with new HttpClients when your call CreateClient(). But there are potentially HttpClients out there which are still using the active handler. The IHttpClientFactory has to wait for all the HttpClient instances that reference this handler to be cleaned up before it can dispose the handler pipeline.

The problem is, how can IHttpClientFactory track that the handler is no longer referenced? The key is the use of the "noop" LifetimeTrackingHttpMessageHandler, and the ExpiredHandlerTrackingEntry.

The ExpiredHandlerTrackingEntry, shown below, creates a WeakReference to the LifetimeTrackingHttpMessageHandler. As I showed in the previous section, the LifetimeTrackingHttpMessageHandler is the "outermost" handler in the chain, so it is the handler that is directly referenced by the HttpClient.

internal class ExpiredHandlerTrackingEntry
{
    private readonly WeakReference _livenessTracker;

    // IMPORTANT: don't cache a reference to `other` or `other.Handler` here.
    // We need to allow it to be GC'ed.
    public ExpiredHandlerTrackingEntry(ActiveHandlerTrackingEntry other)
    {
        Name = other.Name;
        Scope = other.Scope;

        _livenessTracker = new WeakReference(other.Handler);
        InnerHandler = other.Handler.InnerHandler;
    }

    public bool CanDispose => !_livenessTracker.IsAlive;

    public HttpMessageHandler InnerHandler { get; }
    public string Name { get; }
    public IServiceScope Scope { get; }
}

Using WeakReference to the LifetimeTrackingHttpMessageHandler means that the only direct references to the outermost handler in the chain are in HttpClients. Once all these HttpClients have been collected by the garbage collector, the LifetimeTrackingHttpMessageHandler will have no references, and so will also be disposed. The ExpiredHandlerTrackingEntry can detect that via the WeakReference.IsAlive property.

Note that the ExpiredHandlerTrackingEntry does maintain a reference to the rest of the handler pipeline, so that it can properly dispose the inner handler chain, as well as the DI IServiceScope.

After an entry is added to the _expiredHandlers queue, a timer is started by StartCleanupTimer() which fires after 10 seconds. This calls the CleanupTimer_Tick() method, which checks to see whether all the references to the handler have expired. If so, the handler chain and IServiceScope are disposed. If not, they are added back onto the queue, and the clean-up timer is started again:

internal void CleanupTimer_Tick()
{
    // Stop any pending timers, we'll restart the timer if there's anything left to process after cleanup.
    StopCleanupTimer();

    // Loop through all the timers
    int initialCount = _expiredHandlers.Count;
    for (int i = 0; i < initialCount; i++)
    {
        _expiredHandlers.TryDequeue(out ExpiredHandlerTrackingEntry entry);

        if (entry.CanDispose)
        {
            // All references to the handler chain have been removed
            try
            {
                entry.InnerHandler.Dispose();
                entry.Scope?.Dispose();
            }
            catch (Exception ex)
            {
                // log the exception
            }
        }
        else
        {
            // If the entry is still live, put it back in the queue so we can process it
            // during the next cleanup cycle.
            _expiredHandlers.Enqueue(entry);
        }
    }

    // We didn't totally empty the cleanup queue, try again later.
    if (_expiredHandlers.Count > 0)
    {
        StartCleanupTimer();
    }
}

The method presented above is pretty simple - it loops through each of the ExpiredHandlerTrackingEntry entries in the queue, and checks if all references to the LifetimeTrackingHttpMessageHandler handlers have been removed. If they have, the handler chain (everything that was inside the lifetime tracking handler) is disposed, as is the DI IServiceScope.

If there are still live references to any of the LifetimeTrackingHttpMessageHandler handlers, the entries are put back in the queue, and the cleanup timer is started again. Every 10 seconds another cleanup sweep is run.

I simplified the CleanupTimer_Tick() method shown above compared to the original. The original adds additional logging, and uses locking to ensure only a single thread runs the cleanup at a time.

That brings us to the end of this deep dive in the internals of IHttpClientFactory! IHttpClientFactory shows the correct way to manage HttpClient and HttpMessageHandlers in your application. Having read through the code, it's understandable that noone got this completely right for so long - there's a lot of tricky gotchas there! If you've made it this far, I suggest going and looking through the original code, I highlighted (what I consider) the most important points in this post, but you can learn a lot from reading other people's code!

Summary

In this post I looked at the source code behind the default IHttpClientFactory implementation in .NET Core 3.1, DefaultHttpClientFactory. I showed how the factory stores an active HttpMessageHandler pipeline for each configured named or typed client, with each new HttpClient getting a reference to the same pipeline. I showed that the handler pipeline is built in a similar way to the ASP.NET Core middleware pipeline, using handlers. Finally, I showed how the factory tracks whether any HttpClients reference a pipeline instance by using a WeakReference to the handler.

Detecting duplicate routes in ASP.NET Core: Visualizing ASP.NET Core 3.0 endpoints using GraphvizOnline - Part 5

Andrew Lock "Sock" — Tue, 28 Jul 2020 10:00:00 +0000

In this series, I have shown how to view all the routes in your application using an endpoint graph. In this post I show how to do something more useful—detecting duplicate routes that would throw an exception at runtime. I show how to use the same DfaGraphWriter primitives as in previous posts to create a unit test that fails if you have any duplicate routes in your application that would cause a failure at runtime.

Duplicate routes and runtime exceptions

ASP.NET Core 3.x uses endpoint routing for all your MVC/API controllers and Razor Pages, as well as dedicated endpoints like a health check endpoint. As you've already seen in this series, those endpoints are built into a directed graph, which is used to route incoming requests to a handler:

Unfortunately, it's perfectly possible to structure your controllers/Razor Pages in such as way as to have multiple endpoints be a match for a given route. For example, imagine you have a "values" controller in your project:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

Meanwhile, some joker has also created the following controller too:

[ApiController]
public class DuplicateController
{
    [HttpGet("api/values")]
    public string Get()
    {
        return "oops";
    }
}

As routing is only handled at runtime, everything will appear to be fine when you build and deploy your application. Health checks will pass, and all other routes will behave normally. But when someone hits the URL /api/values, you'll get this beauty:

The good thing here at least is that the error message tells you where the problem is. But wouldn't it be nice to know that before you've deployed to production?

Trying to detect this error ahead of time was what started me down the graph-drawing rabbit-hole of this series. My goal was to create a simple unit test that can run as part of the build, to identify errors like these.

Creating a duplicate endpoint detector

If you've read the rest of this series, then you may have already figured out how this is going to work. The DfaGraphWriter that is built-in to the framework, which can be used to visualize the endpoint graph, knows how to visit each node (route) in the graph. We'll adapt this somewhat: instead of outputting a graph, we'll return a list of routes which match multiple endpoints.

The detector class we'll create, DuplicateEndpointDetector uses the same ImpromptuInterface technique as previous posts, reusing the IDfaNode and IDfaMatcherBuilder interfaces, shown below for completeness:

public interface IDfaNode
{
    public string Label { get; set; }
    public List<Endpoint> Matches { get; }
    public IDictionary Literals { get; }
    public object Parameters { get; }
    public object CatchAll { get; }
    public IDictionary PolicyEdges { get; }
}

public interface IDfaMatcherBuilder
{
    void AddEndpoint(RouteEndpoint endpoint);
    object BuildDfaTree(bool includeLabel = false);
}

These interfaces give us a slightly nicer way to work with the internal classes used by the default DfaGraphWriter.

The bulk of the DuplicateEndpointDetector is identical to the CustomDfaGraphWriter from my previous post. The only difference is that we a GetDuplicateEndpoints() method instead of a Write() method. We also don't use a TextWriter (as we're not trying to build a graph for display) and we return a dictionary of duplicated endpoints (keyed on the route).

I've shown almost the complete code below, with the exception of the LogDuplicates method which we'll get to shortly.

public class DuplicateEndpointDetector
{
    private readonly IServiceProvider _services;
    public DuplicateEndpointDetector(IServiceProvider services)
    {
        _services = services;
    }

    public Dictionary<string, List<string>> GetDuplicateEndpoints(EndpointDataSource dataSource)
    {
        // Use ImpromptuInterface to create the required dependencies as shown in previous post
        Type matcherBuilder = typeof(IEndpointSelectorPolicy).Assembly
            .GetType("Microsoft.AspNetCore.Routing.Matching.DfaMatcherBuilder");

        // Build the list of endpoints used to build the graph
        var rawBuilder = _services.GetRequiredService(matcherBuilder);
        IDfaMatcherBuilder builder = rawBuilder.ActLike<IDfaMatcherBuilder>();

        // This is the same logic as the original graph writer
        var endpoints = dataSource.Endpoints;
        for (var i = 0; i < endpoints.Count; i++)
        {
            if (endpoints[i] is RouteEndpoint endpoint && (endpoint.Metadata.GetMetadata<ISuppressMatchingMetadata>()?.SuppressMatching ?? false) == false)
            {
                builder.AddEndpoint(endpoint);
            }
        }

        // Build the raw tree from the registered routes
        var rawTree = builder.BuildDfaTree(includeLabel: true);
        IDfaNode tree = rawTree.ActLike<IDfaNode>();

        // Store a list of nodes that have already been visited 
        var visited = new Dictionary<IDfaNode, int>();

        // Store a dictionary of duplicates
        var duplicates = new Dictionary<string, List<string>>();

        // Build the graph by visiting each node, and calling LogDuplicates on each
        Visit(tree, LogDuplicates);

        // done
        return duplicates;

        void LogDuplicates(IDfaNode node)
        {
            /* Details shown later in this post*/
        }
    }

    // Identical to the version shown in the previous post
    static void Visit(IDfaNode node, Action<IDfaNode> visitor)
    {
        if (node.Literals?.Values != null)
        {
            foreach (var dictValue in node.Literals.Values)
            {
                IDfaNode value = dictValue.ActLike<IDfaNode>();
                Visit(value, visitor);
            }
        }

        // Break cycles
        if (node.Parameters != null && !ReferenceEquals(node, node.Parameters))
        {
            IDfaNode parameters = node.Parameters.ActLike<IDfaNode>();
            Visit(parameters, visitor);
        }

        // Break cycles
        if (node.CatchAll != null && !ReferenceEquals(node, node.CatchAll))
        {
            IDfaNode catchAll = node.CatchAll.ActLike<IDfaNode>();
            Visit(catchAll, visitor);
        }

        if (node.PolicyEdges?.Values != null)
        {
            foreach (var dictValue in node.PolicyEdges.Values)
            {
                IDfaNode value = dictValue.ActLike<IDfaNode>();
                Visit(value, visitor);
            }
        }

        visitor(node);
    }
}

This class follows the same approach as the graph writer. It uses ImpromptuInterface to create an IDfaMatcherBuilder proxy, which it uses to build a graph of all the endpoints in the system. It then visits each of the IDfaNodes in the graph and calls the LogDuplicates() method, passing in each node in turn.

LogDuplicates() is a lot simpler than the WriteNode() implementation from the previous post. All we're concerned about here is whether a node has multiple entries in its Matches property. If it does, we have an ambiguous route, so we add it to the dictionary. I'm using the DisplayName to identify the ambiguous endpoints, just as the exception message shown earlier does.

// LogDuplicates is a local method. visited and duplicates are defined in the calling function
var visited = new Dictionary<IDfaNode, int>();
var duplicates = new Dictionary<string, List<string>>();

void LogDuplicates(IDfaNode node)
{
    // Add the node to the visited node dictionary if it isn't already
    // Generate a zero-based integer label for the node
    if (!visited.TryGetValue(node, out var label))
    {
        label = visited.Count;
        visited.Add(node, label);
    }

    // We can safely index into visited because this is a post-order traversal,
    // all of the children of this node are already in the dictionary.

    // Does this node have multiple matches?
    var matchCount = node?.Matches?.Count ?? 0;
    if(matchCount > 1)
    {
        // Add the node to the dictionary!
        duplicates[node.Label] = node.Matches.Select(x => x.DisplayName).ToList();
    }
}

After executing GetDuplicateEndpoints() you'll have a dictionary containing all the duplicate routes in your application. The final thing to do is create a unit test, so that we can fail the build if we detect a problem.

Creating a unit test to detect duplicate endpoints

I like to put this check in a unit test, because performance is much less of an issue. You could check for duplicate routes on app startup or using a health check But given that we use reflection heavily this will add to startup time, and also given that the routes are fixed once you deploy your application, a unit test seems like the best place for it.

Just as in a previous post where I draw the graph in a unit test, in this post I'll use an "integration test" to check for duplicate endpoints in my main app.

Create a new xUnit project using VS or by running dotnet new xunit.
Install Microsoft.AspNetCore.Mvc.Testing by running dotnet add package Microsoft.AspNetCore.Mvc.Testing
Update the <Project> element of your test project to <Project Sdk="Microsoft.NET.Sdk.Web">
Reference your ASP.NET Core project from the test project

You can now create a simple integration test using the WebApplicationFactory<> as a class fixture. I also inject ITestOutputHelper so that we can list out the duplicate endpoints for the test:

public class DuplicateDetectorTest
    : IClassFixture<WebApplicationFactory<ApiRoutes.Startup>>
{
    // Inject the factory and the output helper
    private readonly WebApplicationFactory<ApiRoutes.Startup> _factory;
    private readonly ITestOutputHelper _output;
    public DuplicateDetectorTest(WebApplicationFactory<Startup> factory, ITestOutputHelper output)
    {
        _factory = factory;
        _output = output;
    }

    [Fact]
    public void ShouldNotHaveDuplicateEndpoints()
    {
        // Create an instance of the detector using the IServiceProvider from the app
        // and get an instance of the endpoint data
        var detector = new DuplicateEndpointDetector(_factory.Services);
        var endpointData = _factory.Services.GetRequiredService<EndpointDataSource>();

        // Find all the duplicates
        var duplicates = detector.GetDuplicateEndpoints(endpointData);

        // Print the duplicates to the output
        foreach (var keyValuePair in duplicates)
        {
            var allMatches = string.Join(", ", keyValuePair.Value);
            _output.WriteLine($"Duplicate route: '{keyValuePair.Key}'. Matches: {allMatches}");
        }

        // If we have some duplicates, then fail the CI build!
        Assert.Empty(duplicates);
    }
}

When you run the test, the assertion will fail, and if you view the output, you'll see a list of the routes with issues, as well as the endpoints that caused the problem:

If you're running your unit tests as part of your CI build, then you'll catch the issue before it gets to production. Pretty handy!

Summary

In this post I show how you can build a duplicate endpoint detector using the endpoint graph building facilities included in ASP.NET Core. The end result requires quite a few tricks, as I've shown in the previous posts of this series, such as using ImpromptuInterface to create proxies for interacting with internal types.

The end result is that you can detect when multiple endpoints (e.g. API controllers) are using the same route in your application. Given that those throw routes would throw an AmbiguousMatchException at runtime, being able to detect issues using a unit test is pretty handy!

Creating a custom endpoint visualization graph: Visualizing ASP.NET Core 3.0 endpoints using GraphvizOnline - Part 4

Andrew Lock "Sock" — Tue, 21 Jul 2020 10:00:00 +0000

In this series, I've been laying the groundwork for building a custom endpoint visualization graph, as I showed in my first post. This graph shows the different parts of the endpoint routes: literal values, parameters, verb constraints, and endpoints that generate a result:

In this post I show how you can create an endpoint graph like this for your own application, by creating a custom DfaGraphWriter.

This post uses techniques and classes from the previous posts in the series, so I strongly suggest reading those before continuing.

Adding configuration for the endpoint graph

The first thing we'll look at is how to configure what the final endpoint graph will look like. We'll add configuration for two types of node and four types of edge. The edges are:

Literal edges: Literal matches for route sections, such as api and values in the route api/values/{id}.
Parameters edges: Parameterised sections for routes, such as {id} in the route api/values/{id}.
Catch all edges: Edges that correspond to the catch-all route parameter, such as {**slug}.
Policy edges: Edges that correspond to a constraint other than the URL. For example, the HTTP verb-based edges in the graph, such as HTTP: GET.

and the nodes are:

Matching node: A node that is associated with an endpoint match, so will generate a response.
Default node: A node that is not associated with an endpoint match.

Each of these nodes and edges can have any number of Graphviz attributes to control their display. The GraphDisplayOptions below show the default values I used to generate the graph at the start of this post:

public class GraphDisplayOptions
{
    /// <summary>
    /// Additional display options for literal edges
    /// </summary>
    public string LiteralEdge { get; set; } = string.Empty;

    /// <summary>
    /// Additional display options for parameter edges
    /// </summary>
    public string ParametersEdge { get; set; } = "arrowhead=diamond color=\"blue\"";

    /// <summary>
    /// Additional display options for catchall parameter edges
    /// </summary>
    public string CatchAllEdge { get; set; } = "arrowhead=odot color=\"green\"";

    /// <summary>
    /// Additional display options for policy edges
    /// </summary>
    public string PolicyEdge { get; set; } = "color=\"red\" style=dashed arrowhead=open";

    /// <summary>
    /// Additional display options for node which contains a match
    /// </summary>
    public string MatchingNode { get; set; } = "shape=box style=filled color=\"brown\" fontcolor=\"white\"";

    /// <summary>
    /// Additional display options for node without matches
    /// </summary>
    public string DefaultNode { get; set; } = string.Empty;
}

We can now create our custom graph writer using this object to control the display, and using the ImpromptuInterface "proxy" technique shown in the previous post.

Creating a custom DfaGraphWriter

Our custom graph writer (cunningly called CustomDfaGraphWriter) is heavily based on the DfaGraphWriter included in ASP.NET Core. The bulk of this class is the same as the original, with the following changes:

Inject the GraphDisplayOptions into the class to customise the display.
Use the ImpromptuInterface library to work with the internal DfaMatcherBuilder and DfaNode classes, as shown in the previous post.
Customise the WriteNode function to use our custom styles.
Add a Visit function to work with the IDfaNode interface, instead of using the Visit() method on the internal DfaNode class.

The whole CustomDfaGraphWriter is shown below, focusing on the main Write() function. I've kept the implementation almost identical to the original, only updating the parts we have to.

public class CustomDfaGraphWriter
{
    // Inject the GraphDisplayOptions 
    private readonly IServiceProvider _services;
    private readonly GraphDisplayOptions _options;
    public CustomDfaGraphWriter(IServiceProvider services, GraphDisplayOptions options)
    {
        _services = services;
        _options = options;
    }

    public void Write(EndpointDataSource dataSource, TextWriter writer)
    {
        // Use ImpromptuInterface to create the required dependencies as shown in previous post
        Type matcherBuilder = typeof(IEndpointSelectorPolicy).Assembly
            .GetType("Microsoft.AspNetCore.Routing.Matching.DfaMatcherBuilder");

        // Build the list of endpoints used to build the graph
        var rawBuilder = _services.GetRequiredService(matcherBuilder);
        IDfaMatcherBuilder builder = rawBuilder.ActLike<IDfaMatcherBuilder>();

        // This is the same logic as the original graph writer
        var endpoints = dataSource.Endpoints;
        for (var i = 0; i < endpoints.Count; i++)
        {
            if (endpoints[i] is RouteEndpoint endpoint && (endpoint.Metadata.GetMetadata<ISuppressMatchingMetadata>()?.SuppressMatching ?? false) == false)
            {
                builder.AddEndpoint(endpoint);
            }
        }

        // Build the raw tree from the registered routes
        var rawTree = builder.BuildDfaTree(includeLabel: true);
        IDfaNode tree = rawTree.ActLike<IDfaNode>();

        // Store a list of nodes that have already been visited 
        var visited = new Dictionary<IDfaNode, int>();

        // Build the graph by visiting each node, and calling WriteNode on each
        writer.WriteLine("digraph DFA {");
        Visit(tree, WriteNode);
        writer.WriteLine("}");

        void WriteNode(IDfaNode node)
        {
            /* Write the node to the TextWriter */
            /* Details shown later in this post*/
        }
    }

    static void Visit(IDfaNode node, Action<IDfaNode> visitor)
    {
        /* Recursively visit each node in the tree. */
        /* Details shown later in this post*/
    }
}

I've elided the Visit and WriteNode functions here for brevity, but we'll look into them soon. We'll start with the Visit function, as that flies closest to the original.

Updating the Visit function to work with IDfaNode

As I discussed in my previous post, one of the biggest problems creating a custom DfaGraphWriter is its use of internal classes. To work around that I used ImpromptuInterface to create proxy objects that wrap the original:

The original Visit() method is a method on the DfaNode class. It recursively visits every node in the endpoint tree, calling a provided Action<> function for each node.

As DfaNode is internal, I implemented the Visit function as a static method on CustomDfaGraphWriter instead.

Our custom implementation is broadly the same as the original, but we have to do some somewhat arduous conversions between the "raw" DfaNodes and our IDfaNode proxies. The updated method is shown below. The method takes two parameters—the node being checked, and an Action<> to run on each.

static void Visit(IDfaNode node, Action<IDfaNode> visitor)
{
    // Does the node of interest have any nodes connected by literal edges?
    if (node.Literals?.Values != null)
    {
        // node.Literals is actually a Dictionary<string, DfaNode>
        foreach (var dictValue in node.Literals.Values)
        {
            // Create a proxy for the child DfaNode node and visit it
            IDfaNode value = dictValue.ActLike<IDfaNode>();
            Visit(value, visitor);
        }
    }

    // Does the node have a node connected by a parameter edge?
    // The reference check breaks any cycles in the graph
    if (node.Parameters != null && !ReferenceEquals(node, node.Parameters))
    {
        // Create a proxy for the DfaNode node and visit it
        IDfaNode parameters = node.Parameters.ActLike<IDfaNode>();
        Visit(parameters, visitor);
    }

    // Does the node have a node connected by a catch-all edge?
    // The refernece check breaks any cycles in the graph
    if (node.CatchAll != null && !ReferenceEquals(node, node.CatchAll))
    {
        // Create a proxy for the DfaNode node and visit it
        IDfaNode catchAll = node.CatchAll.ActLike<IDfaNode>();
        Visit(catchAll, visitor);
    }

    // Does the node have a node connected by a policy edges?
    if (node.PolicyEdges?.Values != null)
    {
        // node.PolicyEdges is actually a Dictionary<object, DfaNode>
        foreach (var dictValue in node.PolicyEdges.Values)
        {
            IDfaNode value = dictValue.ActLike<IDfaNode>();
            Visit(value, visitor);
        }
    }

    // Write the node using the provided Action<>
    visitor(node);
}

The Visit function uses a post-order traversal, so it traverses "deep" into a node's child nodes first before writing the node using the visitor function. This is the same as the original DfaNode.Visit() function.

We're almost there now. We have a class that builds the endpoint node tree, traverses all the nodes in the tree, and runs a function for each. All that remains is to define the visitor function, WriteNode().

Defining a custom WriteNode function

We've finally got to the meaty part, controlling how the endpoint graph is displayed. All of the customisation and effort so far has been to enable us to customise the WriteNode function.

WriteNode() is a local function that writes a node to the TextWriter output, along with any connected edges, using the DOT graph description language.

Our custom WriteNode() function is, again, almost the same as the original. There are two main differences:

The original graph writer works with DfaNodes, we have to convert to using the IDfaNode proxy.
The original graph writer uses the same styling for all nodes and edges. We customise the display of nodes and edges based on the configured GraphDisplayOptions.

As WriteNode is a local function, it can access variables from the enclosing function. This includes the writer parameter, used to write the graph to output and the visited dictionary of previously written nodes.

The following shows our (heavily commented) custom version of the WriteNode() method.

void WriteNode(IDfaNode node)
{
    // add the node to the visited node dictionary if it isn't already
    // generate a zero-based integer label for the node
    if (!visited.TryGetValue(node, out var label))
    {
        label = visited.Count;
        visited.Add(node, label);
    }

    // We can safely index into visited because this is a post-order traversal,
    // all of the children of this node are already in the dictionary.

    // If this node is linked to any nodes by a literal edge
    if (node.Literals != null)
    {
        foreach (DictionaryEntry dictEntry in node.Literals)
        {
            // Foreach linked node, get the label for the edge and the linked node
            var edgeLabel = (string)dictEntry.Key;
            IDfaNode value = dictEntry.Value.ActLike<IDfaNode>();
            int nodeLabel = visited[value];

            // Write an edge, including our custom styling for literal edges
            writer.WriteLine($"{label} -> {nodeLabel} [label=\"/{edgeLabel}\" {_options.LiteralEdge}]");
        }
    }

    // If this node is linked to a nodes by a parameter edge
    if (node.Parameters != null)
    {
        IDfaNode parameters = node.Parameters.ActLike<IDfaNode>();
        int nodeLabel = visited[catchAll];

        // Write an edge labelled as /* using our custom styling for parameter edges
        writer.WriteLine($"{label} -> {nodeLabel} [label=\"/**\" {_options.CatchAllEdge}]");
    }

    // If this node is linked to a catch-all edge
    if (node.CatchAll != null && node.Parameters != node.CatchAll)
    {
        IDfaNode catchAll = node.CatchAll.ActLike<IDfaNode>();
        int nodeLabel = visited[catchAll];

        // Write an edge labelled as /** using our custom styling for catch-all edges
        writer.WriteLine($"{label} -> {nodelLabel} [label=\"/**\" {_options.CatchAllEdge}]");
    }

    // If this node is linked to any Policy Edges
    if (node.PolicyEdges != null)
    {
        foreach (DictionaryEntry dictEntry in node.PolicyEdges)
        {
            // Foreach linked node, get the label for the edge and the linked node
            var edgeLabel = (object)dictEntry.Key;
            IDfaNode value = dictEntry.Value.ActLike<IDfaNode>();
            int nodeLabel = visited[value];

            // Write an edge, including our custom styling for policy edges
            writer.WriteLine($"{label} -> {nodeLabel} [label=\"{key}\" {_options.PolicyEdge}]");
        }
    }

    // Does this node have any associated matches, indicating it generates a response?
    var matchCount = node?.Matches?.Count ?? 0;

    var extras = matchCount > 0 
        ? _options.MatchingNode // If we have matches, use the styling for response-generating nodes...
        : _options.DefaultNode; // ...otherwise use the default style

    // Write the node to the graph output
    writer.WriteLine($"{label} [label=\"{node.Label}\" {extras}]");
}

Tracing the flow of these interactions can be a little confusing, because of the way we write the nodes from the "leaf" nodes back to the root of the tree. For example if we look at the output for the basic app shown at the start of this post, you can see the "leaf" endpoints are all written first: the healthz health check endpoint and the terminal match generating endpoints with the longest route:

digraph DFA {
  1 [label="/healthz/" shape=box style=filled color="brown" fontcolor="white"]
  2 [label="/api/Values/{...}/ HTTP: GET" shape=box style=filled color="brown" fontcolor="white"]
  3 [label="/api/Values/{...}/ HTTP: PUT" shape=box style=filled color="brown" fontcolor="white"]
  4 [label="/api/Values/{...}/ HTTP: DELETE" shape=box style=filled color="brown" fontcolor="white"]
  5 [label="/api/Values/{...}/ HTTP: *" shape=box style=filled color="brown" fontcolor="white"]
  6 -> 2 [label="HTTP: GET" color="red" style=dashed arrowhead=open]
  6 -> 3 [label="HTTP: PUT" color="red" style=dashed arrowhead=open]
  6 -> 4 [label="HTTP: DELETE" color="red" style=dashed arrowhead=open]
  6 -> 5 [label="HTTP: *" color="red" style=dashed arrowhead=open]
  6 [label="/api/Values/{...}/"]
  7 [label="/api/Values/ HTTP: GET" shape=box style=filled color="brown" fontcolor="white"]
  8 [label="/api/Values/ HTTP: POST" shape=box style=filled color="brown" fontcolor="white"]
  9 [label="/api/Values/ HTTP: *" shape=box style=filled color="brown" fontcolor="white"]
  10 -> 6 [label="/*" arrowhead=diamond color="blue"]
  10 -> 7 [label="HTTP: GET" color="red" style=dashed arrowhead=open]
  10 -> 8 [label="HTTP: POST" color="red" style=dashed arrowhead=open]
  10 -> 9 [label="HTTP: *" color="red" style=dashed arrowhead=open]
  10 [label="/api/Values/"]
  11 -> 10 [label="/Values"]
  11 [label="/api/"]
  12 -> 1 [label="/healthz"]
  12 -> 11 [label="/api"]
  12 [label="/"]
}

Even though the leaf nodes are written to the graph output first, the Graphviz visualizer will generally draw the graph with the leaf nodes at the bottom, and the edges pointing down. You can visualize the graph online at https://dreampuf.github.io/GraphvizOnline/:

If you want to change how the graph is rendered you can customize the GraphDisplayOptions. If you use the "test" approach I described in a previous post, you can pass these options in directly when generating the graph. If you're using the "middleware" approach, you can register the GraphDisplayOptions using the IOptions<> system instead, and control the display using the configuration system.

Summary

In this post I showed how to create a custom DfaGraphWriter to control how an application's endpoint graph is generated. To interoperate with the internal classes we used ImpromptuInterface, as described in the previous post, to create proxies we can interact with. We then had to write a custom Visit() function to work with the IDfaNode proxies. Finally, we created a custom WriteNode function that uses custom settings defined in a GraphDisplayOptions object to display each type of node and edge differently.

Adding an endpoint graph to your ASP.NET Core application: Visualizing ASP.NET Core 3.0 endpoints using GraphvizOnline - Part 2

Andrew Lock "Sock" — Tue, 07 Jul 2020 10:00:00 +0000

In this post I show how to visualize the endpoint routes in your ASP.NET Core 3.0 application using the DfaGraphWriter service. I show how to generate a directed graph (as shown in my previous post) which can be visualized using GraphVizOnline. Finally, I describe the points in your application's lifetime where you can retrieve the graph data.

In this post I only show how to create the "default" style of graph. In my next post I create a custom writer for generating the customised graphs like the one in my previous post.

Using DfaGraphWriter to visualize your endpoints.

ASP.NET Core comes with a handy class, DfaGraphWriter, that can be used to visualize your routes in an ASP.NET Core 3.x application:

public class DfaGraphWriter
{
    public void Write(EndpointDataSource dataSource, TextWriter writer);
}

This class has a single method, Write. The EndpointDataSource contains the collection of Endpoints describing your application, and the TextWriter is used to write the DOT language graph (as you saw in my previous post).

For now we'll create a middleware that uses the DfaGraphWriter to write the graph as an HTTP response. You can inject both the DfaGraphWriter and the EndpointDataSource it uses into the constructor using DI:

public class GraphEndpointMiddleware
{
    // inject required services using DI
    private readonly DfaGraphWriter _graphWriter;
    private readonly EndpointDataSource _endpointData;

    public GraphEndpointMiddleware(
        RequestDelegate next, 
        DfaGraphWriter graphWriter, 
        EndpointDataSource endpointData)
    {
        _graphWriter = graphWriter;
        _endpointData = endpointData;
    }

    public async Task Invoke(HttpContext context)
    {
        // set the response
        context.Response.StatusCode = 200;
        context.Response.ContentType = "text/plain";

        // Write the response into memory
        await using (var sw = new StringWriter())
        {
            // Write the graph
            _graphWriter.Write(_endpointData, sw);
            var graph = sw.ToString();

            // Write the graph to the response
            await context.Response.WriteAsync(graph);
        }
    }
}

This middleware is pretty simple—we inject the necessary services into the middleware using dependency injection. Writing the graph to the response is a bit more convoluted: you have to write the response in-memory to a StringWriter, convert it to a string, and then write it to the graph.

This is all necessary because the DfaGraphWriter writes to the TextWriter using synchronous Stream API calls, like Write, instead of WriteAsync. Ideally, we would be able to do something like this:

// Create a stream writer that wraps the body
await using (var sw = new StreamWriter(context.Response.Body))
{
    // write asynchronously to the stream
    await _graphWriter.WriteAsync(_endpointData, sw);
}

If DfaGraphWriter used asynchronous APIs, then you could write directly to Response.Body as shown above and avoid the in-memory string. Unfortunately, it's synchronous, and you shouldn't write to Response.Body using synchronous calls for performance reasons. If you try to use pattern above then you may get an InvalidOperationException like the following, depending on the size of the graph being written:

System.InvalidOperationException: Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.

You might not get this exception if the graph is small, but you can see it if you try and map a medium-side application, such as the default Razor Pages app with Identity.

Let's get back on track—we now have a graph-generating middleware, so lets add it to the pipeline. There's two options here:

Add it as an endpoint using endpoint routing.
Add it as a simple "branch" from your middleware pipeline.

The former approach is the generally recommended method for adding endpoints to ASP.NET Core 3.0 apps, so lets start there.

Adding the graph visualizer as an endpoint

To simplify the endpoint registration code, I'll create a simple extension method for adding the GraphEndpointMiddleware as an endpoint:

public static class GraphEndpointMiddlewareExtensions
{
    public static IEndpointConventionBuilder MapGraphVisualisation(
        this IEndpointRouteBuilder endpoints, string pattern)
    {
        var pipeline = endpoints
            .CreateApplicationBuilder()
            .UseMiddleware<GraphEndpointMiddleware>()
            .Build();

        return endpoints.Map(pattern, pipeline).WithDisplayName("Endpoint Graph");
    }
}

We can then add the graph endpoint to our ASP.NET Core application by calling MapGraphVisualisation("/graph") in the UseEndpoints() method in Startup.Configure():

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz");
        endpoints.MapControllers();
        // Add the graph endpoint
        endpoints.MapGraphVisualisation("/graph");
    });
}

That's all we need to do. The DfaGraphWriter is already available in DI, so there's no additional configuration required there. Navigating to http://localhost:5000/graph (for example) generates the graph of our endpoints as plain text (shown here for the app from ](/visualizing-asp-net-core-endpoints-using-graphvizonline-and-the-dot-language/):

digraph DFA {
    0 [label="/graph/"]
    1 [label="/healthz/"]
    2 [label="/api/Values/{...}/ HTTP: GET"]
    3 [label="/api/Values/{...}/ HTTP: PUT"]
    4 [label="/api/Values/{...}/ HTTP: DELETE"]
    5 [label="/api/Values/{...}/ HTTP: *"]
    6 -> 2 [label="HTTP: GET"]
    6 -> 3 [label="HTTP: PUT"]
    6 -> 4 [label="HTTP: DELETE"]
    6 -> 5 [label="HTTP: *"]
    6 [label="/api/Values/{...}/"]
    7 [label="/api/Values/ HTTP: GET"]
    8 [label="/api/Values/ HTTP: POST"]
    9 [label="/api/Values/ HTTP: *"]
    10 -> 6 [label="/*"]
    10 -> 7 [label="HTTP: GET"]
    10 -> 8 [label="HTTP: POST"]
    10 -> 9 [label="HTTP: *"]
    10 [label="/api/Values/"]
    11 -> 10 [label="/Values"]
    11 [label="/api/"]
    12 -> 0 [label="/graph"]
    12 -> 1 [label="/healthz"]
    12 -> 11 [label="/api"]
    12 [label="/"]
}

Which can be visualized using GraphVizOnline:

Exposing the graph as an endpoint in the endpoint routing system has both pros and cons:

You can easily add authorization to the endpoint. You probably don't want just anyone to be able to view this data!
The graph endpoint shows up as an endpoint in the system. That's obviously correct, but could be annoying.

If that final point is a deal breaker for you, you could use the old-school way of creating endpoints, using branching middleware.

Adding the graph visualizer as a middleware branch

Adding branches to your middleware pipeline was one of the easiest way to create "endpoints" before we had endpoint routing. It's still available in ASP.NET Core 3.0, it's just far more basic than the endpoint routing system, and doesn't provide the ability to easily add authorization or advanced routing.

To create a middleware branch, use the Map() command. For example, you could add a branch using the following:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // add the graph endpoint as a branch of the pipeline
    app.Map("/graph", branch => 
        branch.UseMiddleware<GraphEndpointMiddleware>());

    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz");
        endpoints.MapControllers();
    });
}

The pros and cons of using this approach are essentially the opposite of the endpoint-routing version: there's no /graph endpoint in your graph, but you can't easily apply authorization to the endpoint!

For me, it doesn't make a lot of sense to expose the graph of your application like this. In the next section, I show how you can generate the graph from a small integration test instead.

Generating an endpoint graph from an integration test

ASP.NET Core has a good story for running in-memory integration tests, exercising your full middleware pipeline and API controllers/Razor Pages, without having to make network calls.

As well as the traditional "end-to-end" integration tests that you can use to confirm the overall correct operation of your app, I sometimes like to write "sanity-check" tests, that confirm that an application is configured correctly. You can achieve this by using the WebApplicationFactory<> facility, in Microsoft.AspNetCore.Mvc.Testing which exposes the underlying DI container. This allows you to run code in the DI context of the application, but from a unit test.

To try it out

Create a new xUnit project (my testing framework of choice) using VS or by running dotnet new xunit
Install Microsoft.AspNetCore.Mvc.Testing by running dotnet add package Microsoft.AspNetCore.Mvc.Testing
Update the <Project> element of the test project to <Project Sdk="Microsoft.NET.Sdk.Web">
Reference your ASP.NET Core project from the test project

We can now create a simple test that generates the endpoint graph, and writes it to the test output. In the example below, I'm using the default WebApplicationFactory<> as a class fixture; if you need to customise the factory, see the docs or my previous post for details.

In addition to WebApplicationFactory<>, I'm also injecting ITestOutputHelper. You need to use this class to record test output with xUnit. Writing directly to Console won't work..

public class GenerateGraphTest
    : IClassFixture<WebApplicationFactory<ApiRoutes.Startup>>
{

    // Inject the factory and the output helper
    private readonly WebApplicationFactory<ApiRoutes.Startup> _factory;
    private readonly ITestOutputHelper _output;

    public GenerateGraphTest(
        WebApplicationFactory<Startup> factory, ITestOutputHelper output)
    {
        _factory = factory;
        _output = output;
    }

    [Fact]
    public void GenerateGraph()
    {
        // fetch the required services from the root container of the app
        var graphWriter = _factory.Services.GetRequiredService<DfaGraphWriter>();
        var endpointData = _factory.Services.GetRequiredService<EndpointDataSource>();

        // build the graph as before
        using (var sw = new StringWriter())
        {
            graphWriter.Write(endpointData, sw);
            var graph = sw.ToString();

            // write the graph to the test output
            _output.WriteLine(graph);
        }
    }
}

The bulk of the test is the same as for the middleware, but instead of writing to the response, we write to xUnit's ITestOutputHelper. This records the output against the test. In Visual Studio, you can view this output by opening Test Explorer, navigating to the GenerateGraph test, and clicking "Open additional output for this result", which opens the result as a tab:

I find a simple test like this is often sufficient for my purposes. There's lots of advantages in my eyes:

It doesn't expose this data as an endpoint
Has no impact on your application
Can be easily generated

Nevertheless, maybe you want to generate this graph from your application, but you don't want to include it using either of the middleware approaches shown so far. If so, just be careful exactly where you do it.

You can't generate the graph in an IHostedService

Generally speaking, you can access the DfaGraphWriter and EndpointDataSource services from anywhere in your app that uses dependency injection, or that has access to an IServiceProvider instance. That means generating the graph in the context of a request, for example from an MVC controller or Razor Page is easy, and identical to the approach you've seen so far.

Where you must be careful is if you're trying to generate the graph early in your application's lifecycle. This applies particularly to IHostedServices.

In ASP.NET Core 3.0, the web infrastructure was rebuilt on top of the generic host, which means your server (Kestrel) runs as an IHostedService in your application. In most cases, this shouldn't have a big impact, but it changes the order that your application is built, compared to ASP.NET Core 2.x.

In ASP.NET Core 2.x, the following things would happen:

The middleware pipeline is built.
The server (Kestrel) starts listening for requests.
The IHostedService implementations are started.

Instead, on ASP.NET Core 3.x, you have the following:

The IHostedService implementations are started.
The GenericWebHostService is started:
- The middleware pipeline is built
- The server (Kestrel) starts listening for requests.

The important thing to note is that the middleware pipeline isn't built until after your IHostedServices are executed. As UseEndpoints() has not yet been called, EndpointDataSource won't contain any data!

The EndpointDataSource will be empty if you try and generate your graph using DfaGraphWriter from an IHostedService.

The same goes if you try and use another standard mechanisms for injecting early behaviour, like IStartupFilter—these execute before Startup.Configure() is called, so the EndpointDataSource will be empty.

Similarly, you can't just build a Host by calling IHostBuilder.Build() in Program.Main, and access the services using IHost.Services: until you call IHost.Run, and the server has started, your endpoint list will be empty!

These limitations may or may not be an issue depending on what you're trying to achieve. For me, the unit test approach solves most of my issues.

Whichever approach you use, you're stuck only being able to generate the "default" endpoint graphs shown in this post. As I mentioned in my previous post, this hides a lot of really useful information, like which nodes generate an endpoint. In the next post, I show how to create a custom graph writer, so you can generate your own graphs.

Summary

In this post I showed how to use the DfaGraphWriter and EndpointDataSource to create a graph of all the endpoints in your application. I showed how to create a middleware endpoint to expose this data, and how to use this middleware both with a branching middleware strategy and as an endpoint route.

I also showed how to use a simple integration test to generate the graph data without having to run your application. This avoids exposing (the potentially sensitive) endpoint graph publicly, while still allowing easy access to the data.

Finally, I discussed when you can generate the graph in your application's lifecycle. The EndpointDataSource is not populated until after the Server (Kestrel) has started, so you're primarily limited to accessing the data in a Request context. IHostedService and IStartupFilter execute too early to access the data, and IHostBuilder.Build() only builds the DI container, not the middleware pipeline.

Visualizing ASP.NET Core endpoints using GraphvizOnline and the DOT language

Andrew Lock "Sock" — Tue, 30 Jun 2020 10:00:00 +0000

In this post I show how the endpoint routes in an ASP.NET Core 3.0 application can be visualized using the GraphvizOnline service. That lets you create diagrams like the following, which describe all the endpoints in your application:

Drawing graphs with GraphvizOnline and the DOT language

GraphvizOnline is a GitHub project that provides an online vizualizer for viewing graphs specified in the DOT graph description language. This is a simple language that lets you define various types of graph, which connects nodes with edges.

For example, a basic undirected graph could be defined as

graph MyGraph {
  a -- b -- c;
  b -- d;
}

which describes the following graph:

Each node has a name (a, b, c, d), and -- defines the edges between the nodes. The edges define connections between nodes, but they don't have a direction (hence the name, undirected).

You can also define a directed graph, in which the edges do have a direction. For a directed edge use -> instead of --. For example:

digraph MyGraph {
  a -> b -> c;
  d -> b;
}

which describes the following graph:

You can customise the way the nodes and edges are displayed in multiple ways. For example, you can label the nodes and edges:

digraph MySimpleGraph {
   // The label attribute can be used to change the label of a node...
   a [label="Foo"];
   b [label="Bar"];
   // ... or an edge
   a -> b [label="Baz"];
}

There's way more you can do with the DOT graph description language, but that's all we need for now. So how does this apply to ASP.NET Core?

Visualizing ASP.NET Core endpoints as a directed graph

The endpoint routing system in ASP.NET Core effectively works by creating a directed graph of the endpoint URL segments. Incoming requests are then matched, a segment at a time, to the graph to determine the endpoint to execute.

For example, the following simple directed graph represents the endpoints in the default ASP.NET Core 3.0 Razor Pages application template (dotnet new webapp), which contains three Razor Pages: Index.cshtml, Error.cshtml and Privacy.cshtml:

digraph DFA {
  1 [label="/Error/"]
  2 [label="/Index/"]
  3 [label="/Privacy/"]
  4 -> 1 [label="/Error"]
  4 -> 2 [label="/Index"]
  4 -> 3 [label="/Privacy"]
  4 [label="/"]
}

which describes:

In the DOT file above, the nodes are given sequential integer names, 1, 2, 3 etc and are labelled using the endpoint name. This is the format ASP.NET Core uses for representing the endpoint graph.

For Razor Pages, the routing is very simple, so the graph is pretty obvious. A more interesting graph is produced by an API application. For example, the ValuesController implementation shown below is similar to the version included in the ASP.NET Core 2.0 templates. It uses multiple HTTP verbs, as well as a slightly more complex URL structure:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // GET api/values
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get() => new string[] { "value1", "value2" };

    // GET api/values/5
    [HttpGet("{id}")]
    public ActionResult<string> Get(int id) => "value";

    // POST api/values
    [HttpPost]
    public void Post([FromBody] string value) { }

    // PUT api/values/5
    [HttpPut("{id}")]
    public void Put(int id, [FromBody] string value) { }

    // DELETE api/values/5
    [HttpDelete("{id}")]
    public void Delete(int id) { }
}

For good measure, I also added a basic health check endpoint to UseEndpoints():

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/healthz");
    endpoints.MapControllers();
});

This app produces the following graph:

digraph DFA {
  1 [label="/healthz/"] 
  2 [label="/api/Values/{...}/ HTTP: GET"] 
  3 [label="/api/Values/{...}/ HTTP: PUT"] 
  4 [label="/api/Values/{...}/ HTTP: DELETE"] 
  5 [label="/api/Values/{...}/ HTTP: *"] 
  6 -> 2 [label="HTTP: GET"]
  6 -> 3 [label="HTTP: PUT"]
  6 -> 4 [label="HTTP: DELETE"]
  6 -> 5 [label="HTTP: *"]
  6 [label="/api/Values/{...}/"] 
  7 [label="/api/Values/ HTTP: GET"] 
  8 [label="/api/Values/ HTTP: POST"] 
  9 [label="/api/Values/ HTTP: *"] 
  10 -> 6 [label="/*"]
  10 -> 7 [label="HTTP: GET"]
  10 -> 8 [label="HTTP: POST"]
  10 -> 9 [label="HTTP: *"]
  10 [label="/api/Values/"] 
  11 -> 10 [label="/Values"]
  11 [label="/api/"] 
  12 -> 1 [label="/healthz"]
  12 -> 11 [label="/api"]
  12 [label="/"] 
}

Which is visualised as:

There's a lot more going on in this graph, as we now have variable route parameter values ({id} in the route templates, shown as {...} in the graph) and HTTP verb constraints (GET/PUT/POST etc).

When I first saw this graph, I struggled to understand it. Is every node an endpoint? Surely not, as /api/ shouldn't generate a response. And what about the HTTP: * endpoints, do they generate a response?

To understand further, I went spelunking into the ASP.NET Core code that can generate these graphs, but it's a bit involved, and unfortunately not overly amenable to experimentation, due to extensive use of internal classes. I explore this code in a later post.

To better grasp the endpoint graph, we need to understand that not all the nodes are the same. In the next section we'll dig into the different types of node in even this simple graph, and then look at a better graphical representation (in my opinion at least!)

Understanding the different types of node.

Each node in the graph is associated with a given "depth". This is the number of URL segments that should already be matched. For example, the /api/Values/ node has a depth of 2—it requires the empty segment / and the /api segment to already be matched.

When a request reaches the EndpointRoutingMiddleware (added by UseRouting()), the incoming request URL is compared against this graph. A path is attempted to be found through the graph, starting with the root node at the top of the tree. URL segments are incrementally matched to edges in the graph, and a path is traversed through the graph until the whole request URL is matched.

Each node (represented by the DfaNode in ASP.NET Core internally) has several properties . The properties we're interested in for now are:

Matches: This is the Endpoint(s) associated with the node. If this node is matched via routing, then this is the Endpoint that will be selected for execution.
Literals: These are the edges that connect nodes. If a DfaNode has any Literals, it has literal segments that can be further traversed to reached other nodes. For example, the /api/ node contains a single Literal with value /Values, pointing to the /api/Values node.
PolicyEdges: These are edges that match based on a constraint other than the URL. For example, the verb-based edges in the graph, such as HTTP: GET, are policy edges, that point to a different DfaNode.
Parameters: If the node has an edge that supports route parameters (e.g. {id}), Parameters points to the node that handles matching the parameters. This is represented in the graph by the edge /*.

There is an additional property, CatchAll, which is relevant in some graphs, but I'll ignore it for now, as it's not required for our API graph.

Based on these properties, we can add some additional richness to our graph, by making use of some of the other features in the DOT language, such as shapes, colours, line type and arrowheads:

This graph makes the following additions:

Nodes which don't have any associated Endpoint are shown in the default style, black bubbles.
Nodes with Matches are shown as filled, brown, boxes. These are nodes with an Endpoint, that can generate a response. For the API example above, this applies to the nodes where a verb has been selected, as well as the health check endpoint.
Literal segment edges are shown as default black edges, with a filled arrowhead.
Parameters edges (/*) are shown in blue, using a diamond arrowhead.
PolicyEdges are shown in red, with a dashed line, and an empty triangle arrowhead.

Now, I freely admit my design skills suck, but nevertheless I think you can agree that this graph shows way more information than the default! 🙂 This is the definition that generated the graph above, remember you can visualise and play with the display yourself using an online editor.

digraph DFA {
  1 [label="/healthz/" shape=box style=filled color="brown" fontcolor="white"]
  2 [label="/api/Values/{...}/ HTTP: GET" shape=box style=filled color="brown" fontcolor="white"]
  3 [label="/api/Values/{...}/ HTTP: PUT" shape=box style=filled color="brown" fontcolor="white"]
  4 [label="/api/Values/{...}/ HTTP: DELETE" shape=box style=filled color="brown" fontcolor="white"]
  5 [label="/api/Values/{...}/ HTTP: *" shape=box style=filled color="brown" fontcolor="white"]
  6 -> 2 [label="HTTP: GET" color="red" style=dashed arrowhead=open]
  6 -> 3 [label="HTTP: PUT" color="red" style=dashed arrowhead=open]
  6 -> 4 [label="HTTP: DELETE" color="red" style=dashed arrowhead=open]
  6 -> 5 [label="HTTP: *" color="red" style=dashed arrowhead=open]
  6 [label="/api/Values/{...}/"]
  7 [label="/api/Values/ HTTP: GET" shape=box style=filled color="brown" fontcolor="white"]
  8 [label="/api/Values/ HTTP: POST" shape=box style=filled color="brown" fontcolor="white"]
  9 [label="/api/Values/ HTTP: *" shape=box style=filled color="brown" fontcolor="white"]
  10 -> 6 [label="/*" arrowhead=diamond color="blue"]
  10 -> 7 [label="HTTP: GET" color="red" style=dashed arrowhead=open]
  10 -> 8 [label="HTTP: POST" color="red" style=dashed arrowhead=open]
  10 -> 9 [label="HTTP: *" color="red" style=dashed arrowhead=open]
  10 [label="/api/Values/"]
  11 -> 10 [label="/Values"]
  11 [label="/api/"]
  12 -> 1 [label="/healthz"]
  12 -> 11 [label="/api"]
  12 [label="/"]
}

Note the "HTTP: *" nodes are associated with an endpoint, even though you might not expect it, because they return a 405 Method Not Allowed.

In the next post, I'll show how you can generate endpoint graphs for your own ASP.NET Core applications.

Summary

In this post I provided an introduction to the DOT language for describing graphs, and showed how you can use online editors to create images from the graphs. I then showed how routing for endpoints in an ASP.NET Core 3.x application can be represented as a directed graph. I described the differences between various nodes and edges in the endpoint graph, and tweaked the graph's display to better represent these differences. In later posts I'll show how you can generate your own endpoint graphs for your application, how to customise the display, and how to do more than just view the graphs.

Getting started with ASP.NET Core

Andrew Lock "Sock" — Tue, 23 Jun 2020 10:00:00 +0000

The Manning Early Access Program (MEAP) has started for the second edition of my book ASP.NET Core in Action, Second Edition. This post gives you a sample of what you can find in the book. If you like what you see, please take a look - for now you can even get a 40% discount with the code bllock2. On top of that, you'll also get a copy of the first edition, free!

The Manning Early Access Program provides you full access to books as they are written, You get the chapters as they are produced, plus the finished eBook as soon as it’s ready, and the paper book long before it's in bookstores. You can also interact with the author (me!) on the forums to provide feedback as the book is being written.

When to choose ASP.NET Core

This article assumes that you have a general grasp of what ASP.NET Core is and how it was designed. You might be wondering: should you use it? Microsoft is recommending that all new .NET web development should use ASP.NET Core, but switching to or learning a new web stack is a big ask for any developer or company. In this article I cover:

What sort of applications you can build with ASP.NET Core
Some of the highlights of ASP.NET Core
Why you should consider using ASP.NET Core for new applications
Things to consider before converting existing ASP.NET applications to ASP.NET Core

What type of applications can you build?

ASP.NET Core provides a generalized web framework that can be used for a variety of applications. It can most obviously be used for building rich, dynamic websites, whether they’re e-commerce sites, content-based sites, or large n-tier applications—much the same as the previous version of ASP.NET.

When .NET Core was originally released, there were few third-party libraries available for building these types of complex applications. After several years of active development, that’s no longer the case. Many developers have updated their libraries to work with ASP.NET Core, and many other libraries have been created to target ASP.NET Core specifically. For example, the open source content management system (CMS), Orchard has been redeveloped as Orchard Core to run on ASP.NET Core. In contrast, the cloudscribe CMS project (figure 1) was written specifically for ASP.NET Core from its inception.

Figure 1. The .NET Foundation website (https://dotnetfoundation.org/) is build using the cloudscribe CMS and ASP.NET Core

Traditional, page-based server-side-rendered web applications are the bread and butter of ASP.NET development, both with the previous version of ASP.NET and with ASP.NET Core. Additionally, single-page applications (SPAs), which use a client-side framework that commonly talks to a REST server, are easy to create with ASP.NET Core. Whether you’re using Angular, Vue, React, or some other client-side framework, it’s easy to create an ASP.NET Core application to act as the server-side API.

DEFINITION REST stands for Representational State Transfer. RESTful applications typically use lightweight and stateless HTTP calls to read, post (create/update), and delete data.

ASP.NET Core isn’t restricted to creating RESTful services. It’s easy to create a web service or remote procedure call (RPC)-style service for your application, depending on your requirements, as shown in figure 2. In the simplest case, your application might expose only a single endpoint, narrowing its scope to become a microservice. ASP.NET Core is perfectly designed for building simple services thanks to its cross-platform support and lightweight design.

Figure 2. ASP.NET Core can act as the server-side application for a variety of different clients: it can serve HTML pages for traditional web applications, it can act as a REST API for client-side SPA applications, or it can act as an ad-hoc RPC service for client applications.

You should consider multiple factors when choosing a platform, not all of which are technical. One such factor is the level of support you can expect to receive from its creators. For some organizations, this can be one of the main obstacles to adopting open source software. Luckily, Microsoft has pledged to provide full support for Long Term Support (LTS) versions of .NET Core and ASP.NET Core for at least three years from the time of their release. And as all development takes place in the open, you can sometimes get answers to your questions from the general community, as well as from Microsoft directly.

When deciding whether to use ASP.NET Core, you have two primary dimensions to consider: whether you’re already a .NET developer, and whether you’re creating a new application or looking to convert an existing one.

If you’re new to .NET development

If you’re new to .NET development and are considering ASP.NET Core, then welcome! Microsoft is pushing ASP.NET Core as an attractive option for web development beginners, but taking .NET cross-platform means it’s competing with many other frameworks on their own turf. ASP.NET Core has many selling points when compared to other cross-platform web frameworks:

It’s a modern, high-performance, open source web framework.
It uses familiar design patterns and paradigms.
C# is a great language (or you can use VB.NET or F# if you prefer).
You can build and run on any platform.

ASP.NET Core is a re-imagining of the ASP.NET framework, built with modern software design principles on top of the new .NET Core platform. Although new in one sense, .NET Core has several years of widespread production use, and has drawn significantly from the mature, stable, and reliable .NET Framework, which has been used for nearly two decades. You can rest easy knowing that by choosing ASP.NET Core and .NET Core, you’ll be getting a dependable platform as well as a fully-featured web framework.

Many of the web frameworks available today use similar, well-established design patterns, and ASP.NET Core is no different. For example, Ruby on Rails is known for its use of the Model-View-Controller (MVC) pattern; Node.js is known for the way it processes requests using small discrete modules (called a pipeline); and dependency injection is found in a wide variety of frameworks. If these techniques are familiar to you, you should find it easy to transfer them across to ASP.NET Core; if they’re new to you, then you can look forward to using industry best practices!

The primary language of .NET development, and ASP.NET Core in particular, is C#. This language has a huge following, and for good reason! As an object-oriented C-based language, it provides a sense of familiarity to those used to C, Java, and many other languages. In addition, it has many powerful features, such as Language Integrated Query (LINQ), closures, and asynchronous programming constructs. The C# language is also designed in the open on GitHub, as is Microsoft’s C# compiler, codenamed Roslyn.

The primary language of .NET development and ASP.NET Core is C#. This language has a huge following, and for good reason! As an object-oriented C-based language it provides a sense of familiarity to those familiar with C, Java, and many other languages. In addition, it has many powerful features, such as Language Integrated Query (LINQ), closures, and asynchronous programming constructs. The C# language is also designed in the open on GitHub, as is Microsoft’s C# compiler, code-named Roslyn ¹.

NOTE If you want to learn C#, I recommend C# in Depth, Fourth Edition by Jon Skeet (Manning, 2019), and Code like a Pro in C#, by Jort Rodenburg (Manning, 2021).

One of the major selling points of ASP.NET Core and .NET Core is the ability to develop and run on any platform. Whether you’re using a Mac, Windows, or Linux, you can run the same ASP.NET Core apps and develop across multiple environments. As a Linux user, a wide range of distributions are supported (RHEL, Ubuntu, Debian, Cent-OS, Fedora, and openSUSE, to name a few), so you can be confident your operating system of choice will be a viable option. ASP.NET Core even runs on the tiny Alpine distribution, for truly compact deployments to containers.

Built with containers in mind

Traditionally, web applications were deployed directly to a server, or more recently, to a virtual machine. Virtual machines allow operating systems to be installed in a layer of virtual hardware, abstracting away the underlying hardware. This has several advantages over direct installation, such as easy maintenance, deployment, and recovery. Unfortunately, they’re also heavy both in terms of file size and resource use.

This is where containers come in. Containers are far more lightweight and don’t have the overhead of virtual machines. They’re built in a series of layers and don’t require you to boot a new operating system when starting a new one. That means they’re quick to start and are great for quick provisioning. Containers, and Docker in particular, are quickly becoming the go-to platform for building large, scalable systems.

Containers have never been a particularly attractive option for ASP.NET applications, but with ASP.NET Core, .NET Core, and Docker for Windows, that’s all changing. A lightweight ASP.NET Core application running on the cross-platform .NET Core framework is perfect for thin container deployments. You can learn more about your deployment options in chapter 16.

As well as running on each platform, one of the selling points of .NET is the ability to write and compile only once. Your application is compiled to Intermediate Language (IL) code, which is a platform-independent format. If a target system has the .NET Core platform installed, then you can run compiled IL from any platform. That means you can, for example, develop on a Mac or a Windows machine and deploy the exact same files to your production Linux machines. This compile-once, run-anywhere promise has finally been realized with ASP.NET Core and .NET Core.

If you’re a .NET Framework developer creating a new application

If you’re a .NET developer, then the choice of whether to invest in ASP.NET Core for new applications has largely been a question of timing. Early versions of .NET Core were lacking in some features that made it hard to adopt. With the release of .NET Core 3.1 and .NET 5, that is no longer a problem; Microsoft now explicitly advises that all new .NET applications should use .NET Core. Microsoft has pledged to provide bug and security fixes for the older ASP.NET framework, but it won’t receive any more feature updates. .NET Framework isn’t being removed, so your old applications will continue to work, but you shouldn’t use it for new development.

The main benefits of ASP.NET Core over the previous ASP.NET framework are:

Cross-platform development and deployment
A focus on performance as a feature
A simplified hosting model
Regular releases with a shorter release cycle
Open source
Modular features

As a .NET developer, if you aren’t using any Windows-specific constructs, such as the Registry, then the ability to build and deploy applications cross-platform opens the door to a whole new avenue of applications: take advantage of cheaper Linux VM hosting in the cloud, use Docker containers for repeatable continuous integration, or write .NET code on your Mac without needing to run a Windows virtual machine. ASP.NET Core, in combination with .NET Core, makes all this possible.

.NET Core is inherently cross-platform, but you can still use platform-specific features if you need to. For example, Windows-specific features like the Registry or Directory Services can be enabled with a compatibility pack² that makes these APIs available in .NET Core. They’re only available when running .NET Core on Windows, not on Linux or macOS, so you need to take care that such applications only run in a Windows environment, or account for the potential missing APIs.

The hosting model for the previous ASP.NET framework was a relatively complex one, relying on Windows IIS to provide the web server hosting. In a cross-platform environment, this kind of symbiotic relationship isn’t possible, so an alternative hosting model has been adopted, one which separates web applications from the underlying host. This opportunity has led to the development of Kestrel: a fast, cross-platform HTTP server on which ASP.NET Core can run.

Instead of the previous design, whereby IIS calls into specific points of your application, ASP.NET Core applications are console applications that self-host a web server and handle requests directly, as shown in figure 3. This hosting model is conceptually much simpler and allows you to test and debug your applications from the command line, though it doesn’t remove the need to run IIS (or equivalent) in production.

Figure 3. The difference between hosting models in ASP.NET (top) and ASP.NET Core (bottom). With the previous version of ASP.NET, IIS is tightly coupled with the application. The hosting model in ASP.NET Core is simpler; IIS hands off the request to a self-hosted web server in the ASP.NET Core application and receives the response, but has no deeper knowledge of the application.

Changing the hosting model to use a built-in HTTP web server has created another opportunity. Performance has been somewhat of a sore point for ASP.NET applications in the past. It’s certainly possible to build high-performing applications—Stack Overflow (https://stackoverflow.com) is testament to that—but the web framework itself isn’t designed with performance as a priority, so it can end up being somewhat of an obstacle.

To be competitive cross-platform, the ASP.NET team have focused on making the Kestrel HTTP server as fast as possible. TechEmpower (www.techempower.com/benchmarks) has been running benchmarks on a whole range of web frameworks from various languages for several years now. In Round 19 of the plain text benchmarks, TechEmpower announced that ASP.NET Core with Kestrel was the fastest of over 400 frameworks tested³!

Web servers – naming things is hard

One of the difficult aspects of programming for the web is the confusing array of often conflicting terminology. For example, if you’ve used IIS in the past, you may have described it as a web server, or possibly a web host. Conversely, if you’ve ever built an application using Node.js, you may have also referred to that application as a web server. Alternatively, you may have called the physical machine on which your application runs a web server!

Similarly, you may have built an application for the internet and called it a website or a web application, probably somewhat arbitrarily based on the level of dynamism it displayed.

When I say “web server” in the context of ASP.NET Core, I am referring to the HTTP server that runs as part of your ASP.NET Core application. By default, this is the Kestrel web server, but that’s not a requirement. It would be possible to write a replacement web server and substitute it for Kestrel if you desired.

The web server is responsible for receiving HTTP requests and generating responses. In the previous version of ASP.NET, IIS took this role, but in ASP.NET Core, Kestrel is the web server.

I will only use the term web application to describe ASP.NET Core applications, regardless of whether they contain only static content or are completely dynamic. Either way, they’re applications that are accessed via the web, so that name seems the most appropriate!

Many of the performance improvements made to Kestrel did not come from the ASP.NET team themselves, but from contributors to the open source project on GitHub. Developing in the open means you typically see fixes and features make their way to production faster than you would for the previous version of ASP.NET, which was dependent on .NET Framework and Windows and, as such, had long release cycles.

In contrast, .NET Core, and hence ASP.NET Core, is designed to be released in small increments. Major versions will be released on a predictable cadence, with a new version every year, and a new Long Term Support (LTS) version released every two years. In addition, bug fixes and minor updates can be released as and when they’re needed. Additional functionality is provided as NuGet packages, independent of the underlying .NET Core platform.

NOTE NuGet is a package manager for .NET that enables importing libraries into your projects. It’s equivalent to Ruby Gems, npm for JavaScript, or Maven for Java.

To enable this, ASP.NET Core is highly modular, with as little coupling to other features as possible. This modularity lends itself to a pay-for-play approach to dependencies, where you start from a bare-bones application and only add the additional libraries you require, as opposed to the kitchen-sink approach of previous ASP.NET applications. Even MVC is an optional package! But don’t worry, this approach doesn’t mean that ASP.NET Core is lacking in features; it means you need to opt in to them. Some of the key infrastructure improvements include:

Middleware “pipeline” for defining your application’s behavior
Built-in support for dependency injection
Combined UI (MVC) and API (Web API) infrastructure
Highly extensible configuration system
Scalable for cloud platforms by default using asynchronous programming

Each of these features was possible in the previous version of ASP.NET but required a fair amount of additional work to set up. With ASP.NET Core, they’re all there, ready, and waiting to be connected!

Microsoft fully supports ASP.NET Core, so if you have a new system you want to build, then there’s no significant reason not to. The largest obstacle you’re likely to come across is when you want to use programming models that are no longer supported in ASP.NET Core, such as Web Forms or WCF server (more about that in the next section).

Hopefully, this section has whetted your appetite with some of the many reasons to use ASP.NET Core for building new applications. But if you’re an existing ASP.NET developer considering whether to convert an existing ASP.NET application to ASP.NET Core, that’s another question entirely.

Converting an existing ASP.NET application to ASP.NET Core

In contrast with new applications, an existing application is presumably already providing value, so there should always be a tangible benefit to performing what may amount to a significant rewrite in converting from ASP.NET to ASP.NET Core. The advantages of adopting ASP.NET Core are much the same as for new applications: cross-platform deployment, modular features, and a focus on performance. Determining whether the benefits are sufficient will depend largely on the particulars of your application, but there are some characteristics that are clear indicators against conversion:

Your application uses ASP.NET Web Forms
Your application is built using WCF
Your application is large, with many “advanced” MVC features

If you have an ASP.NET Web Forms application, then attempting to convert it to ASP.NET Core isn’t advisable. Web Forms is inextricably tied to System.Web.dll, and as such will likely never be available in ASP.NET Core. Converting an application to ASP.NET Core would effectively involve rewriting the application from scratch, not only shifting frameworks but also shifting design paradigms. A better approach would be to slowly introduce Web API concepts and try to reduce the reliance on legacy Web Forms constructs such as ViewData. You can find many resources online to help you with this approach, in particular, the https://www.asp.net/web-api website.

Windows Communication Foundation (WCF) is only partially supported in ASP.NET Core⁴. It’s possible to consume some WCF services, but support is spotty at best. There’s no supported way to host a WCF service from an ASP.NET Core application, so if you absolutely must support WCF, then ASP.NET Core may be best avoided for now.

TIP If you like WCFs RPC-style of programming, but don’t have a hard requirement on WCF itself, then consider using gRPC instead. gRPC is a modern RPC framework with many similar concepts as WCF and is supported by ASP.NET Core out-of-the-box. You can find an eBook from Microsoft on gRPC for WCF developers at https://docs.microsoft.com/en-us/dotnet/architecture/grpc-for-wcf-developers/

If your existing application is complex and makes extensive use of the previous MVC or Web API extensibility points or message handlers, then porting your application to ASP.NET Core may be more difficult. ASP.NET Core is built with many similar features to the previous version of ASP.NET MVC, but the underlying architecture is different. Several of the previous features don’t have direct replacements, and so will require rethinking.

The larger the application, the greater the difficulty you’re likely to have converting your application to ASP.NET Core. Microsoft itself suggests that porting an application from ASP.NET MVC to ASP.NET Core is at least as big a rewrite as porting from ASP.NET Web Forms to ASP.NET MVC. If that doesn’t scare you, then nothing will!

If an application is rarely used, isn’t part of your core business, or won’t need significant development in the near term, then I strongly suggest you don’t try to convert it to ASP.NET Core. Microsoft will support .NET Framework for the foreseeable future (Windows itself depends on it!) and the payoff in converting these “fringe” applications is unlikely to be worth the effort.

So, when should you port an application to ASP.NET Core? As I’ve already mentioned, the best opportunity for getting started is on small, green-field, new projects instead of existing applications. That said, if the existing application in question is small, or will need significant future development, then porting may be a good option. It is always best to work in small iterations where possible, rather than attempting to convert the entire application at once. But if your application consists primarily of MVC or Web API controllers and associated Razor views, then moving to ASP.NET Core may well be a good choice.

Summary

That’s all for this article. If you want to see more of the book’s contents, you can preview them on our browser-based liveBook platform here. Don’t forget to save 40% with code bllock2 at manning.com.

The C# language and .NET Compiler Platform GitHub source code repository can be found at https://github.com/dotnet/roslyn. ↩
The Windows Compatibility Pack is designed to help port code from .NET Framework to .NET Core. See http://mng.bz/50hu. ↩
As always in web development, technology is in a constant state of flux, so these benchmarks will evolve over time. Although ASP.NET Core may not maintain its top ten slot, you can be sure that performance is one of the key focal points of the ASP.NET Core team. ↩
You can find the client libraries for using WCF with .NET Core at https://github.com/dotnet/wcf. ↩

Adding host filtering to Kestrel in ASP.NET Core

Andrew Lock "Sock" — Tue, 16 Jun 2020 09:00:00 +0000

Host filtering, restricting the hostnames that your app responds to, is recommended whenever you're running in production for security reasons. In this post, I describe how to add host filtering to an ASP.NET Core application.

What is host filtering?

When you run an ASP.NET Core application using Kestrel, you can choose the ports it binds to, as I described in a previous post. You have a few options:

Bind to a port on the loopback (localhost) address
Bind to a port on a specific IP address
Bind to a port on any IP address on the machine.

Note that we didn't mention a hostname (e.g. example.org) at any point here - and that's because Kestrel doesn't bind to a specific host name, it just listens on a given port.

Note that HTTP.sys can be used to bind to a specific hostname.

DNS is used to convert the hostname you type in your address bar to an IP address, and typically port 80, or (443 for HTTPS). You can simulate configuring DNS with a provider locally be editing the hosts file on your local machine, as I'll show in the remainder of this section

On Linux, you can run sudo nano /etc/hosts to edit the hosts file. On Windows, open an administrative command prompt, and run notepad C:\Windows\System32\drivers\etc\hosts. At the bottom of the file, add entries for site-a.local and site-b.local that point to your local machine:

# Other existing configuration
# For example:
#
# 102.54.94.97 rhino.acme.com # source server
# 38.25.63.10 x.acme.com # x client host

127.0.0.1 site-a.local
127.0.0.1 site-b.local

Now create a simple ASP.NET Core app, for example using dotnet new webapi. By default, if you run dotnet run, your application will listen on ports 5000 (HTTP) and 5001 (HTTPS), on all IP addresses. If you navigate to https://localhost:5001/weatherforecast, you'll see the results from the standard default WeatherForecastController.

Thanks to your additions to the hosts file, you can now also access the site at site-a.local and site-b.local, for example, https://site-a.local:5001/weatherforecast:

You'll need to click through some SSL warnings to view the example above, as the development SSL is only valid for localhost, not our custom domain.

By default, there's no host filtering, so you can access the ASP.NET Core app via localhost, or any other hostname that maps to your IP address, such as our custom site-a.local domain. But why does that matter?

Why should you use host filtering?

The Microsoft documentation points out that you should use host filtering for a couple of reasons:

There are several attacks which rely on an apps responding to requests, regardless of the host name:

A DNS rebinding attack, that allows attackers to execute code on your machine if you're running a server on localhost.
Cache poisoning attacks
Password reset hijacking

The latter two attacks essentially rely on an application "echoing" the hostname used to access the website when generating URLs.

You can easily see this vulnerability in an ASP.NET Core app if you generate an absolute URL, for use in a password reset email for example. As a simple example, consider the controller below: this generates an absolute link to the WeatherForecast action (shown in the previous image):

Specifying the protocol means an absolute URL is generated instead of a relative link. There are various other methods that generate absolute links, as well as others on the LinkGenerator.

[ApiController]
[Route("[controller]")]
public class ValuesController : Controller
{
    [HttpGet]
    public string GetPasswordReset()
    {
        return Url.Action("Get", "WeatherForecast", values: null, protocol: "https");
    }
}

Depending on the hostname you access the site with, a different link is generated. By leveraging "forgot your password" functionality, an attacker could send an email from your system to any of your users with a link to a malicious domain under the attacker's control!

Hopefully we can all agree that's bad… luckily the fix isn't hard.

Enabling host filtering for Kestrel

Host filtering is added by default in the ConfigureWebHostDefaults() method, but it's disabled by default. If you're using this method, you can enable the middleware by setting the "AllowedHosts" value in the app's IConfiguration.

In the default templates, this value is set to * in appsettings.json, which disables the middleware. To add host filtering, add a semicolon delimited list of hostnames:

{
  "AllowedHosts": "site-a.local;localhost"
}

You can set the configuration value using any enabled configuration provider, for example using an environment variable.

With this value set, you can still access the allowed host names, but all other requests to other hosts will return a 400 response, stating the hostname is invalid:

If you're not using the ConfigureWebHostDefaults() method, you need to configure the HostFilteringOptions yourself, and add the HostFilteringMiddleware manually to your middleware pipeline. You can configure these in Startup.ConfigureServices(). For example, the following uses the "AllowedHosts" configuration setting, in a similar way to the defaults:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        // ..other config

        // "AllowedHosts": "localhost;127.0.0.1;[::1]"
        var hosts = Configuration["AllowedHosts"]?
                        .Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
        if(hosts?.Length > 0)
        {
            services.Configure<HostFilteringOptions>(
                options => options.AllowedHosts = hosts;
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        // Should be first in the pipeline
        app.UseHostFiltering();

        // .. other config

    }
}

This is very similar to the default configuration used by ConfigureWebHostDefaults(), though it doesn't allow changing the configured hosts at runtime. See the default implementation if that's something you need.

The default configuration uses an IStartupFilter, HostFilteringStartupFilter, to add the hosting middleware, but it's internal, so you'll have to make do with the approach above.

Host filtering is especially important when you're running Kestrel on the edge, without a reverse proxy, as in most cases a reverse proxy will manage the host filtering for you. Depending on the reverse proxy you use, you may need to set the ForwardedHeadersOptions.AllowedHosts value, to restrict the allowed values of the X-Forwarded-Host header. You can read more about configuring the forwarded headers and a reverse proxy in the documentation.

Summary

In this post I described Kestrel's default behaviour, of binding to a port not a domain. I then showed how this behaviour can be used as an attack vector by generating malicious links, if you don't filter requests to only a limited number of hosts. Finally, I showed how to enable host filtering by setting the AllowedHosts value in configuration, or by manually adding the HostFilteringMiddleware.

Setting global authorization policies using the DefaultPolicy and the FallbackPolicy in ASP.NET Core 3.x

Andrew Lock "Sock" — Tue, 09 Jun 2020 09:00:00 +0000

ASP.NET Core has an extensive authorization system that you can use to create complex authorization policies. In this post, I look at the various ways you can apply these policies to large sections of your application.

I wrote about creating custom authorization policies several years ago. For a more up-to-date look, my new book ASP.NET Core in Action is currently in pre-release. Use code mllock2 to get 50% off until June 10th 2020!

We'll start by configuring a global AuthorizeFilter and see why that's no longer the recommended approach in ASP.NET Core 3.0+. We'll then look at the alternative, using endpoint routing, as well as using Razor Page conventions to apply different authorization policies to different parts of your app. We'll also compare the DefaultPolicy to the FallbackPolicy see when each of them are applied, and how you can update them.

For the purposes of this post, I'll assume you have a standard Razor Pages application, with a Startup.cs something like the following. The details of this aren't very important, I just assume you have already configured authentication and a UI system for your application.

public class Startup
{
    public IConfiguration Configuration { get; }
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        // Configure ASP.NET Core Identity + EF Core
        services.AddDbContext<AppDbContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"))
        );

        services.AddDefaultIdentity<IdentityUser>()
            .AddEntityFrameworkStores<AppDbContext>();

        // Add Razor Pages services
        services.AddRazorPages();

        // Add base authorization services
        services.AddAuthorization();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseStaticFiles();

        // Ensure the following middleware are in the order shown
        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            // Add Razor Pages to the application
            endpoints.MapRazorPages();
        });
    }
}

At this point, you have authentication, and you want to start protecting your application. You could apply [Authorize] attributes to every Razor Page, but you want to be a bit safer, and apply authorization globally, to all the pages in your application. For the rest of this post, we look at the various options available.

Globally applying an AuthorizeFilter

The first option is to apply an AuthorizeFilter globally to all your MVC actions and Razor Pages. This is the approach traditionally used in earlier versions of ASP.NET Core.

Note that this is not the recommend approach to apply authorization globally in ASP.NET Core 3.0+. You'll see other approaches later in the post.

For example, you can add an AuthorizeFilter to all your Razor Page actions when configuring your Razor Pages in ConfigureServices (you can configure MVC controllers in a similar way):

public void ConfigureServices(IServiceCollection services)
{
    // ...other config as before

    // Add a default AuthorizeFilter to all endpoints
    services.AddRazorPages()
        .AddMvcOptions(options => options.Filters.Add(new AuthorizeFilter()));
}

This is equivalent to decorating all your Razor Pages with an [Authorize] attribute, so users are authorized using the DefaultPolicy (more on that shortly!), which by default just requires an authenticated user. If you're not authenticated, you'll be redirected to the login page for Razor Pages apps (you'll receive a 401 response for APIs).

If you want to apply a different policy, you can specify one in the constructor of the AuthorizeFilter:

public void ConfigureServices(IServiceCollection services)
{
    // ...other config as before

    // Pass a policy in the constructor of the Authorization filter
    services.AddRazorPages()
        .AddMvcOptions(options => options.Filters.Add(new AuthorizeFilter("MyCustomPolicy")));

    // Configure the custom policy
    services.AddAuthorization(options =>
    {
        options.AddPolicy("MyCustomPolicy",
            policyBuilder => policyBuilder.RequireClaim("SomeClaim"));
    });
}

The authorization filter is still applied globally, so users will always be required to login, but now they must also satisfy the "MyCustomPolicy" policy. If they don't, they'll be redirected to an access denied page for Razor Pages apps (or receive a 403 for APIs).

Remember, this policy applies globally so you need to ensure your "Login" and "AccessDenied" pages are decorated with [AllowAnonymous], otherwise you'll end up with endless redirects.

Applying AuthorizeFilters like this was the standard approach for early versions of ASP.NET Core, but ASP.NET Core 3.0 introduced endpoint routing. Endpoint routing allows moving some previously-MVC-only features to being first-class citizens. Authorization is one of those features!

Using RequireAuthorization on endpoint definitions

The big problem with the AuthorizeFilter approach is that it's an MVC-only feature. ASP.NET Core 3.0+ provides a different mechanism for setting authorization on endpoints—the RequireAuthorization() extension method on IEndpointConventionBuilder.

Instead of configuring a global AuthorizeFilter, call RequireAuthorization() when configuring the endpoints of your application, in Configure():

public void ConfigureServices(IServiceCollection services)
{
    // ...other config as before

    // No need to add extra filters
    services.AddRazorPages();

    // Default authorization services
    services.AddAuthorization();
}

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        // Require Authorization for all your Razor Pages
        endpoints.MapRazorPages().RequireAuthorization();
    });
}

The net effect of this is the same as applying a global AuthorizeFilter. So why use this approach? One big advantage is the ability to add authorization for other endpoints, that aren't MVC or Razor Pages. For example, you could require authenticated requests for your health check endpoints:

app.UseEndpoints(endpoints =>
{
    // Require Authorization for all your Razor Pages
    endpoints.MapRazorPages().RequireAuthorization();
    // Also require authorization for your health check endpoints
    endpoints.MapHealthChecks("/healthz").RequireAuthorization();
});

As before, you can specify a different policy to apply in the call to RequireAuthorization(). You could also provide different policies to apply for different endpoints. In the example below I'm applying the "MyCustomPolicy" policy to the Razor Pages endpoints, and two policies, "OtherPolicy" and "MainPolicy" to the health check endpoints:

app.UseEndpoints(endpoints =>
{
    // Require Authorization for all your Razor Pages
    endpoints.MapRazorPages().RequireAuthorization("MyCustomPolicy");
    // Also require authorization for your health check endpoints
    endpoints.MapHealthChecks("/healthz").RequireAuthorization("OtherPolicy", "MainPolicy");
});

As always, ensure you've registered the policies in the call to AddAuthorization(), and ensure your added [AllowAnonymous] to your Login Access Denied pages.

If you don't provide a policy name in the RequireAuthorization() call, then the DefaultPolicy is applied. This is the same behaviour as using an [Authorize] filter without a policy name.

Changing the `DefaultPolicy` for an application

The DefaultPolicy is the policy that is applied when:

You specify that authorization is required, either using RequireAuthorization(), by applying an AuthorizeFilter, or by using the [Authorize] attribute on your actions/Razor Pages.
You don't specify which policy to use.

Out-of-the-box, the DefaultPolicy is configured as the following:

new AuthorizationPolicyBuilder()
    .RequireAuthenticatedUser()
    .Build();

That means if you're authenticated, then you're authorized. This provides the default behaviour that you're likely familiar with, of redirecting unauthenticated users to the login page, but allowing any authenticated user access to the page.

You can change the DefaultPolicy so that an empty [Authorize] attribute applies a different policy in UseAuthorization(). For example, the following sets the DefaultPolicy to a policy that requires users have the Claim "SomeClaim".

public void ConfigureServices(IServiceCollection services)
{
    // ...other config as before
    services.AddRazorPages();

    services.AddAuthorization(options =>
    {
        // Configure the default policy
        options.DefaultPolicy = new AuthorizationPolicyBuilder()
            .RequireClaim("SomeClaim")
            .Build();

        // ...other policy configuration
    });
}

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        // The default policy applies here, as no other policy set
        endpoints.MapRazorPages().RequireAuthorization();

        // DefaultPolicy not used, as OtherPolicy is provided
        endpoints.MapHealthChecks("/healthz").RequireAuthorization("OtherPolicy");

        // DefaultPolicy not applied, as authorization not required
        endpoints.MapHealthChecks("/ready");
    });
}

The example above shows when the DefaultPolicy is applied, and when it isn't. The DefaultPolicy only applies when you've request authorization and you haven't specified a different policy. So it only applies to the Razor Pages endpoints in the example above.

Applying a default policy like this can be very useful, but sometimes you want to have slightly more granular control over when to apply policies. In Razor Pages applications for example, you might want to apply a given policy to one folder, and a different policy to another folder or area. You can achieve that using Razor Pages conventions.

Applying authorization policies using conventions with Razor Pages

The Razor Pages framework is designed around a whole set of conventions that are designed to make it easy to quickly build applications. However, you can customise virtually all of those conventions when your app starts, and authorization is no different.

The Razor Page conventions allow you to set authorization requirements based on a folder, area, or page. They also allow you to mark sections and pages with AllowAnonymous in situations where you need to "punch a hole" through the default authorization policy. The documentation on this feature is excellent, so I've just provided a brief example below:

public void ConfigureServices(IServiceCollection services)
{
    // ...other config as before

    // Applying multiple conventions 
    services.AddRazorPages(options => 
    {
        // These apply authorization policies to various folders and pages
        options.Conventions.AuthorizeAreaFolder("Users", "/Accounts");
        options.Conventions.AuthorizePage("/ChangePassword");

        // You can provide the policy as an optional parameter, otherwise the DefaultPolicy is used
        options.Conventions.AuthorizeFolder("/Management", "MyCustomPolicy"); 

        // You can also configure [AllowAnonymous] for pages/folders/areas
        options.Conventions.AllowAnonymousToAreaPage("Identity", "/Account/AccessDenied");
    });

    services.AddAuthorization(options =>
    {
        // ...other policy configuration
    });
}

These conventions can be useful for broadly applying authorization policies to whole sections of your application. But what if you just want to apply authorization everywhere? That's where the FallbackPolicy comes in.

Using the FallbackPolicy to authorize everything

The FallbackPolicy is applied when the following is true:

The endpoint does not have any authorisation applied. No [Authorize] attribute, no RequireAuthorization, nothing.
The endpoint does not have an [AllowAnonymous] applied, either explicitly or using conventions.

So the FallbackPolicy only applies if you don't apply any other sort of authorization policy, including the DefaultPolicy, When that's true, the FallbackPolicy is used.

By default, the FallbackPolicy is a no-op; it allows all requests without authorization. You can change the FallbackPolicy in the same way as the DefaultPolicy, in UseAuthorization:

public void ConfigureServices(IServiceCollection services)
{
    // ...other config as before
    services.AddRazorPages();

    services.AddAuthorization(options =>
    {
        // Configure the default policy
        options.FallbackPolicy = new AuthorizationPolicyBuilder()
            .RequireClaim("SomeClaim")
            .Build();

        // ...other policy configuration
    });
}

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        // The FallbackPolicy applies here, as no other policy set
        endpoints.MapRazorPages()

        // FallbackPolicy not used, as authorization applied
        endpoints.MapHealthChecks("/healthz").RequireAuthorization("OtherPolicy");

        // FallbackPolicy not used, as DefaultPolicy applied
        endpoints.MapHealthChecks("/ready").RequireAuthorization();
    });
}

In the example above, the FallbackPolicy is set to a custom policy. It only applies to the Razor Pages endpoints, as the health check endpoints have specified authorization requirements of "OtherPolicy" and the DefaultPolicy.

With the combination of the DefaultPolicy, FallbackPolicy, Razor Page conventions, and the RequireAuthorization() extension method, you have multiple ways to apply authorization "globally" in your application. Remember that you can always override the DefaultPolicy and FallbackPolicy to achieve a more specific behaviour by applying an [Authorize] or [AllowAnonymous] attribute directly to a Razor Page or action method.

Summary

In this post I described the various options available for setting global authorization policies:

Apply an AuthorizeFilter globally. This is no longer the recommended approach, as it is limited to MVC/Razor Pages endpoints.
Call RequireAuthorization() when configuring an endpoint in UseEndpoints(). You can specify a policy to apply, or leave blank to apply the DefaultPolicy.
Apply authorization to Razor Pages using conventions when you call AddRazorPages(). You can apply authorization policies and [AllowAnonymous] using these conventions.
The DefaultPolicy is applied when you specify that authorization is required, but don't specify a policy to apply. By default, the DefaultPolicy authorizes all authenticated users.
The FallbackPolicy is applied when no authorization requirements are specified, including the [Authorize] attribute or equivalent. By default, the FallbackPolicy does not apply any authorization.

Customising the ASP.NET Core default UI without editing the PageModels

Andrew Lock "Sock" — Tue, 02 Jun 2020 09:00:00 +0000

ASP.NET Core Identity includes a default UI as a Razor library that enables you to quickly add users to an application, without having to build all the UI yourself. The downside is that if you want to customise any of the pages associated with the default UI, then you end up taking ownership of all the logic too. Even if all you want to do is add a CSS class to an element, you're stuck maintaining the underlying page handler logic too.

In this post I show how you can replace the Razor views for the default UI, without taking ownership of the business logic stored in the Razor Page PageModel code-behind files. I show how you can use the ASP.NET Core Identity scaffolder to generate the replacement Razor Pages initially, but customise these to use the existing, default, PageModels.

Background: ASP.NET Core Identity

ASP.NET Core Identity is a series of services that provide functionality for managing and signing in users. You can use the Identity services to (among other things):

Create users, and provide sign-in functionality
Secure passwords using best practice, strong, hashing algorithms
Generate short-lived tokens for email confirmation or multi-factor authentication,
Enable auto-lockout of users to prevent brute-force attacks.
Allow logging in with third-party providers like Google and Facebook.

The Identity services provide APIs for achieving all these things, but you still have to arrange them all in the right order. You also have to write the UI that users use to interact with the services. Obviously, that's a huge investment, and is working with sensitive data, so you have to be very careful not to introduce any security holes.

Prior to ASP.NET Core 2.1, your best bet for implementing this was to use the UI generated from the Visual Studio templates. Unfortunately, using templates means that your UI is fine initially, but you then have a lot of code to maintain. If a bug is found in the templates, you have to go and update it yourself. What are the chances of people doing that? Slim to none I'd wager.

Luckily, ASP.NET Core 2.1 introduced a default UI Razor Class Library that meant you could benefit from the same UI, without having dozens of Razor Pages in your application to maintain. If a bug is found in the UI, the NuGet package can be updated, and you seamlessly get the bug fix, and all is great.

Customising the default UI

Of course, using the default UI means: you have to use the default UI. I think it's generally unlikely that users will want to use the default UI in its entirety, unless you're building internal apps only, or creating a "throwaway" app. For a start, the login and register pages include references to developer documentation that most people will want to remove:

Even though the UI is contained in a Razor Class Library, you can "overwrite" individual pages, by placing your own Razor Pages in a "magic" location in your project. For example, to override the register page, you can create a Razor Page at Areas/Identity/Pages/Register.cshtml:

A valid concern would be "how do I know which pages I can override?". Luckily there's a .NET Core tool you can use to scaffold pages from Identity in the correct locations, along with supporting files.

Scaffolding Identity files with the .NET CLI

The documentation for scaffolding Identity pages is excellent, so I'll just run through the basics with the .NET CLI here. You can also use Visual Studio, but be sure to follow steps 1-3 below, otherwise you get weird random errors when running the scaffolder.

Add all the required packages to your application. If you're already using EF Core in your app, then you may already have some of these, but make sure they're all there, as missing packages can cause frustrating errors locally

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
dotnet add package Microsoft.AspNetCore.Identity.UI
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

Also make sure that the installed package versions match your project version, for example .NET Core 3.1 projects should use packages starting 3.1.x.

Confirm your project builds without errors. If it doesn't you'll get errors when scaffolding files.
Install the code generator tool globally using dotnet tool install -g dotnet-aspnet-codegenerator. Alternatively, you could install it as a local tool instead.
Run dotnet aspnet-codegenerator identity -lf from the project folder (not the solution folder), to see the list of files you can scaffold:

> dotnet aspnet-codegenerator identity -lf
Building project ...
Finding the generator 'identity'...
Running the generator 'identity'...
File List:
Account._StatusMessage
Account.AccessDenied
Account.ConfirmEmail
Account.ConfirmEmailChange
Account.ExternalLogin
Account.ForgotPassword
Account.ForgotPasswordConfirmation
Account.Lockout
... 25 more not shown!

In this case, I'm going to scaffold the Account.Register page, and remove the external login provider section completely.

You can create a Razor Pages app using the default UI by running dotnet new webapp -au Individual -uld

If you're scaffolding into a project that's configured to use the default UI, you will already have an EF Core IdentityDbContext in your application. Pass the fully namespaced name of the context in the following command, using the -dc switch, when scaffolding your files:

dotnet aspnet-codegenerator identity -dc TestApp.Data.ApplicationDbContext --files "Account.Register"

After running this command, you'll find a bunch more files in the Areas/Identity folder:

The generated pages override the equivalents in the default UI package, so any changes you make to Register.cshtml will be reflected in your app. For example, I can delete the external login provider section entirely:

The downside is that I'm now maintaining the code-behind file Register.cshtml.cs. That's 100 lines of code I'd rather not be maintaining, as I haven't changed it from the default…

Remove your liabilities - deleting the scaffolded PageModel

I don't want that code, so I'm just going to delete it! As I'm only going to make changes to the Razor views, I can delete the following files:

Areas/Identity/Pages/Account/Register.cshtml.cs — this is the PageModel implementation I don't want to have to maintain
Areas/Identity/Pages/Account/ViewImports.cshtml — No longer necessary, as there's nothing in the namespace it specifies now
Areas/Identity/Pages/_ValidationScriptsPartial.cshtml — A duplicate of the version included in the default UI. No need to override it
Areas/Identity/Pages/IdentityHostingStartup.cs — Doesn't actually configure anything, so can be deleted

Additionally, you can update Areas/Identity/Pages/ViewImports.cshtml to remove the project-specific namespaces, to leave just the following:

@using Microsoft.AspNetCore.Identity
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

At this point, your app won't compile. The Register.cshtml page will complain that you've specified a now non-existent RegisterModel as the PageModel for the Razor Page:

The final step is to update the @page directive to point to the original RegisterModel that's included with the default Identity UI, referenced in full in the example below:

@page
@model Microsoft.AspNetCore.Identity.UI.V4.Pages.Account.Internal.RegisterModel
@{
    ViewData["Title"] = "Register";
}

This is the magic step. Your application will now compile, use your custom Razor views, but use the original Razor Pages PageModels that are part of the default UI! That's much less code to maintain, and less chance to screw something up in your Identity pages

What are the downsides?

So what are the downsides of this approach? The only one I can really think of is that you're very tightly tied to the PageModels in the original Identity UI, so you have to be sure that any updates that are made to the Identity UI are reflected in your Razor Page templates as appropriate. The big advantage is that if the default UI package is updated and it doesn't make any breaking changes to the Razor templates, then you get the updates with no friction at all.

Another danger is that the inability to customise the PageModel may encourage you to do slightly janky things like @inject-ing services into the Razor views that shouldn't be there, and adding additional logic into the Razor views. I'm not suggesting you should do this. If you _do_ need to change the behaviour of the page handlers, then you should just go ahead and take ownership of that code. The point is that this technique is useful when you don't need to change the page handler logic.

Summary

In this post I gave some background on ASP.NET Core Identity and the default UI Razor Class Library that provides over 30 Razor Pages "for free". I then showed how you could use the scaffolder tool to override one of these pages when you want to change the Razor template.

The downside of this default approach is that you now have to maintain the page handlers for the scaffolded pages. That's 100s of lines of code per page that you must keep up to date when a new package version is released.

I showed how you can avoid that burden by deleting the scaffolded PageModel file, and point your Razor template to the original PageModel that comes as part of the default UI. This lets you update your Razor templates without having to take ownership of the page handler logic, potentially giving you the best of both worlds.

Strongly-typed ID update 0.2.1: Using strongly-typed entity IDs to avoid primitive obsession - Part 6

Andrew Lock "Sock" — Tue, 26 May 2020 09:00:00 +0000

Last year I wrote a series about using strongly typed IDs to avoid a whole class of bugs in C# applications. In this post I describe some recent updates to a NuGet package that drastically reduces the amount of boilerplate you have to write by auto-generating it for you at compile-time.

Background

If you don't know what strongly typed IDs are about, I suggest reading the previous posts in this series. In summary, strongly-typed IDs help avoid bugs introduced by using primitive types for entity identifiers. For example, imagine you have a method signature like the following:

public Order GetOrderForUser(Guid orderId, Guid userId);

Can you spot the bug in the method call?

public Order GetOrder(Guid orderId, Guid userId)
{
    return _service.GetOrderForUser(userId, orderId);
}

The call above accidentally inverts the order of orderId and userId when calling the method. Unfortunately, the type system doesn't help us here because both IDs are using the same type, Guid.

Strongly Typed IDs allow you to avoid these types of bugs entirely, by using different types for the entity IDs, and using the type system to best effect. This is something that's easy to achieve in some languages (e.g. F#), but is a bit of a mess in C# (at least until we get record types in C# 9!):

public readonly struct OrderId : IComparable<OrderId>, IEquatable<OrderId>
{
    public Guid Value { get; }

    public OrderId(Guid value)
    {
        Value = value;
    }

    public static OrderId New() => new OrderId(Guid.NewGuid());

    public bool Equals(OrderId other) => this.Value.Equals(other.Value);
    public int CompareTo(OrderId other) => Value.CompareTo(other.Value);

    public override bool Equals(object obj)
    {
        if (ReferenceEquals(null, obj)) return false;
        return obj is OrderId other && Equals(other);
    }

    public override int GetHashCode() => Value.GetHashCode();
    public override string ToString() => Value.ToString();

    public static bool operator ==(OrderId a, OrderId b) => a.CompareTo(b) == 0;
    public static bool operator !=(OrderId a, OrderId b) => !(a == b);
}

The StronglyTypedId NuGet package massively simplifies the amount of code you need to write to the following:

[StronglyTypedId]
public partial struct OrderId { }

On top of that, the StronglyTypedId package uses Roslyn to auto generate the additional code whenever you save a file. No need for snippets, full IntelliSense, but all the benefits of strongly-typed IDs!

So that's the background, now lets look at some of the updates

Recent updates

These updates are primarily courtesy of Bartłomiej Oryszak who did great work! There are primarily three updates:

Update to the latest version of CodeGeneration.Roslyn to support for .NET Core 3.x
Support creating JSON converters for System.Text.Json
Support for using long as a backing type for the strongly typed ID

Support for .NET Core 3.x

StronglyTypedId has now been updated to the latest version of CodeGeneration.Roslyn to support for .NET Core 3.x. This brings updates to the Roslyn build tooling, which makes the library much easier to consume. You can add a single <PackageReference> in your project.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="StronglyTypedId" Version="0.2.1" PrivateAssets="all"/>
  </ItemGroup>
</Project>

Setting PrivateAssets=all prevents the CodeGeneration.Roslyn.Attributes and StronglyTypedId.Attributes from being published to the output. There's no harm in them being there, but they're only used at compile time!

With the package added, you can now add the [StronglyTypedId] to your IDs:

[StronglyTypedId(generateJsonConverter: false)]
public partial struct OrderId {}

class Program
{
    static void Main(string[] args)
    {
        Console.WriteLine("Value = " + new OrderId().Value);
    }
}

This will generate a Guid-backed ID, with a TypeConverter, without any JSON converters. If you do want explicit JSON converters, you have another option—System.Text.Json converters.

Support for System.Text.Json converters

StronglyTypedId has always supported the Newtonsoft.Json JsonConverter but now you have another option, System.Text.Json. You can generate this converter by passing an appropriate StronglyTypedIdJsonConverter value:

[StronglyTypedId(jsonConverter: StronglyTypedIdJsonConverter.SystemTextJson)]
public partial struct OrderId {}

This generates a converter similar to the following:

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

[JsonConverter(typeof(OrderIdSystemTextJsonConverter))]
readonly partial struct OrderId : IComparable<OrderId>, IEquatable<OrderId>
{
    // other implementation
    public class OrderIdSystemTextJsonConverter : JsonConverter<OrderId>
    {
        public override OrderId Read(ref Utf8JsonReader reader, System.Type typeToConvert, JsonSerializerOptions options)
        {
            return new OrderId(System.Guid.Parse(reader.GetString()));
        }

        public override void Write(Utf8JsonWriter writer, OrderId value, JsonSerializerOptions options)
        {
            writer.WriteStringValue(value.Value);
        }
    }
}

If you want to generate both a System.Text.Json converter and a Newtonsoft.Json converter, you can use flags:

[StronglyTypedId(jsonConverter: StronglyTypedIdJsonConverter.SystemTextJson | StronglyTypedIdJsonConverter.NewtonsoftJson)
public partial struct OrderId {}

Remember, if you generate a Newtonsoft.Json converter, you'll need to add a reference to the project file.

Support for long as a backing type

The final update is adding support for using long as the backing field for your strongly typed IDs. To use long, use the StronglyTypedIdBackingType.Long option:

[StronglyTypedId(backingType: StronglyTypedIdBackingType.Long)]
public partial struct OrderId {}

The currently supported backing fields are:

Guid
int
long
string

Future work

C# 9 is bringing some interesting features, most notably source generators and record types. Both of these features have the potential to impact the StronglyTypedId package in different ways.

Source generators are designed for exactly the sort of functionality StronglyTypedId provides - build time enhancement of existing types. From a usage point of view, as far as I can tell, converting to using source generators would provide essentially the exact same experience as you can get now with CodeGeneration.Roslyn. For that reason, it doesn't really seem worth the effort looking into at this point, unless I've missed something!

Record types on the other hand are much more interesting. Records provide exactly the experience we're looking for here! With the exception of the built-in TypeConverter and JsonConverters, records seem like they would give an overall better experience out of the box. So when C#9 drops, I think this library can probably be safely retired 🙂

Summary

In this post I described some recent enhancements to the StronglyTypedId NuGet package, which lets you generate strongly-typed IDs at compile time. The updates simplify using the StronglyTypedId package in your app by supporting .NET Core 3.x, added support for System.Text.Json as a JsonConverter, and using long as a backing field. If you have any issues using the package, let me know in the issues on GitHub, or in the comments below.

Handling Web API Exceptions with ProblemDetails middleware

Andrew Lock "Sock" — Tue, 19 May 2020 10:00:00 +0000

In this short post I describe a handy error-handling middleware, created by Kristian Hellang, that is used to return ProblemDetails results when an exception occurs.

ProblemDetails and the [ApiController] attribute

ASP.NET Core 2.1 introduced the [ApiController] attribute which applies a number of common API-specific conventions to controllers. In ASP.NET Core 2.2 an extra convention was added - transforming error status codes (>= 400) to ProblemDetails.

Returning a consistent type, ProblemDetails, for all errors makes it much easier for consuming clients. All errors from MVC controllers, whether they're a 400 (Bad Request) or a 404 (Not Found), return a ProblemDetails object:

However, if your application throws an exception, you don't get a ProblemDetails response:

In the default webapi template (shown below), the developer exception page handles errors in the Development environment, producing the error above.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // Only add error handling in development environments
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

In the production environment, there's no exception middleware registered so you get a "raw" 500 status code without a message body at all:

A better option would be to consistent, and return a ProblemDetails object for exceptions too. One way to achieve this would be to create a custom error handler, as I described in a previous post. A better option is to use an existing NuGet package that handles it for you.

ProblemDetailsMiddleware

The ProblemDetailsMiddleware from Kristian Hellang does exactly what you expect - it handles exceptions in your middleware pipeline, and converts them to ProblemDetails. It has a lot of configuration options (which I'll get to later), but out of the box it does exactly what we need.

Add the Hellang.Middleware.ProblemDetails to your .csproj file, by calling dotnet add package Hellang.Middleware.ProblemDetails. The latest version at the time of writing is 5.0.0:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Hellang.Middleware.ProblemDetails" Version="5.0.0" />
  </ItemGroup>

</Project>

You need to add the required services to the DI container by calling AddProblemDetails(). Add the middleware itself to the pipeline by calling UseProblemDetails. You should add this early in the pipeline, to ensure it catches errors from any subsequent middleware:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        services.AddProblemDetails(); // Add the required services
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        app.UseProblemDetails(); // Add the middleware

        app.UseHttpsRedirection();
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

With this simple addition, if you get an exception somewhere in the pipeline (in a controller for example), you'll still get a ProblemDetails response. In the Development environment, the middleware includes the exception details and the Stack Trace:

This is more than just calling ToString() on the Exception though - the response even includes the line that threw the exception (contextCode) and includes the source code before (preContextCode) and after (postContextCode) the offending lines:

In the Production environment, the middleware doesn't include these details for obvious reasons, and instead returns the basic ProblemDetails object only.

As well as handling exceptions, the ProblemDetailsMiddleware also catches status code errors that come from other middleware too. For example, if a request doesn't match any endpoints in your application, the pipeline will return a 404. The ApiController attribute won't catch that, so it won't be converted to a ProblemDetails object.

Similarly, by default, if you send a POST request to a GET method, you'll get a 405 response, again without a method body, even if you apply the [ApiController] attribute:

With the ProblemDetailsMiddleware in place, you get a ProblemDetails response for these error codes too:

This behaviour gave exactly what I needed out-of-the-box, but you can also extensively customise the behaviour of the middleware if you need to. In the next section, I'll show some of these customization options.

Customising the middleware behaviour

You can customise the behaviour of the ProblemDetailsMiddleware by providing a configuration lambda for an ProblemDetailsOptions instance in the AddProblemDetails call:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddProblemDetails(opts => {
        // configure here
    });
}

There's lots of possible configuration settings, as shown below. Most of the configuration settings are Func<> properties, that give access to the current HttpContext, and let you control how the middleware behaves.

public class ProblemDetailsOptions
{
    public int SourceCodeLineCount { get; set; }
    public IFileProvider FileProvider { get; set; }
    public Func<HttpContext, string> GetTraceId { get; set; }
    public Func<HttpContext, Exception, bool> IncludeExceptionDetails { get; set; }
    public Func<HttpContext, bool> IsProblem { get; set; }
    public Func<HttpContext, MvcProblemDetails> MapStatusCode { get; set; }
    public Action<HttpContext, MvcProblemDetails> OnBeforeWriteDetails { get; set; }
    public Func<HttpContext, Exception, MvcProblemDetails, bool> ShouldLogUnhandledException { get; set; }
}

For example, by default, ExceptionDetails are included only for the Development environment. If you wanted to include the details in the Staging environment too, you could use something like the following:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddProblemDetails(opts =>
    {
        // Control when an exception is included
        opts.IncludeExceptionDetails = (ctx, ex) =>
        {
            // Fetch services from HttpContext.RequestServices
            var env = ctx.RequestServices.GetRequiredService<IHostEnvironment>();
            return env.IsDevelopment() || env.IsStaging();
        };
    });
}

Another thing worth pointing out is that you can control when the middleware should convert non-exception responses to ProblemDetails. The default configuration converts non-exception responses to ProblemDetails when the following is true:

The status code is between 400 and 600.
The Content-Length header is empty.
The Content-Type header is empty.

As I mentioned at the start of this post, the [ApiController] attribute from ASP.NET Core 2.2 onwards automatically converts "raw" status code results into ProblemDetails anyway. Those responses are ignored by the middleware, as the response will already have a Content-Type.

However, if you're not using the [ApiController] attribute, or are still using ASP.NET Core 2.1, then you can use the ProblemDetailsMiddleware to automatically convert raw status code results into ProblemDetails, just as you get in ASP.NET Core 2.2+.

The responses in these cases aren't identical, but they're very similar. There are small differences in the values used for the Title and Type properties for example.

Another option would be to use the ProblemDetailsMiddleware in an application that combines Razor Pages with API controllers. You could then use the IsProblem function to ensure that ProblemDetails are only generated for API controller endpoints.

I've only touched on a couple of the customisation features, but there's lots of additional hooks you can use to control how the middleware works. I just haven't had to use them, as the defaults do exactly what I need!

Summary

In this post I described the ProblemDetailsMiddleware by Kristian Hellang, that can be used with API projects to generate ProblemDetails results for exceptions. This is a very handy library if you're building APIs, as it ensures all errors return a consistent object. The project is open source on GitHub, and available on NuGet, so check it out!

Extending the shutdown timeout setting to ensure graceful IHostedService shutdown

Andrew Lock "Sock" — Tue, 12 May 2020 10:00:00 +0000

I was seeing an issue recently where our application wasn't running the StopAsync method in our IHostedService implementations when the app was shutting down. It turns out that this was due to some services taking too long to respond to the shutdown signal. In this post I show an example of the problem, discuss why it happens, and how to avoid it.

Running background services with IHostedService

ASP.NET Core 2.0 introduced the IHostedService interface for running background tasks. The interface consists of two methods:

public interface IHostedService
{
    Task StartAsync(CancellationToken cancellationToken);
    Task StopAsync(CancellationToken cancellationToken);
}

StartAsync is called when the application is starting up. In ASP.NET Core 2.x this occurs just after the application starts handling requests, while in ASP.NET Core 3.x the hosted services are started just before the application starts handling requests.

StopAsync is called when the application receives the shut down (SIGTERM) signal, for example when you push CTRL+C in the console window, or the app is stopped by the host system. This allows you to close any open connections, dispose resources, and generally clean up your class as required.

In practice, there are actually some subtleties to implementing this interface that means that you typically want to derive from the helper class BackgroundService.

Steve Gordon has a course on Pluralsight "Building ASP.NET Core Hosted Services and .NET Core Worker Services" if you want to learn more.

Problems shutting down an `IHostedService` implementation

The problem I saw recently was causing an OperationCanceledException to be thrown when the application was shutting down:

Unhandled exception. System.OperationCanceledException: The operation was canceled.
   at System.Threading.CancellationToken.ThrowOperationCanceledException()
   at Microsoft.Extensions.Hosting.Internal.Host.StopAsync(CancellationToken cancellationToken)

I traced the source of this problem to one particular IHostedService implementation. We use IHostedServices as the host for each of our Kafka consumers. The specifics of this aren't important - the key is just that shutting down the IHostedService is relatively slow: it can take several seconds to cancel the subscription.

Part of the problem is the way the Kafka library (and underlying librdkafka library) uses synchronous, blocking Consume calls, instead of async, cancellable calls. There's not a great way around that.

The easiest way to understand this issue is with an example.

Demonstrating the problem

The easiest way to understand the problem is to create an application containing two IHostedService implementations:

NormalHostedService logs when it starts up and shuts down, then returns immediately.
SlowHostedService logs when it starts and stops, but takes 10s to complete shutdown

The implementations for these two classes are shown below. The NormalHostedService is very simple:

public class NormalHostedService : IHostedService
{
    readonly ILogger<NormalHostedService> _logger;

    public NormalHostedService(ILogger<NormalHostedService> logger)
    {
        _logger = logger;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("NormalHostedService started");
        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("NormalHostedService stopped");
        return Task.CompletedTask;
    }
}

The SlowHostedService is almost identical, but it has a Task.Delay that takes 10s to simulate a slow shutdown

public class SlowHostedService : IHostedService
{
    readonly ILogger<SlowHostedService> _logger;

    public SlowHostedService(ILogger<SlowHostedService> logger)
    {
        _logger = logger;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("SlowHostedService started");
        return Task.CompletedTask;
    }

    public async Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("SlowHostedService stopping...");
        await Task.Delay(10_000);
        _logger.LogInformation("SlowHostedService stopped");
    }
}

The IHostedServices I had in practice only took 1s to shutdown, but we had many of them, so the overall effect was the same as above!

The order the services are registered in ConfigureServices is important in this case - to demonstrate the issue, we need SlowHostedService to be shut down first. Services are shut down in reverse order, which means we need to register it last:

public void ConfigureServices(IServiceCollection services)
{
    services.AddHostedService<NormalHostedService>();
    services.AddHostedService<SlowHostedService>();
}

When we run the application, you'll see the starting logs as usual:

info: ExampleApp.NormalHostedService[0]
      NormalHostedService started
info: ExampleApp.SlowHostedService[0]
      SlowHostedService started
...
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

However, if you press CTRL+C to shut down the application, there's a problem. The SlowHostedService completes shutting down, but then an OperationCanceledException is thrown:

info: Microsoft.Hosting.Lifetime[0]
      Application is shutting down...
info: ExampleApp.SlowHostedService[0]
      SlowHostedService stopping...
info: ExampleApp.SlowHostedService[0]
      SlowHostedService stopped

Unhandled exception. System.OperationCanceledException: The operation was canceled.
   at System.Threading.CancellationToken.ThrowOperationCanceledException()
   at Microsoft.Extensions.Hosting.Internal.Host.StopAsync(CancellationToken cancellationToken)
   at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.WaitForShutdownAsync(IHost host, CancellationToken token)
   at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync(IHost host, CancellationToken token)
   at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync(IHost host, CancellationToken token)
   at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Run(IHost host)
   at ExampleApp.Program.Main(String[] args) in C:\repos\andrewlock\blog-examples\SlowShutdown\Program.cs:line 16

The NormalHostedService.StopAsync() method is never called. If the service needed to do some cleanup then you have a problem. For example, maybe you need to gracefully deregister the service from Consul, or unsubscribe from Kafka topics - that won't happen now.

So what's going on here? Where's that timeout coming from?

The reason: HostOptions.ShutDownTimeout

You can find the problematic code in the framework Host implementation that runs on application shutdown. A simplified version is shown below:

internal class Host: IHost, IAsyncDisposable
{
    private readonly HostOptions _options;
    private IEnumerable<IHostedService> _hostedServices;

    public async Task StopAsync(CancellationToken cancellationToken = default)
    {
        // Create a cancellation token source that fires after ShutdownTimeout seconds
        using (var cts = new CancellationTokenSource(_options.ShutdownTimeout))
        using (var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(cts.Token, cancellationToken))
        {
            // Create a token, which is cancelled if the timer expires
            var token = linkedCts.Token;

            // Run StopAsync on each registered hosted service
            foreach (var hostedService in _hostedServices.Reverse())
            {
                // stop calling StopAsync if timer expires
                token.ThrowIfCancellationRequested();
                try
                {
                    await hostedService.StopAsync(token).ConfigureAwait(false);
                }
                catch (Exception ex)
                {
                    exceptions.Add(ex);
                }
            }
        }

        // .. other stopping code
    }
}

The key point here is the CancellationTokenSource that is configured to fire after HostOptions.ShutdownTimeout. By default, this fires after 5 seconds. That means hosted service shutdown is abandoned after 5s - shut down of all IHostedServices has to happen within this timeout.

public class HostOptions
{
    public TimeSpan ShutdownTimeout { get; set; } = TimeSpan.FromSeconds(5);
}

On the first iteration of the foreach loop, the SlowHostedService.Stopasync() executes, which takes 10s to run. On the second iteration, the 5s timeout is exceeded, and so token.ThrowIfCancellationRequested(); throws an OperationConcelledException. That exits the control flow, and NormalHostedService.Stopasync() is never executed.

There's a simple solution to this - increase the shutdown timeout!

The solution: increase the shutdown timeout

HostOptions isn't explicitly configured anywhere by default, so you will need to configure it manually in your ConfigureSerices method. For example, the following config increases the timeout to 15s:

public void ConfigureServices(IServiceCollection services)
{
    services.AddHostedService<NormalHostedService>();
    services.AddHostedService<SlowShutdownHostedService>();

    // Configure the shutdown to 15s
    services.Configure<HostOptions>(
        opts => opts.ShutdownTimeout = TimeSpan.FromSeconds(15));
}

Alternatively, you can also load the timeout from configuration. For example, if you add the following to appsettings.json:

{
    "HostOptions": {
        "ShutdownTimeout": "00:00:15"
    }
    // other config
}

You can then bind the HostOptions configuration section to the HostOptions object:

public class Startup
{
    public IConfiguration Configuration { get; }
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHostedService<NormalHostedService>();
        services.AddHostedService<SlowShutdownHostedService>();

        // bind the config to host options
        services.Configure<HostOptions>(Configuration.GetSection("HostOptions"));
    }
}

This binds the serialised TimeSpan value 00:00:15 to the HostOptions value and sets the timeout to 15s. With that configuration, now when we stop the application, the services all shutdown correctly:

info: Microsoft.Hosting.Lifetime[0]
      Application is shutting down...
info: SlowShutdown.SlowShutdownHostedService[0]
      SlowShutdownHostedService stopping...
info: SlowShutdown.SlowShutdownHostedService[0]
      SlowShutdownHostedService stopped
info: SlowShutdown.NormalHostedService[0]
      NormalHostedService stopped

Your application will now wait up to 15s for all the hosted services to finish shutting down before exiting!

Summary

In this post I discussed an issue recently where our application wasn't running the StopAsync method in our IHostedService implementations when the app was shutting down. This was due to some background services taking too long to respond to the shutdown signal, and exceeding the shutdown timeout. I demonstrated the problem with a single service taking 10s to shutdown, but in practice it happens whenever the total shutdown time for all services exceeds the default 5s.

The solution to the problem was to extend the HostOptions.ShutdownTimeout configuration value to be longer than 5s, using the standard ASP.NET Core IOptions<T> configuration system.

DEV Community: Andrew Lock "Sock"

Exploring the code behind IHttpClientFactory in depth

A brief overview of IHttpClientFactory

Creating an HttpClient and HttpMessageHandler

Creating and tracking HttpMessageHandlers in CreateHandlerEntry

Cleaning up expired handlers.

Summary

Detecting duplicate routes in ASP.NET Core: Visualizing ASP.NET Core 3.0 endpoints using GraphvizOnline - Part 5

Duplicate routes and runtime exceptions

Creating a duplicate endpoint detector

Creating a unit test to detect duplicate endpoints

Summary

Creating a custom endpoint visualization graph: Visualizing ASP.NET Core 3.0 endpoints using GraphvizOnline - Part 4

Adding configuration for the endpoint graph

Creating a custom DfaGraphWriter

Updating the Visit function to work with IDfaNode

Defining a custom WriteNode function

Summary

Adding an endpoint graph to your ASP.NET Core application: Visualizing ASP.NET Core 3.0 endpoints using GraphvizOnline - Part 2

Using DfaGraphWriter to visualize your endpoints.

Adding the graph visualizer as an endpoint

Adding the graph visualizer as a middleware branch

Generating an endpoint graph from an integration test

You can't generate the graph in an IHostedService

Summary

Visualizing ASP.NET Core endpoints using GraphvizOnline and the DOT language

Drawing graphs with GraphvizOnline and the DOT language

Visualizing ASP.NET Core endpoints as a directed graph

Understanding the different types of node.

Summary

Getting started with ASP.NET Core

When to choose ASP.NET Core

What type of applications can you build?

If you’re new to .NET development

Built with containers in mind

If you’re a .NET Framework developer creating a new application

Web servers – naming things is hard

Converting an existing ASP.NET application to ASP.NET Core

Summary

Adding host filtering to Kestrel in ASP.NET Core

What is host filtering?

Why should you use host filtering?

Enabling host filtering for Kestrel

Summary

Setting global authorization policies using the DefaultPolicy and the FallbackPolicy in ASP.NET Core 3.x

Globally applying an AuthorizeFilter

Using RequireAuthorization on endpoint definitions

Changing the DefaultPolicy for an application

Applying authorization policies using conventions with Razor Pages

Using the FallbackPolicy to authorize everything

Summary

Customising the ASP.NET Core default UI without editing the PageModels

Background: ASP.NET Core Identity

Customising the default UI

Scaffolding Identity files with the .NET CLI

Remove your liabilities - deleting the scaffolded PageModel

What are the downsides?

Summary

Strongly-typed ID update 0.2.1: Using strongly-typed entity IDs to avoid primitive obsession - Part 6

Background

Recent updates

Support for .NET Core 3.x

Support for System.Text.Json converters

Support for long as a backing type

Future work

Summary

Handling Web API Exceptions with ProblemDetails middleware

ProblemDetails and the [ApiController] attribute

ProblemDetailsMiddleware

Customising the middleware behaviour

Summary

Extending the shutdown timeout setting to ensure graceful IHostedService shutdown

Running background services with IHostedService

Problems shutting down an IHostedService implementation

Demonstrating the problem

The reason: HostOptions.ShutDownTimeout

The solution: increase the shutdown timeout

Summary

Changing the `DefaultPolicy` for an application

Problems shutting down an `IHostedService` implementation