In many of my Web applications I have a few files that are dynamically created as part of administrative tasks. These files tend to be cumulative and contain data that can be accessed directly from the file system. But... they are in effect static files, but they shouldn't be accessible by just anybody. They should still respect authentication rules.

For example, in several small apps I write application error logs into /wwwroot/admin/temp. In another application that does occasional order processing, I track processing errors in files in a similar manner.

But again - these files can potentially contain sensitive information so they shouldn't be accessible by just any user, but only by logged in Admin users or whatever elevated group of users has access to that type of information.

What exactly does wwwroot do?

The wwwroot folder in your project is the 'static files' folder for your ASP.NET Web application. As the name suggests it assumes static content that doesn't change.

wwwroot is a ASP.NET Project Thang

The way it works is that in your ASP.NET projects anything that you store in the wwwroot folder is mapped into the Web root of the published Web site so that a /wwwroot/somefile.html file maps to /somefile.html on your published Web site.

It's also possible to publish sites into subfolders or virtual folders/sites/applications (on IIS) in which case wwwroot maps to /subfolder/somefile.html.

• Running ASP.NET Core Applications as a Subfolder Application

The key here is that by default (if you don't mess with the property publish settings) all files in the wwwroot folder are published to the Web root on the publish site.

Static File Middleware

In order for static files to be actually served by ASP.NET you need to add the StaticFiles middleware in your app's startup code in program.cs:

app.UseStaticFiles()

The middleware handles the actual semantics of translating paths into static files, and also provides a host of features like virtualization of file providers, content compression and caching.

By default everything in the wwwroot folder is published and then served as public by the middleware and directly accessible by anybody browsing your site. ASP.NET doesn't restrict access to static content by default.

In most cases that's exactly what you want. Static content mostly consists of support resources for your project:

• Images
• CSS
• JavaScript
• Static Html
• Media content
• Downloadable files

and in most cases that content should be directly accessible without any authentication or other restrictions beyond site level security.

The static file middleware is not limited to what you publish in your wwwroot folder. Anything else you manually copy into the Web Root folder or dynamically create and then store there is also accessible. The default file provider points at a folder and serves all files in and below that folder.

Static Files Middleware can do More!

The default use case for the static files middleware is to serve root Web folder content from published wwwroot output, but you can use this middleware for many different scenarios by using alternate or customized the file providers (IFileProvider). For starters, you can point at a different folder than wwwroot or point at multiple folders to serve static files from, which is particularly useful for serving application specific resources that are stored separately from the Web app.

There are several different types of file stores that can be used to serve files from Resources, Azure etc. and you can implement your own IFileProvider implementations that serve from different sources.

Protecting Folders or Files in wwwroot

But... in some cases you do need to protect dynamically created files that are served as static content. Technically that's not static content, since it was generated, but it lives in the scope of the Static File middleware.

There's no 'built-in' way to secure static files served from the StaticFile middleware. If the middleware fires, the files get served.

So in order to limit access a separate approach is required that explicitly prohibits access to specific paths.

There are a few ways to do this, none of them particularly clean:

• Move files outside of wwwroot
  One thing that can be done is move files out of wwwroot and then explicitly have endpoints that either map individual files or wildcard catch-all routes for files.

• Use endpoint-routing with Catch All route You can send minimal API routes or controller routes with catch-all route parameters ({*path} or {**path}) that give you the remaining path of the Url.

• Use custom middleware Similarly you can create a generic Middleware handler that looks at all requests and explicitly filter out requests.

StaticFileOptions.OnPrepareResponse is sometimes suggested for this job, but I don't like it as an authorization boundary. That callback runs after the static-file middleware has already selected a file and prepared the response. It's useful for setting headers, but rejecting the request before static-file processing is easier to reason about.

There are other approaches I've seen suggested using custom Authorization policies and complex routing setups, but that all seems insanely complex for what is essentially a relatively simple task.

The simplest thing seems to be, intercepting the request either with a generic middleware handler, or a catch all route. Both of these use essentially the same concept of looking at the Url and deciding whether requests can go through or not - and if not forcing a login (or at least a 401 result).

My personal preference is the custom middleware which I'll describe below.

Use Custom Middleware

For an existing application that already writes files below wwwroot, the least disruptive solution is often a small generic middleware handler that examines the request path and explicitly rejects requests that aren't authorized.

Here's the relevant part of my application setup which requires authentication for any file requests comes out of an /admin folder:

app.UseRouting();

// Authentication has to run before checking ctx.User
app.UseAuthentication();

// Protect everything below /admin, including static files
// has to run before the static files middleware
app.Use(async (ctx, next) =>
{
    if (ctx.Request.Path.StartsWithSegments(
            "/admin", StringComparison.OrdinalIgnoreCase))
    {
        if (ctx.User.Identity?.IsAuthenticated != true)
        {
            ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await ctx.Response.WriteAsync("401 Unauthorized");
            return;
        }

        // Retrieve application user state from claims and validate access
        var userState = UserState.CreateUserState<WebStoreAppUserState>(ctx);
        if (!userState.IsAdmin)
        {
            ctx.Response.StatusCode = StatusCodes.Status403Forbidden;
            await ctx.Response.WriteAsync("403 Forbidden");
            return;
        }
    }

    await next();
});

// Static files are served only after the /admin check
app.UseStaticFiles();

app.UseAuthorization();

The two return statements are important: denied requests must short-circuit the middleware pipeline. Setting a status code and then calling next() still allows the static-file middleware to process the request.

I'm using application-specific UserState code here, but you can replace that check with ctx.User.IsInRole("Admin"), a claim check, or whatever authorization logic your application uses.

StartsWithSegments() also matters. A string test such as Contains("/admin/") can match unintended URLs and misses the exact /admin path. Segment matching clearly scopes the check to /admin and everything below it.

Finally, middleware order is critical:

• UseAuthentication() has to run before the custom check so that ctx.User is available for my check scenario.
• The custom check has to run before UseStaticFiles() so a rejected request never reaches static-file handling.
• If a front-end Web server serves the file directly, none of this code runs. More on that shortly.

Why MapGet() Doesn't Intercept the File

A similar approach is to use minimal APIs or a controller endpoint with a catch-all route. For minimal APIs you can use a catch-all MapGet() handler such as app.MapGet("/admin/{**path}").

Single vs Double Asterisk Catch-All Parameters

Catch-all routing parameters can use either one or two asterisks: {*path} or {**path}. Both match the remaining part of a URL, including slashes and other characters, and can also match an empty string.

The single-asterisk version URL-encodes forward slashes when generating a URL, while the double-asterisk version preserves them.

Unfortunately, in my application, which uses controller routing and static-file middleware, the MapGet() handler never fired for an existing static file.

The following did not intercept the request:

app.MapGet("/admin/{**path}", async (HttpContext ctx, string path) =>
{
  return "Path: " + path;
});

app.UseStaticFiles();
app.UseRouting();

This isn't really a route-priority problem. Static-file middleware handles a matching file and short-circuits the pipeline before the mapped endpoint executes. Moving declarations around in a Minimal API application's compact startup code can make this behavior less than obvious because route registration and middleware execution aren't the same thing.

You can make endpoint routing work by explicitly arranging the pipeline, or by having the endpoint serve the file itself. But for guarding an existing UseStaticFiles() setup, I find the slightly lower-level app.Use() handler more obvious and unambiguous.

In .NET 9 and later, MapStaticAssets() exposes static assets as endpoints and authorization metadata can be attached to those endpoints. That's useful for build-time application assets, but my files are generated at runtime and only one folder needs protection, so the small middleware check remains a better fit here.

But given the possibility of routing conflicts with .MapGet() or even an explicit route, I'm weary of using that in the future and just opt for the simpler solution of using a generic middleware handler with app.Use() as shown above. It's clear and straight forward and there's no second guessing on when it fires other than pipeline order.

Watch out for your Hosting Platform

Here's another gotcha you may have to watch for:

If you're running your ASP.NET Core application behind a Web server proxy, be aware that the server may be configured to serve static resources directly, effectively bypassing ASP.NET Core processing entirely!

Many of my Web applications still run on a self-hosted IIS VPSs.

In all of my IIS hosted apps I forward most common static file types directly through IIS because it's considerably faster than running them through the ASP.NET Core pipeline, and IIS provides automatic and highly efficient compression for text-based files:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
	<location path="." inheritInChildApplications="false">
		<system.webServer>
            <handlers>
                <!-- Watch out for this one if you're protecting HTML files! -->
                <add name="StaticFileModuleHtml" path="*.htm*" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />

				<add name="StaticFileModuleSvg" path="*.svg" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleJs" path="*.js" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleCss" path="*.css" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleJpeg" path="*.jpeg" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleJpg" path="*.jpg" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModulePng" path="*.png" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleGif" path="*.gif" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleWoff2" path="*.woff2" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleWoff" path="*.woff" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />

				<!-- Everything else goes into Kestrel -->
				<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
			</handlers>
		</system.webServer>
	</location>
</configuration>

If you do this and have a mapping for an affected extension (like *.htm* in this case for example), IIS serves the matching file without forwarding the request to Kestrel. Your entire ASP.NET Core pipeline, including authentication and the low-level middleware check, never fires. Everything discussed above is completely bypassed.

In my case this doesn't matter because the files I'm concerned about tend to use .txt or .log extensions, which I don't forward through IIS. But if you need to protect HTML documents, for example, you have to remove the path="*.htm*" handler so those requests reach ASP.NET Core and the authorization check can fire or add a special <location> sub-section that explicitly excludes the files from IIS processing.

On the flip side it's also possible to explicitly set file or folder permissions to block access to files using <location> element. However, the auth mechanism used is then outside of the ASP.NET application (Windows Auth?) which is at best... hokey. But for a quick fix if you find out you have a file that needs protecting immediately, that might do the trick.

The same warning applies to CDNs, reverse proxies and container ingress configurations that can serve files without reaching the application. Always test the request through the actual production hosting path, not just against local debug environment which always hits Kestrel.

Summary

By default, ASP.NET Core serves all content within the wwwroot directory as public static assets without authorization checks. When applications write sensitive or dynamically generated files (such as error logs or admin reports) into wwwroot, access needs to be restricted.

The most straightforward approach described in this post, is to insert a lightweight custom middleware into the pipeline to explicitly reject requests that are not authenticated. In order to do this it's important to get the order of middleware right so that the checks occur before static files are served but after authentication has provided the necessary user context to decide whether requests can proceed or not.

Officially there are quite a few approaches that can be used but personally I prefer this much more simple and explicit approach to using code to examine path and auth to accept or reject requests, vs complex authorization policies or complex routing order schemes that are often mentioned.

Resources

• Serve static files in ASP.NET Core apps
• Running ASP.NET Core Applications as a Subfolder Application

this post was created and published with the Markdown Monster Editor

Classic native Date values in JavaScript are internally represented as UTC dates. However, when you display values they are by default shown as local date/time values. I've run into this recently again with an application that was returning a mix of UTC and non-UTC dates from the server to the browser, causing some confusion. At that point I realized I was being inconsistent with my use of the my date display functions, and here I am reviewing various Date formatting and Date conversion operations.

JavaScript's core behavior is consistent once you separate two different concepts:

• The instant represented by a Date
• The timezone used to display that instant

An instant is essentially an instant in time expressed in an offset since the Unix Epoch:

January 1, 1970 00:00:00 UTC

The instant is represented via new Date().getTime() or a more precise value of Temporal.Instant which represents the unique point in time, with nanosecond precision. It is fundamentally represented as the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC), without any time zone or calendar system.

