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

In my last post I described a WebPackageViewer tool tool that acts as a static Web site packager and self-contained Web site viewer all contained in a single Executable.

One feature of this single file tool is that it acts both as a GUI application (the Web site viewer) and as a CLI application (the package/unpackage tooling) from a single EXE. However, using both GUI and CLI interface from a single EXE is challenging and doesn't have a 100% clean solution. In this post I'll describe several options that make this dual mode operation work with an as clean as possible approach, as well as some alternatives that I've used in other applications.

If you think this is an off the wall concept, all of my commercial desktop applications Markdown Monster, WebSurge and Documentation Monster have a support CLI for exposing common functionality in a scriptable way. But... in all of these latter cases I actually chose a different approach of using separate EXEs for the GUI app and CLI app with the CLI app driving the GUI app features. It's a very different use case than the simple single Exe WebPackager tool and it works well for full fledged applications that expose a CLI.

CLI Interfaces

In this post I'll discuss 3 different approaches. None of them are what I would consider perfect, which would be if Windows simply supported some way to cleanly service both GUI and Console apps from a single Exe.

But alas, it's Windows so we have to live with trade-offs. Here are the three I'll discuss:

• Create a GUI application with a Console interface
• Create a Console Application and launch GUI from Console
• Create separate CLI and GUI applications with shared functionality

I've used all of these approaches now at some point or another, and it depends on the type of application or tool that you're building which makes the most sense.

GUI Application with CLI Interface Option

Mixed mode GUI app that also supports CLI output is the most tricky of these approaches, because Windows makes this sort of thing difficult with choose-one-or-the-other situation. It's also the most likely situation you're going to find yourself in when you build a GUI app and then later decide that it would be nice to add some CLI functionality.

When you build a Windows .NET application (or any Windows application for that matter) you havet to specify whether it's a WinExe (GUI) or Exe (Console) application. The type of app is written into the PE header when the EXE is created.

In .NET you can specify this in the project's header:

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<!-- Windows GUI app - Exe for Console -->
		<OutputType>WinExe</OutputType>
		
		<TargetFramework>net472</TargetFramework>
		<UseWPF>true</UseWPF>
		<Version>1.1.5.2</Version>

This affects the SubSystem value of the Windows PE header that gets generated into Windows Exes:

Figure 1 - GUI and Console apps have different startup semantics in how they related to Consoles that are attached or loaded based on the SubSystem value in the PE header.

When you launch as a Console application a new Console is started if none is active. That's when you invoke via the Windows shell or Explorer. If launched from an existing Console in the Terminal the Console app attaches to the existing Console and pipes output into it including all the Console streams (Input/Output/Error).

When you launch a GUI app from the shell, no Console is launched, so by default there's no Console - the Console points at a null console if you write to it and that output goes nowhere.

Where it gets weird is if you launch a GUI app from a Console, and you then write to the console which is the exact scenario that I'm using in WebPackageViewer.

By default the launching Console and the GUI exe are not connected and so by default Console input and output are still not going anywhere. However, it's possible to attach to an existing Console using a native AttachConsole() call from a GUI application when the application starts up, which effectively allows your GUI application to send Console output and input to and from the console.

You can use the following two P/Invoke calls (on Windows) to attach and release the Console:

[DllImport("kernel32.dll", SetLastError = true)]
static extern bool FreeConsole();

[DllImport("kernel32.dll", SetLastError = true)]
static extern bool AttachConsole(int dwProcessId);

Then as part of your application's startup code you can attach the Console:

