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)

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:

Figu re 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 lots of command line options that allow you to customize

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.

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.

The WebView doesn't use a Web Server, but rather uses a form of virtual file mapping to execute requests locally.

The WebView 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. running out /docs/ instead of root /). The WebView virtual hosting feature has no support for auto-routing to a sub-folder Url and so the file translation in a virtual folder doesn't work right.

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.

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.

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:

<ItemGroup>
	<Resource Include="WebPackageViewer.ico" />
	<Resource Include="webview2loader.dll" />
</ItemGroup>

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
{
    /// <summary>
    /// Retrieve WebView2Loader.dll which we can't embed into the exe
    /// directly with ILMerge.
    /// </summary>
    /// <returns></returns>
    /// <exception cref="FileNotFoundException"></exception>
    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 most Fluent type of window.

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

<shell:WindowChrome.WindowChrome>
    <shell:WindowChrome
        UseAeroCaptionButtons="False"
        CaptionHeight="32"
        ResizeBorderThickness="4"
        GlassFrameThickness="0"
        CornerRadius="12"/>
</shell:WindowChrome.WindowChrome>

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.

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

• WebPackageViewer on GitHub
• SmartScreen: Windows Protected your PC: Dealing with Windows SmartScreen on Installation

this post was created and published with the Markdown Monster Editor

Last week I finally updated my blog and moved it to .NET 10 from the ancient WebForms based engine I built 20 years ago. The app is deployed onto a Windows server running IIS and I ran into a snag related to cookie authentication in ASP.NET.

The problem showed up in my Admin panel login where the login would persist across browser sessions, but would not persist across IIS or ASP.NET application restarts. In other words, I could sign in and the cookie worked fine for the current session and even in subsequent sessions after shutting down and restarting the browser, but it would eventually fail after an application update, or the nightly scheduled IIS recycle ignoring the full cookie persistence expiration.

Encryption Keys

The app uses Cookie Authentication for the administration backend using a custom identity implementation on top of the base ASP.NET Identity APIs. The base Identity implementation in ASP.NET handles the cookie creation and management using internal logistics to encrypt and decrypt the cookie data, which serves both to hide the data as well as ensuring the content is not tempered with.

In the scenario I mention above the problem is that Cookies are re-generating when the machine application or the Application Pool is restarting (which on IIS usually coincides). For the TLDR; crowd the short version is that the Encryption Keys for the application weren't persisting across Application Pool restarts.

But before I get into the why of that lets look at how the ASP.NET Cookie encryption works by default on Windows and IIS and locally in your development environment.

Cookie Authentication 101 in ASP.NET Core

Here's a quick review of explicit (non-Identity-Provider) Cookie Authentication in ASP.NET Core, which thankfully has gotten a lot simpler over the many convulsions that were plaguing early Authentication schemes in ASP.Core. These days doing your own Cookie implementation on top of the Identity base layer is pretty easy.

It's a two step process:

• Configure the Cookie/Identity middleware in the Startup
• Sign in and Sign out in your endpoints with a single method call

In your app startup set up the auth middleware:

services
    .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(o =>
    {
        o.LoginPath = "/account/login";
        o.LogoutPath = "/account/logout";
        o.SlidingExpiration = true;
        o.ExpireTimeSpan = new TimeSpan(7, 0, 0, 0); // overridden by login 
        o.Cookie.Name = "ww_wl";
    });

and to enable the middleware:

// in this order!
app.UseRouting();

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

Then in your authentication endpoint logic - a controller or minimal api endpoint or Page logic - you can sign in a user after you've validated their credentials (in my case not using the Identity provider) by adding the auth cookie:

// `user` comes from Db
var identity = new ClaimsIdentity(CookieAuthenticationDefaults.AuthenticationScheme);
identity.AddClaim(new Claim("Fullname", user.Fullname));
identity.AddClaim(new Claim("Username", user.Username));
identity.AddClaim(new Claim("UserId", user.Id.ToString()));

if (user.IsAdmin)                
    identity.AddClaim(new Claim(ClaimTypes.Role,"Admin"));

// Set cookie and attach claims
await HttpContext.SignInAsync(
    CookieAuthenticationDefaults.AuthenticationScheme,
    new ClaimsPrincipal(identity), 
    new AuthenticationProperties
    {
        IsPersistent = true,
        ExpiresUtc = DateTimeOffset.UtcNow.AddDays(7),
        AllowRefresh = true
    });

To sign out is also a one-liner:

await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

With the sign in set you can now get a Context.User.Identity object when a cookie has been set, and you can examine Identity.IsAuthenticated and the individual Claims you added.

Here's the part that's relevant to this post and the lost cookies:

ASP.NET encodes all that information into an Identity cookie and encrypts that whole internally stored package with using a known encryption key when it it is created, and then uses that same key to decrypt the cookie value to restore the Identity associated data. More on this in a second as this is part of the problem I ran into...

Once signed in in my app, once the cookie is set, I can now access the admin panel. The cookie persists and should persist across browser sessions and - in theory - across application shutdowns.

When I ran this on my local development setup with Kestrel and a regular logged in user everything is hunky dory. It works for all scenarios - including application restarts.

On Server on IIS: Not so much

I then deployed the app to the server running IIS, and now the browser persistence was working fine even with browser restarts, but an application restart now forced a new login every time. Annoying!

So what gives?

It's not me - it's You! (IIS you old bastard!)

Turns out I was looking in all the wrong places for the problem. I was looking at the ASP.NET Cookie configuration, which as a I showed above is pretty straight forward - not to many thing you can screw up there. I have several applications that use the exact same cookie auth set up, and they work just fine with cookies persisting across restarts. 🤔

After checking and checking and re-checking everything, and even pointing CoPilot at two projects and it confirmed that it couldn't spot a difference that would account for the different behavior either.

CoPilot turned out to be helpful after all, because in a small reasoning side note it mentioned the DataProtection API and key storage location. Although it didn't point at the exact cause - it made me review how encryption keys are generated and used and sure enough that's where the problem turned out to be!

DataProtection APIs for Cookie Encryption

The cookies that ASP.NET writes are two-way encrypted and so the keys to read and write have to be available when the cookie is created and then also when it is read.

More simply put: The underlying key can't change or be 'renewed' in any way between encryption and decryption.

It turns out that the location where keys are stored is crucial. The location is configurable, but by default this location is stored in the active user's Windows User Profile. Aha! 💡

Turns out when you create a new Application Pool in IIS, the User Profile activation is turned off by default!.

Oddly the default of False shows as a non-default value (ie. it's bolded) in the Application Pool Admin panel.

What does Load User Profile do?

Load User Profile effectively causes the Application Pool to map environment variables like USERPROFILE and registry keys like HKEY_CURRENT_USER, so that they work as expected against the specific Identity User Profile. For 'dynamic' accounts like ApplicationPoolIdentity a Profile folder is created the first time the AppDomain starts and that profile is persisted after that and behaves the same as a standard user account.

Here's why this matters: By default, ASP.NET stores the DataProtection API encryption keys used for Cookie Encryption in the active User Profile. No user profile, no persistent encryption key storage.

Instead when no User Profile is mapped, a temporary, non-persistent user profile is created when the Application Pool instance is created (so that profile update operations can work without blowing up) which results in new encryption keys getting generated every time the Application Pool starts.

Now, when a previously created cookie comes in it and tries to validate against the new cookie encryption keys, the keys no longer match and the integrity check against the cookie fails, and a new sign in is required. And that's precisely what I saw happening in my Admin Panel access.

There are couple of ways to fix this:

• Re-enable the User Profile Mapping so your get a persistent User Profile
• Explicitly store the encryption keys in a known location

Enable the Load User Profile

The simplest fix then is to set the Load User Profile setting in the Application Pool to True to force using a persistent user profile for the Application Pool Identity account. This works both with existing User and System accounts as well as with dynamic accounts like ApplicationPoolIdentity.

And voila - keys now work across application and IIS restarts.

When you enable the user profile and don't set an explicit DataProtection API location, keys are stored in:

%LOCALAPPDATA%\ASP.NET\DataProtection-Keys

On non-Windows platforms this works in a similar fashion and are stored under: ~/.aspnet/DataProtection-Keys/key-*.xml

For Windows 'Service' accounts like Network Service this ends up being in a special location that is not in c:\Users as you might expect but in c:\windows\ServiceProfiles\:

For each account, each application gets its own set of keys based on some generated application id. You can see above several different applications that are all running under Network Service with their own dedicated encryption keys.

The Windows key files look like this in case you're interested:

<?xml version="1.0" encoding="utf-8"?>
<key id="65d6b51f-5282-4065-a0e4-1681d6fc0096" version="1">
  <creationDate>2024-03-08T00:52:28.2113827Z</creationDate>
  <activationDate>2024-03-08T00:52:28.2059047Z</activationDate>
  <expirationDate>2024-06-06T00:52:28.2059047Z</expirationDate>
  <descriptor deserializerType="Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel.AuthenticatedEncryptorDescriptorDeserializer, Microsoft.AspNetCore.DataProtection, Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60">
    <descriptor>
      <encryption algorithm="AES_256_CBC" />
      <validation algorithm="HMACSHA256" />
      <encryptedSecret decryptorType="Microsoft.AspNetCore.DataProtection.XmlEncryption.DpapiXmlDecryptor, Microsoft.AspNetCore.DataProtection, Version=8.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60" xmlns="http://schemas.asp.net/2015/03/dataProtection">
        <encryptedKey xmlns="">
          <!-- This key is encrypted with Windows DPAPI. -->
          <value>AQBAANCMnd8BFdERjHoAwE/Cl+sBAAAA/13cneK0bkmbEII3g6oEDgAAAAACAAAAAAAQZgAAAAEAACAAAADxJcn0BIJYkGlTN...==</value>
        </encryptedKey>
      </encryptedSecret>
    </descriptor>
  </descriptor>
</key>

Using the profile option is easiest because it's automatic, but if you need to share keys between multiple machines or multiple applications, you need to use another approach using one of the other supported key storage mechanisms.

And remember that if you turn Load User Profile to False you don't get a peristant profile and keys won't survive an Application Pool shutdown.

Explicitly provide DataProtection Folder Location

If you don't want to be tied to a Windows User Profile there's a more deterministic approach in ASP.NET that lets you specify where the DataProtection keys are stored explicitly in an explicitly specified known location or another storage API solution.

This is configured through ASP.NET's configuration and there's a middleware service that you can register for this via services.AddDataProtection():

// Key storage for cookies - so cookies can persist
if (env.IsProduction())
{
    services.AddDataProtection()
        .PersistKeysToFileSystem(new DirectoryInfo(Path.Combine(env.ContentRootPath, "DataProtectionKeys")))
        .SetApplicationName("Weblog");
}

This example uses the File System provider to store the keys to a specified folder on disk, that contains the required key chain used for encryption using the DataProtection APIs. The layout for this folder is the same as shown in the Profile location, with the difference that you get to chose the location explicitly. Note that your Application Pool Identity account has to have read and write access in this location in order to create the keys written there.

You can store key - as I do here - in a folder below the app's content root (which is not Web accessible), or if you're overly paranoid, stuff it into a known, completely away-from-the-app location.

There are additional providers including persistence to the registry, AzureBlobStorage and you can also implement your own provider to store the key files.

Summary

In the end for my application, I opted for the simplest solution of just enabling the user profile to automatically let it do its thing to store the keys. When running on Windows I tend to have the User Profile enabled even though I don't explicitly access it, because there always can be odd APIs that require a profile user that you might not expect anyway - this has bitten me more than once so I tend to enable it on all app pools. There's no real overhead here as all that really does is map environment variables to point at file and registry keys that already exist. I've had apps break in the past with off the wall failures because profile access was not available. There's no real downside to leaving it on especially with an otherwise non-interactive account.

The alternative of using an explicit store makes sense if you need to share keys between multiple machines in a load balancing or other multi-server environment, or if you simply want more control over where the keys go. Just make sure your app can actually write out the new keys in the location you choose.

Writing this down mainly to remind myself in the future, because due to the default setting in the Application Pool to not load a User Profile I've run into this more than once. Hopefully spending a little time writing it down will have jogged my memory enough not to repeat that mistake in the future... 😀

this post created and published with the Markdown Monster Editor

ASP.NET Core applications by default want to run in a root folder - and to be fair that's the 99% use case. But there are those occasional situations where you want to run a Web site in a sub folder rather than on the root of the Web site.

In this post I review what's required to run ASP.NET with a PathBase - which works with any Web server - and then specifically discuss how to set this up on IIS, which is a little more complicated than it should be.

Although I discuss IIS specifically here for the physical deployment part since that's what I'm running on, the majority of this this content concerning the ASP.NET set up and modifications, applies to any Web server hosting when using sub folder mapping.

Why would I need to run out of a SubFolder?

The specific scenario that I ran into was that recently I updated my old custom Blog engine, and decided to pull all my secondary blogs onto my own server from various blog publishing sites. I've always run my blog on my own hosted server and the main blog runs of its own sub-domain. But the other two blogs are small barely used product related blogs that ran on different hosting sites which I never used because they were terrible and it would be a better fit to just run them off the same site in /blog/ folder.

With my recent site blog update - I finally moved the old WebForms app to .NET Core - and the much simplified deployment set up that comes with it, I decided to just run everything in house for these relatively low volume sites and get better, more consistent theming and a much easier publishing pipeline using Markdown Monster (using a new custom protocol - more on that in another post).

In any case the scenario here is that I have a root product site:

• https://markdownmonster.west-wind.com

and I now want to run the blog site out of a /blog/ sub-folder, rather than as a root site. So:

• https://markdownmonster.west-wind.com/blog

rather than a separate new root Web site like:

• https://markdownmonsterblog.west-wind.com

(which is what I started with then aborted)

For SEO it's often beneficial to run everything on the same site which matters more for the low volume sites, but it's also cleaner and more consistent with other sub folders like /docs and /support. Running a sub folder site also requires less setup - you don't need yet another certificate and custom bindings to manage and so on. So using a subfolder is effectively more lightweight from a config perspective. On the other hand, using a subfolder site requires that more care is given how urls are created in the application as we'll see in a minute.

Creating an Application in a Subfolder

There are three parts to the process of running an application in a subfolder:

• Configuring ASP.NET for running from a subfolder
• Fixing up links so no hardcoded / references are used
• Configuring the Web Server for a subfolder application

Setting up ASP.NET For running with a Subfolder

Turns out setting up ASP.NET to run from a subfolder is pretty easy to do as there's a dedicated middleware to set up a custom PathBase as ASP.NET likes to call it.

In program.cs add this:

var app = builder.build();
...
app.UsePathBase("/blog/");

This code goes into program.cs after the builder has created an app instance using the provided services. You'll want to do this near the top of the app middleware declarations to ensure the folder is respected all the way through the middleware pipeline - you'll want this before authentication, static files and certainly before any routing middleware. I have it at the very top of the pipeline immediately after the builder has created the app instance.

I tend to parameterize the PathBase parameter with a configuration value, because I'm duplicating the same application in multiple folders. So, in my Weblog application it looks like this:

// config from DI initialization or wlApp.Configuration static
if (!string.IsNullOrEmpty(config.VirtualPath) && config.VirtualPath != "/")
{
	app.UsePathBase($"/{config.VirtualPath}/");
}

I have 3 blog sites - one of which runs as root and two of which run in /blog/ subfolders. By parameterizing I can customize whether they run out of a subfolder or not without recompilation.

So what does .AddPathBase() actually do?

It's used to resolve Urls internally, using the path specified in AddPathBase(). Anytime ASP.NET creates a path dynamically for routes, uses ~/ in Views or Pages, or via Url.Content() or other IUrlHelper the path is automatically fixed up with the provided path base.

So instead of returning /images/someimage.png which you'd get for a root site, you get /blog/images/someimage.png for example.

If you use implicit routing, Url helper methods, or you stick to using ~/ paths in your Views/Pages, ASP.NET does most of the heavy lifting for you, without having to do anything else.

Fixing up Root Paths with ~/ and an ApplicationBasePath

All this means is that you need to be more vigilant about how you root any explicitly referenced Urls both in View markup and in your application code. Code fixups should be minimized as much as possible.

For Views: Rather than using <img src="/images/someimage.png" /> you should use <img src="~/images/someimage.png" /> to ensure the appropriate path is used.

If you didn't do this - and let's be honest most of us don't - you can quickly find and replace all instances of hard coded root paths by doing a Find in Files Search (Ctrl-Shift-F) in your IDE and doing a search and replace for ="/ and replacing with ="~/ in all your View files. This should capture most scenarios in any physical files.

In code you can access the IUrlHelper interface in Razor views or injected into controllers or methods.

In a Razor Page or View

var rootPath = Url.Content("~/images/someimage.png");

In Application Code (.cs files)

You can also inject IUrlHelperFactory (WTF Microsoft?) and then retrieve the IUrlHelper in a somewhat convoluted way that only an ivory tower architect could love:

public class MyService
{
    private readonly IUrlHelper _url;

	public MyService(
    			IUrlHelperFactory factory,
    			IActionContextAccessor actionContextAccessor)
	{
	    _url = factory.GetUrlHelper(
	        actionContextAccessor.ActionContext);
	}
	
	public string Resolve()
	{
	    return _url.Content("~/images/logo.png");
	}

}

If you don't want to deal with this and just have a couple of generic methods that work anywhere, the Westwind.AspNetCore package has a couple of generic helpers:

• HttpContext.ResolveUrl() extension method
• WebUtils.ResolveUrl() - you provide a base path as a string and it resolves with that (works without any Context)

Running locally with a SubFolder

If you create your app this way, and fix up Urls you run it locally using the Kestrel Web server with dotnet run or from your IDE you will see the site come up in a subfolder:

The url includes the /docs/ subfolder:

https://localhost:5001/docs/

If you stuck to using ~/ root paths everything is bound to just work the same as if you were running from the root folder.

Note that you should also change your dev launchSettings.json to reflect the new launchUrl that includes the subfolder:

"Westwind.Weblog.MarkdownMonster": {
  "commandName": "Project",
  "launchBrowser": true,
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  },
  "applicationUrl": "https://localhost:5001",
  
  // THIS!
  "launchUrl": "https://localhost:5001/blog/"
},

Configuring IIS for a Subfolder Application

While the UsePathBase() middleware handles the ASP.NET Core side seamlessly, IIS requires some extra work to create an Application under your root website.

IIS has Web Sites and Applications, which are very similar. Web Sites have extra configuration related to Host mappings and bindings, but otherwise Web Sites and Applications behave very similarly.

One ASP.NET Application per Application Pool

IIS requires that each ASP.NET application uses its own dedicated ASP.NET Application Pool. Only a single ASP.NET Application can run inside of any given Application Pool, so unlike classic .NET sites, you can't share a single application pool for multiple Core apps.

It's possible to mix an ASP.NET Core app with a classic ASP.NET app or a static app in the same Application Pool, but you cannot have two or more ASP.NET Core Applications in an Application Pool. If you do only the first starts - the second one fails with a startup error.

Here's what a folder based Application looks like in the IIS Manager:

Application vs. Virtual Folder

There are two options in IIS for a folder: Application or Virtual. In this post I'm only talking about Applications which are self contained apps that run in their own Application Pool.

You can also create a virtual which does not create or use a new Application Pool but simply provides a virtual folder mapping with the app running in the parents application scope. This might work in some scenarios where the parent site is not an ASP.NET Core app. A static site or an ASP.NET Classic site but I've not tried this out. What I describe here is the scenario of creating a new Application that is mapped to an Application Pool explicitly.

Note that the physical folder doesn't have to live in the matching parent site folder - it can point to any location on disk. However, in most cases I put the actual site content into the relative folder location in the parent Web site for consistency in finding it later 😄

For an Application you need to have a dedicated Application Pool for this application - or at least an AppPool that doesn't have another ASP.NET application in it. That AppPool should be configured for No Managed Code.

Make sure you use an identity (user) that matches the rights that you need for your application. My apps tend to have a few configuration related settings that get written out so I have to use an account that has some additional rights.

Once this is set up and you've published your app, IIS will handle the initial request routing and pass the correct path information to the ASP.NET Core module to give you the same behavior that you see on your local install.

Recommendations

If you're like me and you built this site with a Root Site in mind initially, doing this switch to running a sub-folder - I'd highly recommend you take a breather 😄 and spend a bit of time testing locally with the subfolder.

There are bound to be lots of little edge cases that are hard to test and easy to miss when doing smoke testing.

I initially built the site for my main Weblog which runs on root, never giving any thought for running out of a sub-folder. Then when I created the other two sites I initially set them both up as root sites before realizing that I'd rather run them in sub folders.

I went through the initial steps of making the site work with subfolders, and at first glance everything worked. However I ran into lots of little edge cases with a couple of oddball links that used different quotes around links, and any links in Javascript code (see below). I managed to find most issue before uploading the site to production, but over the next day a whole bunch error log reports came in from things I had missed - mostly links.

So take the time to test your functionality, if not automated then manually excercising all the nooks and crannies of your site.

Summary of Path Fixups

To summarize these are some of the things that you have to probably fix or at least check when going from Site to Folder based:

All .cshtml, .razor Pages

All view pages can automatically fix up pages that reference via "~/" paths. Maybe you were diligent and started doing this right way. I rarely ever do this right - I do some with ~/ and some not which is no better than not doing it all 😄.

Luckily fixing up View pages is pretty straight forward: You can do a simple search and replace:

• Select *.cshtml, *.razor etc.
• Search for ="/
• Replace with ="~/

Code Fix ups

You can do something similar for your .NET code, but you have to be a lot more selective and you can't do a search and replace.

• Select *.cs, *.cshtml (cshtml for code blocks that build Urls)
• Search for "/

You want to search code both in your CS files and any code snippets in your Views/Pages.

Hopefully there shouldn't be a lot of those in your code because generally hard coding Urls is a bad idea. Typically this only happens if Urls need to be built up based on a host of input parameters.

var redirectUrl = "/somedeeplink/in/the/site";

changed to:

var redirectUrl = wlApp.Configuration.ApplicationBasePath + "somedeeplink/in/the/site";

Again, this should be pretty rare but worth checking for. This search is likely to produce a lot of false positives that don't require any changes.

Javascript Code

Javascript code is little more tricky. If you have script code that's making server calls, you may have to fix up paths in your scripts. Scripts aren't executable code and the ASP.NET parser doesn't touch them as the files are served as static resources. It's also common that you provide Urls as strings.

It's a lesson I've learned a long time ago - almost every application that calls to the server requires a configurable value to for a base path to call the server. There are lots of ways to do this and in SPA applications I always have a config object to do this.

However, for traditional server based Web apps that have only a few isolated JavaScript callbacks to the server, there is no common entry point for scripts - they are just loaded randomly.

In this application I do this the brute force way by providing a base path in a global script variable that gets embedded into the _Layout.cshtml page. Since _Layout.cshtml touches every page this is as close as I get to a global client side entry point. You can also put this in a script file but you have to make sure it gets loaded early enough that all other scripts can see it.

The idea is that I create a global variable - or rather a global object with an embedded variable - that is accessible from any script. The script is defined at the top of the page in the header so it's visible to any code that follows.

I use another helper class from Westwind.AspNetCore helper for this:

@
{
	// at the top of _Layout.cshtml

	// creates an object with props for the value(s) below
	var scriptVars = new ScriptVariables("window.page");  
	scriptVars.Add("basePath", wlApp.Configuration.ApplicationBasePath);
}
<!DOCTYPE HTML>
<html>
<head runat="server">
    <title>@(ViewBag.Title ??  wlApp.Configuration.ApplicationName)</title>
    <script>
        // expands into an object with props
        @scriptVars.ToHtmlString();
    </script>

ScriptVariables is a helper class that makes it easy to create a Json safe object of values you want to embed into the page from your .NET code. You basically add variables which are then serialized - Javascript and Html safe into the document when you use @scriptVars.ToHtmlString().

In this case it produces an object with a single variable, but typically I end up with a handful of 'global' page level properties that need to be passed through:

window.page = {
	basePath: "https://markdownmonster.west-wind.com/blog/"
};

You can decide whether you want to use just /blog/ or the fully qualified path as I'm doing here.

I'm using:

scriptVars.Add("basePath", wlApp.Configuration.ApplicationBasePath);

which is configured value that I store in the app to have quick and easy access to the full site url. In the case of this _Layout.cshtml page you could also use:

scriptVars.Add("basePath", Url.Content("~/");

which produces the site relative /blog/ base path.

Now any scripts on the page - both in the page itself or in any script files can look at page.basePath and use that to fix up any Urls as necessary:

deletePost = ()=> {
	if (confirm('Are you sure you want to delete this post?')) {
		// THIS
		var url = page.basePath + "posts/@post.Id";
		
		ajaxJson(url, null,
			(res) => { 
			    // AND THIS
			    location.href = page.basePath + "posts";
			},
			(err) => {
			    alert("Error deleting post: " + err.responseText);
			},
			{ HttpVerb: "DELETE" });                                                    
	}
}

Summary

Conversions like this are always more time consuming than you think - getting to 80% is easy. And just as you're padding yourself on the shoulder for an easy job you find all the edge cases that you didn't test for.

The basics mentioned above should get you through most of the conversion pretty quickly. It takes a little bit of time to set up, and I always kick myself for not doing things like using ~/ paths and explicit base path fixups for any coded paths right from the start.

Running Web sites out of a virtual folder is not all that common, but for many low impact sites I'm actually finding myself using them more often than I would have thought. When you need to do it, it's good to know that it's possible and not as complicated as I thought it might be.

Now that I've gone through it I suspect I will be more diligent in the future with new and old sites to use proper pathing from the get go even when it seems overkill and you think you'd never run any other way than out of a root site... we shall see.

this post was created and published with the Markdown Monster Editor