The most common usage of dates is via the Date object and its methods. Dates are stored as UTC values, but standard display of dates in the browser UI or via the debug tools shows dates in local time.

So when you output a date it looks like this (PST or America/Los Angeles timezone in this case):

new Date()
// Mon Aug 24 2026 11:33:26 GMT-0700 (Pacific Daylight Time)

my current PST timezone value is displayed with toString() or any string concat operation. Notice that the date formatter automatically adjusts for Daylight savings time of the active timezone.

I also get a time adjusted value, if I explicitly convert the value using toLocaleTimeString() which gives me just the time value as a string:

new Date().toLocaleTimeString()
// '11:33:46 AM'

I can also go the other way - if I want to actually display the UTC value I can use the following:

new Date().toLocaleTimeString(undefined, { timeZone: "UTC" });
'6:33:43 PM'

I can also specify any specific defined timezone using the familiar timezone abbreviations:

new Date().toLocaleTimeString(undefined, { timeZone: "EST" });
// '1:34:02 PM'

or using a full IANA Time Zones identifier:

new Date().toLocaleTimeString(undefined, { timeZone: "America/New_York" });
// '1:34:02 PM'

Get your Local Timezone

If you're like me you're probably used to seeing timezone values represented by their shortcut names like PST, EST, CET etc., but officially JavaScript uses IANA Time Zones which are represented like America/Los_Angeles, Pacific/Honolulu, Europe/Berlin etc. There are actually many overlapping formats such as Pacific/Honolulu, US/Hawaii and HST for my Hawaii timezone that all represent the same UTC -10 timezone.