protected override void OnStartup(StartupEventArgs e)
{
    bool attached = AttachConsole(-1);  // -1 - active console
    ...
     
    if (attached)
		Console.Write("\n✅ Launching Web Viewer...");
	
	...
	
	// when done
	if(attached)
		FreeConsole();

This sorta works.

The problem is that Console output goes into the active console that the application was started from, but if the application runs for any sort of duration, the console output gets mixed up with the existing prompt:

Figure 2 - Console Fail - In a GUI Application you can attach to a console, but the output gets very janky and the Console doesn't always return to the prompt after completion

The reason for this is that a console launched GUI application returns almost immediately to the console while the GUI app continues running in the background. The end result is that you get a new prompt that appears to be mixed into your Console output.

Depending on where the prompt occurs, it looks like the existing console's prompt is now overwriting your content, but really the prompt is left behind while your output continued into no-man's land. It displays but no longer related to the now active prompt.

Furthermore, once the native prompt has completed if you call FreeConsole() the console has now lost the prompt and essentially hangs until you press a key. While it looks like the prompt is lost, what's really happening is that the cursor appears to be at the end of the output, but the actual prompt is the prompt above in the middle of the Console output.

Yeah, it's bloody mess!

To fix this somewhat I use a helper to release the console rather than just calling FreeConsole():

[DllImport("user32.dll")] static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, nuint dwExtraInfo);

const byte VK_RETURN = 0x0D;

static void ReleaseConsolePrompt()
{
    Console.WriteLine();  // force another line break so that the prompt is on a new line
    FreeConsole();
    
    // force a CR into the console
    keybd_event(VK_RETURN, 0, 0, 0);         // key down
    keybd_event(VK_RETURN, 0, 0x0002, 0);    // key up (KEYEVENTF_KEYUP)
}

which ends up showing a new prompt at the bottom with the cursor at the active new prompt!

Can you live with it?

In a pinch, this sort of funky output works for internal applications where you have a very short output, but for a commercial tool or something that has a lot of output that takes a bit to run, that's not really an option as it just looks like shit.

What's annoying is that the behavior of the prompt can vary. I can run the same command multiple times and sometimes it'll get interrupted by the prompt, sometimes not. If your app's CLI commands run very fast within a few milliseconds you can preempt the console prompt interference. If it's very slow you can be sure it'll show up in an unexpected location.

For some applications that only occasionally use the CLI or that are driven via automation this may not matter and is acceptable. It's the easiest path of providing a CLI interface to a GUI application and may just be Good Enough.

Hackery!

For slight performance trade off you can make this a little better by essentially forcing the Console to show the new prompt immediately by waiting for a brief period with Thread.Sleep(). The idle cycle in the app makes the Console show a new, second prompt immediately.

The idea is that you preemptively force the Console to show a new prompt so it doesn't overwrite your Console output in the middle of your content.

So in WebPackageViewer I do this:

protected override void OnStartup(StartupEventArgs e)
{            
    IsConsoleApp =  AttachConsole(-1);
    if (IsConsoleApp)
    {
        // delay slightly to let existing prompt finish and then show our prompt
        System.Threading.Thread.Sleep(20);
        
        // Insert a line to clear the > prompt
        Console.WriteLine();
    }

Here's what that looks like in PowerShell with a custom OhMyPosh prompt:

Figure 3 - A GUI app with Console output that delays slightly to force the completing existing Console prompt to display immediately, which avoids overwriting our Console output.

Here's what it looks like in a plain Command prompt:

Figure 4 - Plain Command Prompt with the same delayed Console display.

If you look close you see the original Console prompt finish, and then our actual Console output is displayed. I added an extra Console.WriteLine() into the code to skip down over the prompt line (>).

Is that perfect? No, but it looks a lot cleaner than having the prompt injected in the middle, or weird line breaks showing up in your Console output. While we still can't avoid the extra prompt, at least now it's in a predictable location at the very top where it's not interfering with our Console content. And if you don't pay close attention you may not even notice that it's happening... 😉

If you want to see this all working together you can take a look in App.xaml.cs in the WebPackageViewer project.

Is Console Interface Important?

When building CLI tools, the use case is often about automation. For many CLI tools actual Console interaction may be rare anyway because the primary use case is automation.

For example, in Documentation Monster (a desktop application) I automate WebPackageViewer from the application via Process.Start(). I generate the Html Output in the application, package up the files explicitly into a Zip file, then use the packager to package the single file Exe. No Console interface accessed. I'm using the CLI interface, but I'm not ever actually looking at the Console so the output is not important - only the exit code.

In the end having a Console that doesn't behave 100% correctly may not be a big deal, especially when you can get it close enough as described above.

When to use this

If the primary application you are creating is a GUI app and the CLI functionality is secondary, then this approach can work very well for you.

For my use case in WebPackageViewer I used this approach as it was the best choice for this utility for the following reasons:

• I absolutely need a single Executable
• The GUI interface is the primary feature users see
• The CLI interface is likely automated and not actually visibly running from the command line
• The CLI output works well enough with the embellishments described in this post

This integration ticks all of these points and the only real downside is the slightly messy CLI interface with the duplicated prompt line. I can live with that! In this case.

Console Application that hosts a GUI Interface

As I've described above it's possible to create a GUI app that can interact with the Console, but you can also create the reverse: A Console application that can run a GUI application.

This might seem counter-intuitive and most likely this will come up after you've decided to build the entire application as a GUI app - as it did for me!

Realistically though the differences between a Windows GUI and Console application are relatively minor from an implementation perspective. Even for a WPF application it's possible to switch with a few lines of code. It comes down to specifying the Windows Subsystem used during build time and changing the startup code.

For .NET projects this means changing to <OutputType>Exe</OutputType>. The following is from the WebPackageViewer which deliberately builds a .NET Framework Executable to remove any runtime requirements so it works on any recent Windows machine:

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<!-- Exe: Console - WinExe: GUI -->
		<OutputType>Exe</OutputType>
		<TargetFramework>net472</TargetFramework>
		<UseWPF>true</UseWPF>
		...
	</PropertyGroup>		
</Project>	

If you're using ILMerge or ILRepack to package a single file binary, the final EXE and its PE Header is actually determined by those tools, not your project. In ILRepack this is the /target:exe or /target:winexe parameter. This means if you use these tools, it doesn't matter what you set for <OutputType> in the .NET project as the assignment overrides that value in ILMerge/ILRepack scripting!

The other thing that has to change is that a Console application has to start with a static int Main() method, so you have to explicitly add this to your application, in this case for a WPF application that initializes and runs app.xaml:

using System;
using System.IO;
using System.Runtime.InteropServices;
using WebPackageViewer;

class Program
{
    [STAThread]
    static int Main(string[] args)
    {
        var app = new App();
        app.InitializeComponent();
        app.Run();

        return 0;
    }
}

and you should explicitly specify the startup class in the .csproj file:

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<StartupObject>Program</StartupObject>
	</PropertyGroup>
</Project>

Incidentally this also works for GUI mode applications and in fact I launch all of my GUI apps this way as I generally have a few startup checks that I include before the app actually gets launched. Also a great location for a launch screen that pops quicker here than in XAML code for WPF, WinForms or WinUi frameworks startup.

If you go this route, you don't need to AttachConsole() and FreeConsole(). Any Console commands work as you'd expect including having all the Console Streams hooked up.

What's the Downside of a Console GUI Application?

Unfortunately, there is one downside to a Console application that doubles as a GUI application: A Console compiled application always displays a Console window and there's no good way to completely hide the window when the app starts up.

You can hide the Console window immediately after startup using code like this:

class Program
{
    [STAThread]
    static int Main(string[] args)
    {         
        if (!StartedFromConsole())
        {
            // hide the Console window immediately
            ShowWindow(GetConsoleWindow(), 0); // hide console flash
        }

        var app = new App();
        app.InitializeComponent();
        app.Run();

        return 0;
    }

    [DllImport("kernel32.dll", SetLastError = true)]
    static extern bool AttachConsole(int dwProcessId);

    [DllImport("kernel32.dll")]
    static extern bool FreeConsole();

    [DllImport("kernel32.dll")] static extern IntPtr GetConsoleWindow();
    [DllImport("user32.dll")] static extern bool ShowWindow(IntPtr h, int cmd);


    static bool StartedFromConsole()
    {
        if (AttachConsole(-1))
        {
            FreeConsole();
            return true;
        }

        // Already attached to a console also means console-launched.
        return Marshal.GetLastWin32Error() == 5;
    }
}

But even with this code at the very earliest possible point of .NET code entry, you'll get a brief flash or worse a slow animation of the Console Window disappearing.

The code above is also a bit simplistic as it universally hides the Console window. In reality you want to hide it selectively only when you're actually going to display UI, and leave it when you're working with the Console, which may cause you to delay the hiding a little bit longer yet, making the window flash even more pronounced.

In WebPackageViewer when I was experimenting with this, I ended up sticking the window hiding right before the Main Window of the Viewer is created:

// code in OnStartup that handles CommandLine Parsing and execution
// and UI operations

// check and hide only before actual GUI operation
if (!StartedFromConsole())
{
    // hide the Console window immediately
    ShowWindow(GetConsoleWindow(), 0); // hide console flash
}

MainWindow mainWindow = new MainWindow(config);
mainWindow.Show();

But even that may not be quite the right behavior because if you actually launch the UI application from the Console explicitly via keyboard, then you'd want the Console to stay active. There's no easy way to determine whether the Console was created by your application or an existing console in a Console app because a Console is always present.

When to use this

Functionally, a Console application with a GUI interface ticks all the boxes and gives you the best of both Console and GUI applications, except for the initial Console Window popup.

If you can live with the Console popup and it isn't a distraction to you, or if your app is primarily a Console interface, then using a Console app is the way to go.

But for me personally, I find the brief Console popup annoying and unprofessional for a GUI app, so other than for applications that are entirely CLI driven and use GUI only as adjunct, I would probably not opt for this choice.

Separate CLI Application

Another option for creating both a GUI and Console interface is to create two completely separate applications. As I've shown above both GUI app with CLI and CLI with GUI apps have quirks that make them behave not quite right for the CLI or UI scenario.

Avoiding Ambiguities

By separating out the GUI and CLI into completely separate applications you can avoid any of these ambiguities by giving each it's dedicated target Subsystem type.

This works particularly well if your CLI interface is fairly sophisticated and requires the full Console experience including the ability to be driven through Console IO.

I'm using this approach of two separate EXE interface in Markdown Monster, WebSurge and Documentation Monster and it's a relatively simple set up in that the CLI project can simply import the GUI project (or 'business' project) as a reference and get all of the same functionality as the main GUI app without the overhead of all library requirements because it uses the same libraries as the main app.

How does this work?

So, using the Markdown Monster CLI Example I have two .NET projects:

• MarkdownMonster (GUI WPF app)
• mmcli (Console App)

mmcli references MarkdownMonster which is a single assembly monolith. mmcli then calls into the MarkdownMonster and its internal libraries to use all of the built in operational logic to handle many system operations related to installation, generate html and pdf output, start and stop the internal Web server and so on. In MM it's a single monolith that contains most of the logic, but in other tools like WebSurge, a separate business library that contains most of these operations is referenced. In either case, the CLI project references the 'parent' application's libraries that are effectively shared between both projects.

Here's an example of Markdown Monster's CLI generating Html output from Markdown:

Figure 5 - Using the separate mmCli Console application in Markdown Monster to generate various types of Html output

In the project the setup looks something like this:

Figure 6 - GUI and CLI projects are separate, with the small CLI project importing all operational functionality from the GUI project (or libraries)

CLI Projects can have small Footprint

The bottom line here is that the CLI project itself is very small and only implements the command line parsing + the logic to drive the application logic to perform the operations that are defined in the main application code base (either the main EXE or some business library). When the project builds, only the CLI executables (.exe and .dll + the runtime config files) are copied into the main GUI executable's folder:

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
  <Exec Command="copy $(TargetDir)mmcli.exe $(SolutionDir)MarkdownMonster\mmcli.exe" />
  <Exec Command="copy $(TargetDir)mmcli.dll $(SolutionDir)MarkdownMonster\mmcli.dll" />
  <Exec Command="copy $(TargetDir)mmcli.runtimeconfig.json $(SolutionDir)MarkdownMonster\mmcli.runtimeconfig.json" />
  <Exec Command="copy $(TargetDir)mmcli.deps.json $(SolutionDir)MarkdownMonster\mmcli.deps.json" />
</Target>

Because both projects share the exact same dependencies, the footprint of the CLI project is tiny - just the .exe and .dll file even though the CLI project's build output is huge - roughly the same as the main GUI project. So by simply copying the binaries into the main project folder, the CLI binaries have access to everything they need and can run just fine.

When to use

If you can live with multiple executables, separate CLI and GUI projects are the cleanest solution for dual interface applications. Each application can run in its intended environment without any hacks and workarounds.

The only downside is that it takes a little extra effort to set up two separate projects and ensure that the two binaries and runtime config files are available in the right places.

Summary

Mixed mode GUI and CLI applications are not very common. Most applications stick to a simple single interface and use that. GUI applications that have some command line switches typically don't use Console interfaces to display output but rather rely on GUI prompts or forms to display information, so those typically are not dual interface either.

But when you have true dual purpose use cases like I did with WebPackageViewer then a dual interface can be quite useful to provide both a nice GUI interface and a CLI to drive it.

In this post I've described various ways you can create dual interface GUI and CLI applications:

1. GUI App with Console Interaction

• use for UI primary application (ie. a Viewer)
• easy to build
• AttachConsole() and FreeConsole()
• CLI is least desirable but works for 'quick and dirty use'

2. Console Application that Launches a GUI

• use for Console centric applications that also have UI
• requires program.cs launch for GUI (ie. a little non-standard)
• easy to build but need to isolate GUI from Console commandlines
• for GUI apps shows or at least flashes the Terminal Window

3. Separate GUI and CLI Application

• two Separate Exes
• no 'routing' required
• Separates concerns
• CLI can link in GUI app or library features
• no UI oddities for either GUI and CLI

For WebPackageViewer I opted for a GUI app as the Viewer is the primary interface that end-users see, and because the CLI automation most likely won't actually be done via a Console but through some sort of automation. Specifically in my case through I use a separate application. In that project the main reason is because of the single file requirement, so I had to choose between option 1 and 2, with 1 winning out because of the primarily GUI focus of the tool.

For most of my other much bigger application products I've chosen to use separate CLI and GUI projects because it's simply cleaner to separate out the CLI functionality into a separate binary. There are multiple reasons for this. For example, Markdown Monster already has a native command line interface that allows it to open files in various different ways, deal with single-instance limiting and other command line options that deal with application startup. In other words it already has a bunch of command line processing it has to do in various different modes. Adding CLI commands to that would actually be quite complicated. WebSurge and DocMonster have simpler command lines but there are still options to deal with and having separated, well-delineated CLI syntax is much easier to implement and also to use for users without ambiguities.

Beyond maintaining a separate project and setting up the initial build process to produce the binaries in the right place, there's virtually no downside to using separate projects as I get full access to all the functionality of the main application in the CLI project, with the clean separation of functionality. To me if this option is available, it's clearly the cleanest approach.

That leaves the Console Application with GUI launching (2), and although I was initially excited about it, the fact that the Console window pops up in GUI operation is major showstopper for me. If it weren't for that I think I would consider building every application using a Console application. It sure would be nice if Microsoft provided a way to initially hide the Console window on launch via a Manifest setting or something, but AFAIK no such thing exists - the best you can do is hide the window immediately and deal with the brief Console flash. For some situations that may not be a problem, but for me that's a non-starter. YMMV.

WebPackageViewer was an interesting experiment in that it forced me to explore several of these approaches and try to make them work 'perfectly'. In the end I managed to get several 'good enough' approaches to work, with the only near perfect solution being separate EXEs.

Ah, good enough 😂

this post was created and published with the Markdown Monster Editor