Rick Strahl's Web Log

Getting Inherited Controller Routes to work in ASP.NET Core

(Rick Strahl) — Tue, 30 Jun 2026 00:00:00 GMT

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:

Library Inheritance	Base Class Type	Result
No Inheritance	Concrete	Works (Routes recognized on library class)
No Inheritance	Abstract	not picked up by ASP.NET
Inherited	Concrete	Doesn't work (Routes on base class are ignored)
Inherited	Abstract	Works (Routes recognized on child class)

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;

/// 
/// 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<IActionDescriptorProvider>(convention);
/// 
public class InheritedControllerRouteConvention :  IActionDescriptorProvider
{
 
    /// 
    /// 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.    
    /// 
    public List ChildControllerTypes { get; set; } = [];

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

    /// 
    /// This method finds all base controller types or those of the type(s)
    /// specified in 
    /// and removes any [Route()] attributes on the child controllers
    /// to fix the duplication of routes that break inherited controller routing.
    /// 
    /// 
    public void OnProvidersExecuted(ActionDescriptorProviderContext context)
    {
        var descriptors = context.Results
            .OfType()
            .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(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

Creating Dual Use Windows GUI and Console Applications

(Rick Strahl) — Tue, 23 Jun 2026 00:00:00 GMT

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:


	
		
		WinExe
		
		net472
		true
		1.1.5.2

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 Exe. 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:


	
		
		Exe
		net472
		true
		...

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 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:


	
		Program

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:

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

Creating a Packaged Windows Single File Web Site Viewer Executable

(Rick Strahl) — Sat, 13 Jun 2026 00:00:00 GMT

This post falls squarely into the stupid pet tricks category, but I'm going to post about it anyway, because it was an interesting experiment in dynamically creating a single file, self-contained Windows executable that contains the executable, data and a native dependency.

This is about as edge case as it gets, but let me give you my scenario and why I decided to tackle this, foolishly thinking that this would be a quick afternoon project (punchline: it wasn't).

I have several Web based documentation solutions that I both publish publicly and also use for specific customer projects. Essentially these are Web site generator tools with a specific front end for creating the documentation that makes up the final documentation Web output. Because I deal quite a bit with legacy customers one issue that frequently comes up is the ability to take documentation offline while traveling or otherwise being disconnected from the Internet.

My documentation tools (and many others) generate base Html output for documentation in the form of a static Web site, and the online version of that is typically adequate for the majority of users. But a frequent option is for some form of offline output in some portable format like a PDF file or a self-contained Html document, that can be easily shared and used offline. While PDF or Html documents work and let you access the content in document form, it's more like a book - sequential and not very interactive. Web sites tend to offer a more interactive experience and in most cases a much more attractive reading experience due to richer layout and styling that isn't possible in PDF.

That got me to thinking: It would be nice to create a single file EXE package offline Web viewer, that can run the Web site locally instead. So kind of like a CHM file of old, but it's running the full documentation (or the way it's built - any dynamic Web site).

WebPackageViewer

What I came up with is WebPackageViewer, which you can find here:

WebPackageViewer on GitHub

WebPackageViewer is essentially a dual purpose application:

An Exe Packer that can pack and unpack a Web Site as Zip file into an Exe and then run into a built-in viewer application.
That same application can also run with content from disk directly as a Web Site Viewer without the packaging

In practice I use this tool as part of my Documentation Monster documentation solution as one of the output options which packages the generated Documentation Web Site into an self-contained Exe package:

Figure 1 - Generating an Exe as part of publishing options for a documentation solution.

This generates a self-contained Windows Exe that essentially lets you run the Web site in an application locally. Here's what the Viewer looks like running a packaged Web site:

Figure 2 - The Documentation Monster Web Viewer packages the generated Html Web site into a single Exe that can be run offline.

You can see what that looks like here.
(you might get a SmartScreen warning - more on that in a minute)

This tool isn't limited to documentation however. In theory you can use it for any static Html Web site that you want to publish. This can be some other document only Web site, it could be a React, Vue, Angular app, it could be a Blazor WASM app - anything that can run off static Html basically.

For publishing a full application I actually think tools like Photino or InfiniFrame provide a more complete application centric packaging solution that also have cross-platform support. OTOH, these tools also require more setup and aren't a generic, 'just do it' tool like WebPackageViewer.exe, so they a target a different use case.

How does the Web Packaging work?

What you're looking at in Figure 2 is a Web site that's launched off a single file Exe shell: The large single file Exe bundles both the executable and the entire zipped up Web site. The packaged Exe then serves both as an unpackager and viewer, running the unpackager first and then launching the viewer using the same executable.

When it runs, the Exe unpackages the embedded Zip file data into a temporary folder, copies the Exe (ie. itself!) into that folder and then relaunches itself in that folder to run the Web Site from that folder. When the app shuts down the temp folder is deleted.

The Exe itself is implemented using a Windows WPF application with a full screen WebView control and uses virtual folder hosting rather than an actual Http server to 'run' the Web site in the internal WebView browser. Virtual folder hosting eliminates the potential security issues around local port assignment or exposing an Http endpoint locally.

The Viewer application behaves just as it would inside of a browser, but there's no address bar, menus and widgets and so, it's only the raw Web browser.

Unlike a PDF or Html export, you get a fully interactive site that allows for search and navigation the same way as the online Web site but it works completely locally and offline if needed.

Cool! All of this works smoothly... but, and there's always a butt... 😂

The Fly in the Oinment: Windows SmartScreen

This is where the stupid pet tricks part kicks in: When you download an arbitrary Exe from the Internet, Windows security gets real dodgy and wants to protect you:

Figure 3 - Downloading the Documentation Exe comes with warnings!

This is not unexpected as Windows Defender Smartscreen essentially flags any unsigned, downloaded binary or a binary embedded in a downloaded archive as possibly suspect code. It is possible to bypass SmartScreen by clicking More info and then Run anyway but it's not exactly a smooth user experience to scare users with a blue screen of doom.

You can help your chances of not getting a SmartScreen dialog by signing the final executable generated, but unless you're a software developer that already is publishing and signing binary distributions, it's unfortunately not a common thing to have available, nor is the process of setting up a certificate for signing especially simple. But, if you have a certificate and process to sign - you should definitely use it on any generated Exe.

The security problems are two-fold:

The downloaded Exe is not signed
Unsigned downloaded or Zip file downloaded Exe's are always flagged by Windows SmartScreen. Because the file is generated generically signing is not an option, and...
Reputation is going to be low
SmartScreen works of install reputation, and a custom generated file is unlikely to gain real download and install traction to improve SmartScreen reputation. So even a signed executable - although better - is likely to still show the SmartScreen dialog.

Unfortunately there are no real solutions around this that I could find other than to warn users of the issue and prepare them for bypassing the SmartScreen dialog.

Local Installs are Fine

Note that SmartScreen mostly affects downloaded files and does not kick in if you install an executable as part of an application install. SmartScreen triggers mostly of MOTW (Mark of the Web), so if you install the Exe via a local installer then there's no MOTW on the Exe and SmartScreen most likely won't be a problem (it can still be based on policy or many failures but that's more rare).

Bottom line: If you plan on downloading these generated packaged Web Viewers you'll likely have to deal with SmartScreen.

Exe Packaging in .NET

FWIW, I was aware of the SmartScreen issue before I started building the packager - mostly because I thought it would be easy to build the packager and for the few people that always pester about offline documentation they would probably be willing to deal with the SmartScreen issue.

What I ended up building is WebPackageViewer.exe which is a generic tool to package WebPackageViewer and a data package into a single Exe. The viewer includes a Web UI application that handles unpacking the data content and then running the Web site inside of the WebView.

There are two parts to this application:

The Packager/Unpackager CLI Tool
The WebViewer UI application

CLI Mode

In CLI mode you can create a package by running WebPackageViewer.exe like this:

.\webPackageViewer.exe package  `
		--output .\MarkdownMonster-Docs-Viewer.exe `
		--zipfolder "c:\Web Sites\markdownmonster.west-wind.com"

Here's what that looks like:

Figure 4 - Using the Packager to create a self-contained Exe

This generates a single file Exe:

Figure 5 - The generated output file can be fairly large as it contains all the Zipped up Web site Html and support assets. The packager is relatively small.

The base executable WebViewPackager.exe can also be used as a standalone static Web site viewer by running the EXE out of a folder with Html files. By default it looks for index.html and if it exists displays that in the internal browser.

There are a number of command line options that let you customize packaging and the viewer's behavior:

Figure 6 - Command line options for the packager, unpackager, and viewer

Implementation in .NET

At the outset I mentioned that I thought this would be a quickie project and the the first run of it ended up being pretty simple. But the devil is in the details and there are lot of little gotchas to watch out for that I didn't run into until I started publishing a few documentation sites.

How it works

The main premise of this tool is the packaging of the Exe with both the main executable as well as the Web site data which lives in a zip file.

.NET Framework Executable

The first thing about this project is that it's a .NET Framework project rather than a .NET Core project. The reason for this is to create a tiny self-contained Executable for the application that has no framework dependence and - using Windows WPF in this case. .NET Core Single File AOT compilation produces large files when frameworks get involved and wouldn't work with WPF anyway - so in this case I specifically chose .NET framework since it's available on all semi-modern Windows versions in use.

Exe File Packaging

A Windows Exe file contains a PE header that describes the EXE and its length. When the Exe loads it loads the expected file size into memory. There's a lot more to this, but I'm simplifying to what's relevant here. You can however append more data to the end of the Exe file by simply writing more data after the Exe's data stream using standard file writing APIs. After you do this the Exe still works, but the Exe file now contains additional data that you can access.

Note if an Exe is Authenticode signed, and you append data to it you'll break the validity of the signature. For this reason the original WebPackagerViewer.exe is provided in both signed and unsigned versions. -unsigned.exe for packaging, and the signed version for running as a drop in Web Site viewer. s To make this work, the trick is to write a marker into the binary data that separates the original binary Exe file data and the added content which in this case will be a zip file of the Web site.

Figure 7 - Packaging an Exe with an additional payload of a Zip file

Build First using `package` Command

To build the package you use the CLI tooling I showed earlier using the package command.

.\webPackageViewer.exe package  `
		--output .\MarkdownMonster-Docs-Viewer.exe `
		--zipfolder "c:\Web Sites\markdownmonster.west-wind.com"

This creates a packaged Exe that contains the zip file data.

Alternately you can also explicitly create a Zip file using the --zipfile parameter and then attach it to the exe instead. The latter is what Documentation Monster does: It creates a custom zip file that includes a few additional files that don't exist in the original Web site folder that is packaged up. It then uses that zip file as input.

Launching the Packaged Exe triggers unpacking

Once the packaged Exe has been created, launching it now unpacks the attached Zip file, and copies the Exe to a temporary folder. The original exe then launches the copied Exe in the now unpacked Web Folder and shuts itself down.

The Exe is Re-Launched in the Web Folder

The Exe in the unpacked folder knows that it's running in an unpacked directory, and now fires up the UI interface to display the Webview control.

WebView uses Manual Handling for Https Urls

The WebView control then uses local Web resource request and navigation events to capture content load operations and serves images from the local folder using a form of virtual folder mapping.

This means the viewer application doesn't use a Web Server, but rather uses a form of virtual file mapping to execute requests locally.

The WebView2 Control supports a built-in virtual folder mapping, but unfortunately I couldn't use that due to the requirement that previewer has to support virtual subfolders (ie. the base Url running out /docs/ instead of root /). The WebView virtual hosting feature has no support for auto-routing to a sub-folder base Url and so the file translation in a virtual folder doesn't work right.

So instead, I ended up having to manually intercept the Navigation events to re-route virtual folder access, and then handle the resource loading manually. Sounds complicated but it turned out to be a surprisingly easy implementation.

You can take a look at how this works on in the source code on GitHub.

File Packaging and Unpackaging

The code to package a file and unpackage it is also relatively simple.

Creating the Exe and Zip Package

Assuming the Zip file has been created - either externally or letting the packager do it - to write out the packaged Exe, here's the logic that writes out the combined exe and data package executable:

if (first == "package")
{
    ConsoleHelper.WriteWrappedHeader("West Wind Web Package Viewer");
    Console.WriteLine("📦 Packaging zip file...");

    string zipFile = ZipFilename;

    var pack = new FilePackager();
    if (!string.IsNullOrEmpty(ZipFolder))
    {
        zipFile = pack.ZipFolder(ZipFolder);
        if (zipFile == null)
        {
            Console.WriteLine("❌ Error creating Zip file for package: " + pack.ErrorMessage);
            return;
        }
    }

    if (!pack.PackageFile(Path.GetFullPath(OutputPath),
        Path.GetFullPath(ExeFile),
        Path.GetFullPath(zipFile)))
    {
        Console.WriteLine("❌ Error creating package: " + pack.ErrorMessage);
        return;
    }
    Console.WriteLine("✅ Package has been created:");
    ColorConsole.WriteLine(OutputPath, ConsoleColor.DarkYellow);
    return;
}

If you use the command like with the package command and the --zipfolder parameter, the given folder is directly written into a Zip file using the ZipFile class. Remember this is a .NET Framework executable so we have to stick to the older more limited implementation that doesn't have a lot of options, so I grab all files first, then add some additional files.

The actual packaging is also straight forward:

public bool PackageFile(string packageFilename, string exeFilename, string dataFilename)
{  
	...
	
    if (File.Exists(packageFilename))           
        File.Delete(packageFilename);

    using (var outFs = new FileStream(packageFilename, FileMode.Create, FileAccess.Write))
    {
        using (var fs = new FileStream(exeFilename, FileMode.Open, FileAccess.Read, FileShare.Read))
        {
            fs.CopyTo(outFs);
            outFs.Flush();
            outFs.Write(SeparatorBytes, 0, SeparatorBytes.Length);
        };
        using (var fs = new FileStream(dataFilename, FileMode.Open, FileAccess.Read, FileShare.Read))
        {
            fs.CopyTo(outFs);
        }
    }
 
    // optionally sign the new exe
    if (!string.IsNullOrEmpty(App.CommandLine.SignCommand))
    {
        var cmd = App.CommandLine.SignCommand.Replace("%1", "\"" + packageFilename + "\"");
        try
        {
            ExecuteCommandLine(cmd, Path.GetDirectoryName(packageFilename), useShellExecute: false);
        }
        catch {}
    }
    return true;
}

The code creates a new binary file stream and then simple writes first the original Exe, then the marker string as bytes, and finally the zip file.

If you have a certificate the --signcommand allows invoking of a .cmd script (I use a .cmd script that calls a Powershell script because invoking pwsh via string parameter arg values is insane!). Signing will help at least to some extent with SmartScreen.

The packager code is contained in a self-contained FilePackager class that is easily re-usable in your own applications for similar tasking.

Unpackaging the Packaged Exe into Exe and Zipfile

Once the Exe has been created can then be unpackaged either by a packaged Exe 'running itself' and launching the Viewer, or explicitly unpacking the Exe into its components using the CLI:

.\WebPackageViewer unpackage `
      --package .\WebViewer-Packaged.exe 
      --output .\DocMonsterDocs

This creates the folder containing the entire Zip file of Html files unzipped along with the unpackaged WebViewPackager.exe file that you can run out of that folder to run the Web site.

Note: If the folder already exists, the unpackaging fails to avoid overwriting or wiping out data accidentally. If you need to replace existing content, delete the target folder first.

Creating a Single Exe and 'Packaging' a Native Dependency

The WebPackageViewer.exe is compiled down into a single file exe. But the actual application does have a few dependencies, so the actual build output looks like this:

Figure 8 - Build Output from WebView Packager - more than a single file.

In order to package up the file into a single EXE a few things need to happen.

Run an IL Merge tool to combined the external assemblies
Package up CoreWebView2.dll as a Resource to manually extract at runtime

.NET has support for creating a single executable from many package using a tool called ILMerge. Unfortunately that particular tool doesn't work with WPF applications due to the way it packages resources. However, there's a replacement for ILMerge called ILRepack that is updated to support a number of situations like WPF that ILMerge can't handle.

Using ILRepack, I take the built assembly output and package it down to a single Exe with this Powershell script:

# uses IlRepack (dotnet tool)
Set-Location "$PSScriptRoot" 
$release = "$PSScriptRoot\..\WebPackageViewer\bin\Release\net472\win-x64"
Write-Host $release
remove-item $release\*.pdb

$windir = $env:windir
$platform = "v4,$windir\Microsoft.NET\Framework64\v4.0.30319"

$version = [System.Diagnostics.FileVersionInfo]::GetVersionInfo("$release\WebPackageViewer.exe").FileVersion
$version = $version.Trim()
$originalVersion = $version
"Initial Version: " + $version

# Remove last two .0 version tuples if it's 0
if($version.EndsWith(".0.0")) {
    $version = $version.SubString(0,$version.Length - 4);
}
else {
    if($version.EndsWith(".0")) {    
        $version = $version.SubString(0,$version.Length - 2);
    }
}
"Truncated Version: " + $version

# dotnet tool install --global dotnet-ilrepack
# Merge Dlls into single EXE - missing WebView2Loader.dll - has to be manually copied
$ilRepackArgs = @(
    '/target:winexe'
    "/targetplatform:$platform"
    "/ver:$originalVersion"
    '/lib:.'
    '/lib:C:\Windows\Microsoft.NET\Framework64\v4.0.30319'
    '/lib:C:\Windows\Microsoft.NET\Framework64\v4.0.30319\WPF'
    '/out:..\WebPackageViewer.exe'
    "$release\WebPackageViewer.exe"
    "$release\Microsoft.Web.WebView2.Core.dll"
    "$release\Microsoft.Web.WebView2.Wpf.dll"
)

Write-Host "------------- IL Repack Arguments -------------"
Write-Host ($ilRepackArgs -join ' ')
Write-Host "-----------------------------------------------"

& ilrepack @ilRepackArgs

remove-item ../WebPackageViewer.exe.config

# copy unsigned copy
copy ../WebPackageViewer.exe ../WebPackageViewer-Unsigned.exe
copy ../WebPackageViewer.exe "\projects\DocumentationMonster\DocumentationMonster\BinSupport\WebPackageViewer.exe"

# sign with my signing script
& ".\signfile.ps1" -file "..\WebPackageViewer.exe"

exit 0

This creates both a signed and unsigned version of the packager. The signed version can be used to run packager as Web Site viewer by dropping it into a Web site folder, or running with the folder as a parameter.

# If in the Web site directory (or from Explorer in dir)
.\WebPackageViewer 

# with folder
.\WebPackageViewer "c:\Web Sites\markdownmonster.west-wind.com\docs"

ILRepack solves the issue of packaging the .NET assemblies. If you look back at Figure 8 you'll see the runtimes folder which contains native dependencies for CoreWebView2Loader.dll.

ILRepack cannot package any native dependencies so it's not included in the list of dependencies on the ILRepack arguments list.

Instead, the WebSitePackager project, embeds CoreWebView2Loader.dll as a project resource:

which - in a WPF project - gets embedded into a special resource:

Figure 9 - The native CoreWebView2Loader.dll is embedded as a .NET resource into the built exe so we can extract it at runtime.

WPF resources are not quite like normal .NET resources and you can't simply retrieve resources by accessing the ResourceStream and querying for a value by name. Instead WPF stores all resources in a single resource dictionary that you have to iterate over.

Here's what that looks like:

public static class ResourceHelper
{
    /// 
    /// Retrieve WebView2Loader.dll which we can't embed into the exe
    /// directly with ILMerge.
    /// 
    /// 
    /// 
    public static byte[] LoadWebView2LoaderBytes()
    {
        var asm = typeof(ResourceHelper).Assembly;

        using var resStream =
            asm.GetManifestResourceStream("WebPackageViewer.g.resources");

        if (resStream == null)
            throw new FileNotFoundException("WebPackageViewer.g.resources not found.");

        using var reader = new ResourceReader(resStream);

        foreach (DictionaryEntry entry in reader)
        {
            if ((string)entry.Key == "webview2loader.dll")
            {
                using var stream = (Stream)entry.Value;
                using var ms = new MemoryStream();
                stream.CopyTo(ms);
                return ms.ToArray();
            }
        }

        throw new FileNotFoundException("WebPackageViewer.g.resources not found.");
    }
}

So then when the app is running in Viewer mode, we extract the file and dump it out to disk in the same folder as the Exe.

if (!File.Exists("WebView2Loader.dll"))
{
    // If the loader is not present, we may be running from a single file bundle and need to unpack first
    try
    {
        var loaderBytes = ResourceHelper.LoadWebView2LoaderBytes();
        File.WriteAllBytes("WebView2Loader.dll", loaderBytes);
    }
    catch
    {
        MessageBox.Show(
            """
            An error occurred unpacking the WebView2Loader.dll resource.

            Make sure the application is not running from a read-only location and that you have permissions to write to the current directory.

            Alternately manually copy `WebView2Loader.dll` from the same folder as the WebPackageViewer.exe to the current directory and restart the application.`
            """,
            "Web Viewer Error", MessageBoxButton.OK, MessageBoxImage.Exclamation);
        Environment.Exit(1);
    }
}

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

Runtime CoreWebView2Loader.dll Copy

Doing this type of load and copy operation at runtime requires file write permissions in the same folder you're running WebPackageViewer.exe or the generated Packaged Exe file out of. If you don't have permissions the app will fail.

Copying a DLL to disk at runtime is also something that Anti-Virus tends to frown upon, but because CoreWebView2Loader.dll is a well-known Dll I have not actually seen this causing problems. Hyper-sensitive 3rd party AV may think differently though than my base Defender setup. Worst case scenario you can do this once running as Administrator - once the DLL exists it's not copied again.

User Interface Creation

The user interface of the WebPackageViewer is very simple - it's a form with a WebView on it basically. Initially the form was a basic WPF form with literally nothing else on it.

But if you look closely at the image in Figure 2 again you'll notice that the window is not actually a standard WPF window, but rather a dark mode Fluent UI type of window.

I was unaware that WPF actually has some built in support for creating self-drawn windows using System.Windows.Shell integration.

With the help of CoPilot I managed to make the window theme aware supporting both light and dark mode frames. However, getting that all to work - even with CoPilot on some of the higher end models - took a lot of back and forth. Once you take over the Window rendering yourself a lot of functionality has to be reimplemented. You can see the end result in MainWindow.xaml on GitHub. Normally I would use a framework library like MahApps or ControlzEx but that would have added yet another set of dependencies resulting in a larger base Exe yet, so this tedious Window implementation was worth the extra effort.

Console and WPF UI from a single Exe

The app supports two modes:

CLI Mode for packaging and manual unpacking
WPF UI Mode for viewing the Help File

Windows doesn't have direct support for 'mixed mode' executables - they are either marked as Command line or Windows UI applications. In order to make the UI bit work the application is compiled as a Windows UI application.

However, you can still provide output to the Console but it requires some extra work, and the result is typically not very clean due to the way that the UI application handles termination and wait states.

A desktop application can attach to a Console if the application is launched from a Console command line using AllocConsole() and FreeConsole() PInvoke calls:

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

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

You can then attach to the 'default' console if one is available when the app starts and free the console when it's done.

protected override void OnStartup(StartupEventArgs e)
{
    
    bool attached  = AttachConsole(-1);

	// Processes command line operations
	// which all output to CLI
    CommandLine.Parse();

    if (!CommandLine.Unhandled)
    {
        if (attached)
            FreeConsole();
            
        // If Command Line is handled, exit the application
        Environment.Exit(0);
    }

    // unhandled: unpackage Web site for Viewer mode
    var pack = new FilePackager();
    var exeFile = Assembly.GetExecutingAssembly().Location;
    
    if (pack.FindMarkerOffset(exeFile, pack.SeparatorBytes) > 0)
    {
        var outputPath = Path.Combine(Path.GetTempPath(), "dm_" + StringUtils.GenerateUniqueId(8));                
        TempUnpackDirectory = outputPath;
        
        if (!pack.UnpackageFile(exeFile, outputPath, true))
        {
            if (!attached)
            {
                MessageBox.Show("An error occurred unpacking the viewer app and Web site.\n" +
                                pack.ErrorMessage, "Web Viewer Error", MessageBoxButton.OK,
                    MessageBoxImage.Exclamation);
            }
            else
                Console.WriteLine("\n❌ Error:\n" + pack.ErrorMessage);

            Environment.Exit(1);
        }
        Environment.CurrentDirectory = outputPath;

        var exe = Path.Combine(outputPath, "WebPackageViewer.exe");
        var p = Process.Start(new ProcessStartInfo() { FileName = exe, WorkingDirectory = outputPath });

        Console.Write("\n✅ Launching Web Viewer...");

        if (attached)
            FreeConsole();

        Environment.Exit(0);
    }

    InitialStartDirectory = AppContext.BaseDirectory.TrimEnd('/');
    InitialUserStartedDirectory = Environment.CurrentDirectory;

    // Read configuration from Json and override with explicit values passed
    var config = WebViewerConfiguration.Read();
        
    if (attached)
        FreeConsole();
        
    MainWindow mainWindow = new MainWindow(config);
    mainWindow.Show();
    
   ...

The code attaches the console and if started from the Powershell or Command the AttachConsole(-1) call returns true. At that point Console.Write() now outputs to the existing console window instance.

Then when done FreeConsole() has to be called to release the Console and return control back to the console instance.

While this works, the Console behavior can be a bit quirky:

Figure 9 - Console output in a UI compiled application can be a little awkward.

Not really sure what causes this behavior of prompts popping up in the middle of output and on occasion the final operation 'hanging' without a prompt as if you were call ReadKey(). Often also the terminal completes not at the last prompt but the one above it.

I'm not sure what causes this but it seems its a timeout of some sort - new prompts appear when operations take a bit of time like the packager on a large project for example.

It's not pretty, but for the most part it works and displays what you need to know. More often than not a cls is required to clean up the Console after the operation has completed. It's not ideal, but still worth having compared to having to build a separate UI form to display the same information.

I ended up implementing a fix for this by creating the application as a Console app and manually launching the WPF application. This allows Console access normally - including from the WPF interface. I'll have another post about that in the next days.

Woof: Simple but not Simple

At the end of the day I got what I was looking for packaging Web Content into a single executable as well as - as a side effect - getting a simple small executable that lets me also run static sites locally simply by dropping an exe into the folder.

While there are other more sophisticated tools to run Web sites locally - like my own LiveReloadServer - having a small and truly offline viewer is still something that quite a few people are asking for in documentation solutions. I guess some people are still dreaming of the old days of Help and CHM files. 😄

Interestingly enough I started the original planning for this with CoPilot and the original Ask and Plan Mode interactions actually convinced me to even bother with this edge case tool, because it seemed pretty straight forward. But, as is usually the case, the initial AI implementation underwent nearly a complete re-write to work properly to fix the remain 20% that were missing or simply didn't work quite right.

This seems to echo my experience with AI - I have never had LLMs deliver something that is ready to put into production. It's awesome at building a skeleton and base functionality, but I always end up spending much more time cleaning up and fixing the edge cases that aren't obvious. This isn't a criticism BTW - it feels more like working with somebody interactively through the problem rather than letting them solve the problem entirely which is not a bad thing at all. This was certainly not one-shotting, and not even a half and half collaboration, but more like a hit or miss consultation 😄

Creation of this tooling isn't rocket science obviously, but the road to creating something like this is paved with lots of paper cuts resulting in eating up a lot more time than planned!

As I mentioned - this tool serves an edge case that is highly useful to me for several use cases, but I think there are lots of parts to this implementation that can be applied to other scenarios. EXE packaging, ILMerging, Resource hosting of executable code offer some interesting possibilities for shipping self-contained code. Some of you may find value in this.

Resources

this post was created and published with the Markdown Monster Editor

Lost ASP.NET Identity Cookies on IIS Application Pool Restarts

(Rick Strahl) — Sun, 31 May 2026 08:49:58 GMT

If you find that your ASP.NET authentication cookies expire every time your IIS application pool restarts or recycles, the culprit is likely the DataProtection API not finding the previously stored keys. This post describes one gotcha I ran into with the default storage location on IIS in the user profile due to a default Application Pool setting.

Running ASP.NET Core Applications as a Subfolder Application

(Rick Strahl) — Tue, 26 May 2026 14:16:20 GMT

While ASP.NET Core applications typically run from the root folder, some scenarios—such as hosting multiple blogs under a single domain—require running from a subfolder. This post explains how to configure ASP.NET Core with app.UsePathBase() for proper routing and ~/ path resolution, along with the IIS setup required for a dedicated Application Pool using "No Managed Code." It also covers key migration tips, including bulk updates for root-relative links and JavaScript adjustments to keep client-side functionality working in a subfolder environment.

Getting the Client IP Address in ASP.NET Core

(Rick Strahl) — Wed, 13 May 2026 10:35:26 GMT

When I need to pick up the client IP Address in ASP.NET Core I always forget where to find the connection information and/or forget about picking proxy forwarding instead of the actual IP address. To make things easy and reusable, here's a small HttpRequest extension method.

Putting the Westwind.Scripting C# Templating Library to work, Part 2

(Rick Strahl) — Thu, 23 Apr 2026 16:04:43 GMT

In part 2 of this post series I look at some of the issues you may have to deal with when using the Westwind.Scripting library as an offline document or Web site creation engine. While running simple templates is easy enough, when generating static output for Web site publishing or local preview requires some special considerations.

Revisiting C# Scripting with the Westwind.Scripting Templating Library, Part 1

(Rick Strahl) — Wed, 01 Apr 2026 10:35:37 GMT

The `Westwind.Scripting` library provides runtime C# code compilation and execution as well as a C# based Script Template engine using Handlebars style syntax with pure C# code. In this post I discuss use cases for script templating and some examples of how I use in real-world applications, followed by a discussion of the engine's features and the new Layout, Section and Partials feature that was added recently.

Using .NET Native AOT to build Windows WinAPI Dlls

(Rick Strahl) — Sat, 21 Mar 2026 11:47:13 GMT

Did you know that you can use .NET AOT compilation to create native Windows DLLs to potentially replace traditional C/C++ compiled DLLs? It's now possible to build completely native DLLs that can be called from external applications and legacy applications in particular using .NET AOT compilation. In this post I show how this works and discuss the hits and misses of this tech.

Azure Trusted Signing Revisited with Dotnet Sign

(Rick Strahl) — Mon, 02 Mar 2026 10:10:23 GMT

In this follow-up post to my previous guide on Azure Trusted Signing, I explore how the new `dotnet sign` tool significantly simplifies the code signing process compared to the traditional `SignTool` workflow. The post identifies `dotnet sign` using `artifact-signing` as a faster, more efficient alternative.

Rick Strahl's Web Log

Getting Inherited Controller Routes to work in ASP.NET Core

Controller Inheritance?

Controllers vs. Minimal APIs

My Use Case and how I ended up here

Controller Attribute Routes and Inheritance

The Problem: Route Duplication

Controller Inheritance... It's complicated

Preserving Base Class Routes

Abstract Classes are Easiest

Creating an IActionDescriptorProvider Route Interceptor

LLM Heaven and Hell?

Summary

Resources

Creating Dual Use Windows GUI and Console Applications

CLI Interfaces

GUI Application with CLI Interface Option

Can you live with it?

Hackery!

Is Console Interface Important?

When to use this

Console Application that hosts a GUI Interface

What's the Downside of a Console GUI Application?

When to use this

Separate CLI Application

Avoiding Ambiguities

How does this work?

CLI Projects can have small Footprint

When to use

Summary

Creating a Packaged Windows Single File Web Site Viewer Executable

WebPackageViewer

How does the Web Packaging work?

The Fly in the Oinment: Windows SmartScreen

Local Installs are Fine

Exe Packaging in .NET

CLI Mode

Implementation in .NET

How it works

.NET Framework Executable

Exe File Packaging

Build First using package Command

Launching the Packaged Exe triggers unpacking

The Exe is Re-Launched in the Web Folder

WebView uses Manual Handling for Https Urls

File Packaging and Unpackaging

Creating the Exe and Zip Package

Unpackaging the Packaged Exe into Exe and Zipfile

Creating a Single Exe and 'Packaging' a Native Dependency

Runtime CoreWebView2Loader.dll Copy

User Interface Creation

Console and WPF UI from a single Exe

Woof: Simple but not Simple

Resources

Lost ASP.NET Identity Cookies on IIS Application Pool Restarts

Running ASP.NET Core Applications as a Subfolder Application

Getting the Client IP Address in ASP.NET Core

Putting the Westwind.Scripting C# Templating Library to work, Part 2

Revisiting C# Scripting with the Westwind.Scripting Templating Library, Part 1

Using .NET Native AOT to build Windows WinAPI Dlls

Azure Trusted Signing Revisited with Dotnet Sign

Build First using `package` Command