I'm in Hood River (near Portland, OR) currently, but the active PST timezone that gets returned is America/Los_Angeles, which seems semantically very wrong, but does represent the correct UTC -8 timezone.

You can find out the local timezone like this:

Intl.DateTimeFormat(undefined, { timeZoneName: "short" })
   .resolvedOptions().timeZone;
// 'America/Los_Angeles'

or for the abbreviation.

new Intl.DateTimeFormat(undefined, { timeZoneName: "short" })
.formatToParts(new Date())
.find(x => x.type === "timeZoneName")?.value;
// PDT

Dates are Instants, Display is Local

The most important thing to keep in mind is this:

const date = new Date("2026-08-24T18:33:46.000Z");

date.toISOString();
// '2026-08-24T18:33:46.000Z'

date.toString();
// 'Mon Aug 24 2026 11:33:46 GMT-0700 (Pacific Daylight Time)'

toISOString() returns the instance UTC value with no date time offset regardless of whether the instance has a timezone or not ie. 2026-08-24T18:33:46.000Z. The Z at the end indicates the UTC timezone.

toString() and most other date output functions return local time values adjusted for the current timezone.

This is where JavaScript can be confusing because many Date methods are split between local-time and UTC-time versions:

const date = new Date("2026-08-24T18:33:46.000Z");

date.getHours();
// 11   local time for me

date.getUTCHours();
// 18   UTC time

Yeah that .getHours() value is confusing if the time instance is a UTC value, but the bottom line is that any of the 'standard' date operations use local dates unless you explicitly use the UTC or ISO functions.

Formatting Dates with Intl.DateTimeFormat

You can use toLocaleString() to format dates and times, but if you want more control you can use the Intl.DateTimeFormat object which makes formatting more explicit and reusable.

const formatter = new Intl.DateTimeFormat(undefined, {
	dateStyle: "medium",
	timeStyle: "short"
});

formatter.format(new Date("2026-08-24T18:33:46.000Z"));
// 'Aug 24, 2026, 11:33 AM'  // on my machine

The first parameter of the constructor is the locale ie. en-US or de-DE. Passing undefined use the current user's locale.

To override for a specific timezone you can explicitly specify it as part formatting parameters for timeZone. To explicitly show UTC time:

const utcFormatter = new Intl.DateTimeFormat(undefined, {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
	timeZone: "UTC",
	timeZoneName: "short"
});

utcFormatter.format(new Date("2026-08-24T18:33:46.000Z"));
// 'Aug 24, 2026, 6:33 PM UTC'

To show a specific user's timezone formatted for a specific locale:

const newYorkFormatter = new Intl.DateTimeFormat("en-US", {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
	timeZone: "America/New_York",
	timeZoneName: "short"
});

newYorkFormatter.format(new Date("2026-08-24T18:33:46.000Z"));
// 'Aug 24, 2026, 2:33 PM EDT'

Serve me this, Client me That

The way that timezone display works in browsers makes sense 99% of the time as you typically want to display the timezone as local in the client browser.

But it gets a lot more complicated when the dates are server rendered or passed from the server to the client via API calls. The issue here is that the dates on the server might be stored for a specific timezone and perhaps are even returned with that timezone information encoded into the JSON payload.

This is why most applications store dates dates as UTC and then adjust the value on the client or on the server based on user preferences configured.

UTC dates are most consistent, but for users displaying a UTC date is definitely not ideal. It might work for logs or other systems related information, but for end users local time or a selected timezone display is a requirement.

For many applications I like the second option for user-facing screens: send the timestamp as UTC or ISO 8601 in the HTML, then let client-side JavaScript render it into the user's actual local timezone - potentially adjusted for a user specified timezone.

For example:

<time datetime="2026-08-24T18:33:46.000Z" class="local-time">
	2026-08-24 18:33 UTC
</time>

and then for browser local time:

const formatter = new Intl.DateTimeFormat(undefined, {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
	timeZoneName: "short"
});

document.querySelectorAll("time.local-time").forEach(element => {
	const date = new Date(element.dateTime);
	element.textContent = formatter.format(date);
});

For a specific timezone you can specify the timezone in the constructor:

let timeZone = userConfig.timeZone;
const formatter = new Intl.DateTimeFormat(undefined, {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
    timeZone: timeZone,  // America/Los Angeles or PST
	timeZoneName: "short"
});

This gives non-JavaScript clients and crawlers a useful UTC fallback, while normal browser users get a local or user specified timezone display value.

Getting the user's TimeZone for the Server

In order for client applications to provide the timezone to the server you can detect the value on the client like this:

Intl.DateTimeFormat().resolvedOptions().timeZone;
// 'America/Los_Angeles'

and then send that to the server. AFAIK the client does not send timezone information to the server as part of browser headers by default, so some explicit API call or similar operation is required to communicate the default to the server.

New JavaScript APIs

The classic JavaScript Date object has been around forever and it's not going away. It works fine for many things, especially if you treat it as an instant and use Intl.DateTimeFormat for display.

But Date is a pretty limited API. It mixes parsing, timestamps, local timezone accessors, UTC accessors, mutable setters, and display helpers into a single object. That's a lot of behavior packed into one small type.

The newish Temporal API

The newer API to keep an eye on is Temporal. Depending on the JavaScript runtime you're targeting you may still need a polyfill, so check current browser and runtime support before using it directly in production code. But conceptually it's a much better model because it separates the things that Date blends together.

The important Temporal types are:

• Temporal.Instant - a point in time, like a better Date timestamp
• Temporal.PlainDate - a calendar date without time or timezone
• Temporal.PlainDateTime - a date and time without timezone
• Temporal.ZonedDateTime - a date and time in a specific timezone

That separation maps much more cleanly to real application data.

For example, an instant displayed in a timezone:

const instant = Temporal.Instant.from("2026-08-24T18:33:46.000Z");

const localTime = instant.toZonedDateTimeISO("America/Los_Angeles");
localTime.toString();
// '2026-08-24T11:33:46-07:00[America/Los_Angeles]'

A plain date that doesn't accidentally roll back a day:

const birthday = Temporal.PlainDate.from("2026-08-24");
birthday.toString();
// '2026-08-24'

And a timezone-aware future event:

const meeting = Temporal.ZonedDateTime.from({
	year: 2026,
	month: 8,
	day: 24,
	hour: 9,
	minute: 0,
	timeZone: "America/New_York"
});

meeting.toInstant().toString();
// '2026-08-24T13:00:00Z'

Even if you don't use Temporal yet, the model is useful: decide whether your value is an instant, a plain date, a local date/time, or a timezone-aware date/time. That decision prevents a lot of downstream confusion.

PlainDate/PlainDateTime is an odd one - it's time instant without any time zone associated with it. It's not UTC, but it's also not specifically tied to any other time zone. These values always print exactly what the values are without any transformation. One example where that's useful is Birthdays, which always are on a certain date and regardless of time zone adjustment stay on that particular date.

Personally I've not used Temporal, yet, but looking at the API I sure can see that it's useful because it allows you to be precise about what type of date you're dealing with. An Instant timestamp, a Plain date or date time value or a timezone specific date and time with the corresponding date formatting string functions to match.

Summary

JavaScript has a fair amount of options for formatting dates and dealing with dates in various time zone formats. The basic Date type is limited to using UTC or local time formats, but using INTL.DateTimeFormat allows you to create specific time instances that can be set to specific timezones which allows you to adjust dates based on user preferences beyond just the default browser time zone.

The Temporal class adds a more specific API for representing Date and Timezone values as a single instance, and goes beyond just displaying timezone adjusted values. I haven't run into a particular use case where this matters, as I typically use UTC dates and only need to display timezone adjusted values, but if you're passing date time values around between different APIs this might be useful.

Resources

• IANA Time Zones
• Intl.DateTimeFormat()
• Temporal
• Temporal.Instance

this post was created and published with the Markdown Monster Editor

By default ASP.NET applies Controller Attribute Routes on concrete types. If you create a Controller class, the class and its routes are automatically recognized by ASP.NET during the startup process.

ASP.NET scans the startup assembly for any instance controllers and adds the routes it finds on them to the route table. If you have Controllers that live in another assembly you can get those to register as well, but you have to explicitly add the assembly to be scanned to the MVC startup configuration in your startup code:

var mvcBuilder = services.AddControllersWithViews()
    // have to let MVC know we have an externally loaded controller
    .AddApplicationPart(typeof(QmmApiController).Assembly);

Things get more complicated when you want to inherit controllers as it's not always obvious how routed endpoints are making their routes available in an inherited class.

In this post I discuss some of the issues you have to watch out for if your want to inherit controllers with routes from base classes either in the same project or an external library/project.

Controller Inheritance?

Controller inheritance is not a common use case for most people, but yet I find myself frequently using it to provide default Admin APIs or default UI behavior for templating and error handling in various generic components and application templates.

For example, in my Westwind.AspNetCore.Markdown library, a base Controller class provides the default template processing and styling for the default Markdown file rendering. In another project which is a messaging solution, a base controller provides an optional REST interface for the messaging APIs that otherwise use SignalR. In both of these cases, Controllers are shipped as part of a separate library project that is referenced via NuGet in a top level project.

In both of these cases, you have the option of overriding both the functionality and in the case of the Markdown templating library provide a custom View to customize behavior and/or UI.

Controllers vs. Minimal APIs

I realize a lot of people will scoff at using Controllers as being old fashioned, but for packaged functionality like this, Controllers are way easier to manage and to extend than creating a slew of middleware related components along with complex configuration instructions to handle extensibility. Controllers provide a rich, extensive native interface, and you can easily subclass to extend functionality. All of that comes out of the box, so for components that need Http behavior generically provided for me Controllers are my go-to.

One additional reason very relevant for this post is that using controllers it's possible to override routes. ASP.NET does not allow for duplicate routes to be defined and blows up one way or another if they are created, but with controllers there are ways that you can override this behavior, that allow you to either inherit or override routes as I discuss in this post.

AFAIK, this is not really possible with app.Map() short of explicitly mucking with the route definitions.

My Use Case and how I ended up here

As a result, I'm using Controllers for my generic API functionality in a messaging solution. As mentioned this is a REST API defined in a library class that is imported with:

var mvcBuilder = services.AddControllersWithViews()
    // have to let MVC know we have an externally loaded controller
    .AddApplicationPart(typeof(QmmApiController).Assembly);

The scenario I'm working with is the following:

• I have a base controller class public class QmmApiController : BaseApiController
  in a separate assembly that provides a base admin interface. It has a bunch of [Route()] attributes attached to it provide base API functionality.
• I then inherit from this controller public class SampleAppQmmApiController : QmmApiController
  in the top level ASP.NET application

When I try to access the routes defined in the base class as defined I end up with a 500 Internal Server Error:

Figure 1 - Routes from inherited controllers will throw a 500 error. API Access here via WebSurge.

Not a 404, but a 500... which is a pretty harsh result! 😄

If I take a closer look at the issue in the Console, I can see this log error output on the server:

Figure 2 - After inheriting from a concrete base class, I ended up with AmbiguousRoute exceptions

The ambiguous route exception is a clear hint that I - and also various LLMs - missed initially. Note that unfortunately it doesn't mention which routes are failing even though it looks like it's supposed to.

More on this failure a little bit later. But for now, realize that the routes defined on the base class are failing in the inherited class.

Controller Attribute Routes and Inheritance

As it turns out using controllers with inherited Route definitions are tricky to work with. As you can see in Figure 1 and Figure 2, the routes defined on the base class are all failing. Any routes that are explicitly defined on the concrete, top level controller work fine. Any routes defined on the concrete base class fail.

So what's going on here?

My initial thought was that ASP.NET wasn't picking up the base class routes. In fact, both I and various LLMs completely misdiagnosed the problem by assuming the routes were missing and trying to actually add the routes explicitly into the route table. That did not work!

After a lot of back and forth with various agents, and a lot of manual Console.Writeline() outputs trying to track down Routes and Endpoint mappings, it turns out that the problem is not missing routes but actually Route Duplication!

The Problem: Route Duplication

When you subclass a Controller the Attribute Routes defined on it are inherited by the child class, you now effectively have two sets of Attribute Routes: One on the base class and one on the parent class! ASP.NET detects routes on the entire class inheritance structure (as it should), so for the concrete class it picks up any routes that are explicitly defined on the concrete class and the routes from the inherited class.

ASP.NET then also picks up the base class as a separate concrete class and maps the routes defined on it.

And Bingo: You now have route duplication!

This is why we're seeing the Ambiguous Route Error shown in Figure 2.

Controller Inheritance... It's complicated

So the problem is the inheritance, but it's not quite as cut and dried as that either. There's more nuance.

In the example above - which was my original use case - the base class was a concrete instance class:

I define my top level application class like this:

public class SampleQmmApiController : QmmApiController {}

And I'm inheriting from this base class:

public class QmmApiController : BaseApiController {}

That doesn't work and gives the Ambiguous Route error.

But if I use an abstract base class to inherit from, Attribute Routes are not duplicated and an inherited controller can correctly see a single set of inherited routes projected by the inherited concrete instance:

public abstract class QmmApiController : BaseApiController {}

If you inherit this abstract class the routes now work!

Here's a table that summarizes the various modes:

The No Inheritance scenario works both for project local or imported from an external library controllers as long as .AddApplicationPart() has imported the assembly. With an instance class the routes are always-on. Makes sense - this is how controller routes are discovered by default. But in the case of an external library that exposes a controller it might be a little unexpected that any public instance controller you have in the library automatically is available for processing.

For an external library the better path most likely is to use an abstract class, which ASP.NET's parser will not automatically add to the route table. This effectively hides the routing interface and lets you explicitly enable the routes by subclassing the controller in your top level project.

Which works best depends on the scenario. For example, in my Markdown template controller I want the routes to be always active so the Markdown processing can occur. As a result I use an instance class controller. But in my queue controller scenario I want the host application to decide whether the REST API is available to access, so I use an abstract class controller.

Subclassing in both of these use cases provides the abililty to override default behavior - for the Markdown component the template usage, for the API how authentication and tokens are handled - which are common customizations for these two.

Preserving Base Class Routes

There are actually a couple of ways that you can subclass a controller and preserve the base class routes:

• Define your base class as abstract
  Abstract base classes are not picked up by ASP.NET when enumerating routes, so an abstract class when inherited can safely bring in the base class routes and you can use the endpoints as is, or override them. It just works.

• Inheriting Non-Abstract Controllers requires custom Route Manipulation
  If you decide you can't use an abstract class because you want routes to be always-on by default and still have the ability to inherit, there's a way to make this work by intercepting and modifying routes ASP.NET has auto-discovered.

Abstract Classes are Easiest

If you build library components and you want to conditionally expose routes on controllers, using an abstract base class is the easiest way to do it. By marking the controller as abstract and creating a concrete implementation class you are delegating the routes explicitly to where they are required, bypassing potentially unintended conflicts.

The downside is that you have to explicitly implement a subclass and that requires some sort of documentation so that users know that this is necessary to enable the base behavior.

Creating an IActionDescriptorProvider Route Interceptor

In order to deal with non-abstract instance Controlller base classes, we need to manipulate the ASP.NET route table after ASP.NET has picked up all the routes.

Recall that the issue is that routes get duplicated if you inherit and instance class that contains routes: You end up with the base class' routes added to the route table, and then again from the inherited class when ASP.NET scans for controller classes.

So to detect and remove the duplicated routes we can:

• Implement IActionDescriptorProvider to intercept completed Routes after auto-detection
• Remove base class routes for all or specific classes

IActionDescriptorProvider lets you intercept the Controller route handling lifecycle, and it provides a OnProvidersExecuted() method that is fired after routes have been auto-detected.

We can implement that method like this, to remove inherited routes:

namespace Westwind.AspNetCore;

/// <summary>
/// Runs after the full route table is built. Removes descriptors for base
/// controller actions when a subclass is also registered, eliminating the
/// ambiguous-route conflict (duplicate routes).
///
/// Register in Program.cs:
///   var convention = new InheritedControllerRouteConvention();
///   services.AddSingleton&lt;IActionDescriptorProvider&gt;(convention);
/// </summary>
public class InheritedControllerRouteConvention :  IActionDescriptorProvider
{
 
    /// <summary>
    /// Optionally restrict which inherited concrete controller base types 
    /// we want to allow base class routes to work on.
    /// If empty, all inherited concrete controller base types are processed.    
    /// </summary>
    public List<Type> ChildControllerTypes { get; set; } = [];

    public int Order => 0;
    public void OnProvidersExecuting(ActionDescriptorProviderContext context) { }

    /// <summary>
    /// This method finds all base controller types or those of the type(s)
    /// specified in <see cref="ChildControllerTypes"/>
    /// and removes any [Route()] attributes on the child controllers
    /// to fix the duplication of routes that break inherited controller routing.
    /// </summary>
    /// <param name="context"></param>
    public void OnProvidersExecuted(ActionDescriptorProviderContext context)
    {
        var descriptors = context.Results
            .OfType<ControllerActionDescriptor>()
            .ToList();

        var controllerTypes = descriptors
            .Select(d => d.ControllerTypeInfo.AsType())
            .Distinct()
            .ToList();

        // Find child types to process (all, or the restricted list)
        var childTypes = ChildControllerTypes.Count > 0
            ? controllerTypes.Where(t => ChildControllerTypes.Contains(t)).ToList()
            : controllerTypes;

        // Base types are those that a processed child inherits from and that are
        // also directly registered as controllers
        var baseTypesToSuppress = controllerTypes
            .Where(t => childTypes.Any(child => IsSubclassOf(child, t)))
            .ToList();

        var toRemove = descriptors
            .Where(d => baseTypesToSuppress.Any(bt => d.ControllerTypeInfo.AsType() == bt))
            .ToList();

        foreach (var d in toRemove)
            context.Results.Remove(d);
    }

    private static bool IsSubclassOf(Type child, Type parent) => child != parent && parent.IsAssignableFrom(child);

}

This code looks at all the route descriptors captured, and then looks for our matching top level controllers (or all of them if not specified). It then finds all the routes defined on inherited types of the filtered list and removes them.

When running the code you end up with a set of routes to remove - in Figure 3 the 7 routes are the base class routes in QmmApiController which is my filtered controller type that I specify.

Figure 3 - Inherited routes to remove in the IActionDescriptorProvider processing

The code to hook this up in the ASP.NET startup code in program.cs looks like this:

var inheritedRouteConvention = new InheritedControllerRouteConvention
{
    ChildControllerTypes = [typeof(SampleAppQmmApiController)]
};
// Oddly this is what triggers the convention to be used!
services.AddSingleton<IActionDescriptorProvider>(inheritedRouteConvention);

var mvcBuilder = services.AddControllersWithViews()
    // the base controller comes from an external library
    .AddApplicationPart(typeof(QmmApiController).Assembly)

You can find this component and its functionality pre-built in the Westwind.AspNetCore NuGet package.

LLM Heaven and Hell?

As you might imagine, this is the kind of thing where I engaged with LLMs - specifically with GitHub CoPilot and Claude Code with various models.

I say and with various models for a reason here, because in this case the LLMs really did an absolute shit job in a) trying to identify the problem correctly and b) providing a workable solution. So much so I switched between various tools and models several times, yet all of them came up with the same incorrect conclusion at first.

It took some extensive troubleshooting and Console.WriteLineing of routes and endpoints to properly diagnose the problem which was duplicate routes, not missing routes as the original LLM diagnoses was.

In the end, Claude Code (with Sonnet 4.6) ended up giving me a working solution but only after several very long troubleshooting loops and walking through spitting out route mappings and feeding them back into Claude and finally identifying that routes were duplicated.

Once the duplication issue was clearly established the final solution of the IActionDescriptorProvider class was adeptly created by Claude.

I will plainly admit that I probably would have not figured this out on my own. ASP.NET is powerful in the extensibility it has built in but discovering that flexibility is nearly impossible. You would think LLMs help here, but apparently at the edges in scenarios that haven't been widely published even the LLMs can end up not being a big help without some serious hands-on nudging.

Getting this done was a real slog and many, many false solutions were tried along the way trying to solve the wrong problem.

I continue to marvel at people who claim that they are one-shotting solutions and fixing problems - that never, ever seems to happen to me. I can massage an LLM into providing a solution most times, but it's never just a matter of one or even a few prompts - it's always try something and then re-direct the LLM after it's made bad assumptions. This gets very tricky in situations like this where I often don't have the expertise to check the validity of the assumptions so the only way to check is to go with it and figure it out as I go along and hope for the best...

But in the end, the LLM did provide a working solution, which on my own I likely would not have found.

As it is I spent way too much time on this 😄.

Summary

ASP.NET Controller route inheritance is not a thing you commonly do, but if you do find a use case for it, there are a number of things to watch out for.

Here are the main points summed up:

• Routes cannot be duplicated
• Instance classes automatically publish their routes including in external libs if registered
• Inherited instance Controller classes will cause route errors due to route duplication on the child class
• Abstract Controller classes do not duplicate routes and can be safely subclassed with route inheritance
• For inheriting instance Controller class you can use IActionDescriptorProvider to remove base class routes

Resources

• Westwind.AspNetCore Library on GitHub

this post was created and published with the Markdown Monster Editor