Monday, August 4, 2025

Weird issues in WebView2 / WinUI3: using the ms-appx: scheme

 Update your WebView2 WinUI3 code to read ms-appx:/// URLS from your Assets folder

It was the simplest of APIs, it was the most irritating of APIs. The ms-appx:/// URL scheme is one of the unheralded awesome parts of the WinRT API set. With it, there's a simple and straightforward way for an app to combine a bunch of C# code and also some useful HTML code. I'm using it this month for my (upcoming) Simple GPS Explorer app so that I can display GPS traces on an OpenStreetMap map.

The ms-appx:/// URL scheme is also one of the irritations of moving from UWP apps over to WinUI3 and whatever they're calling the framework. That's because the PMs decided that a simple straightforward way to read local assets wasn't useful in programming.

This blog post shows how to use ms-appx:/// in WinUI3 and WebView2 in just a few steps. We're going to combine two different abilities:

1. We're going to replace the ms-appx:/// in all URLs with an HTTP://msappxreplacement/ . This switches both the scheme (ms-appx: to http:) and adds in a fake host name (msappxreplacement)

2. We'll use the WebView2 SetVirtualHostNameToFolderMapping method s that every HTTP URL that goes to hostname "msappxreplacement" will instead read a file from a folder relative to the app.

Just to make life more difficult, the WebView2 navigation flow doesn't actually let you do this easily :-(. You'll need two chunks of code that do three things:

1. Replace the URI with the ms-appx: scheme with an HTTP URL that points to the msappxreplacement hostname. This must be done in the NavigationStarting event handler and requires that the original navigation be canceled and a new navigation started.

2. Set the NavigationStarting event handler on your WebView2 object

3. Update your WebView2.CoreWebView2 with a virtual hostname redirector so that all HTTP URLs that use msappxreplacement as the hostname instead just read from a local directory.

Code snippets:

NavigationStarting event handler must cancel the original navigation and instead set the source to this other place. You can't just update the URI because the StartingEventArgs ".Uri" value doesn't let you. This handles the item #1 above.

        private void UiWebView_NavigationStarting(WebView2 sender, Microsoft.Web.WebView2.Core.CoreWebView2NavigationStartingEventArgs args)
        {
            // Input URL: ms-appx:///Assets/SimpleMapLeaflet/SimpleMapLeaflet.html
            // Updated URL: http://msappxreplacement/SimpleMapLeaflet.html
            var originalUri = args.Uri;
            if (originalUri.StartsWith("ms-appx:///"))
            {
                var replacementUri = originalUri.Replace("ms-appx:///", "http://msappxreplacement/");
                args.Cancel = true; // Cancel the original navigation.
                sender.Source = new Uri(replacementUri);
            }
        }

At initialization (like as part of your control Loaded event)

    uiWebView.NavigationStarting += UiWebView_NavigationStarting;
            await uiWebView.EnsureCoreWebView2Async();
            const String assetFolder = "Assets/HtmlSubdirectory";
            uiWebView.CoreWebView2.SetVirtualHostNameToFolderMapping
             ("msappxreplacement", assetFolder, 
               Microsoft.Web.WebView2.Core.CoreWebView2HostResourceAccessKind.Allow);


This code sets up the WebView2 to divert all URLs with an "msappxreplacement" hostname to the given directory. The directory will be in the app's installation directory (assuming you have a deployable app, of course). The "uiWebView" is the WebView2 that you put onto your XAML control. This handles the item #2 and #3 above.

Hints: the folder must exist for this to work! Otherwise the SetVirtualHostNameToFolderMapping will throw an exception.

Quick gripe: none of this should be needed. There's no reason why the WebView2 shouldn't come this way out of the box. And it's super painful that the ms-appx scheme is so far from handled by WebView2 that the only place to do the replacement is in NavigationStarting event. If the scheme isn't replaced there, WebView2 will simply fail and not even try to load the URL.


Helpful links:

See https://github.com/MicrosoftEdge/WebView2Feedback/issues/212

See also: https://github.com/microsoft/microsoft-ui-xaml/issues/1967

This restriction is not mentioned in https://learn.microsoft.com/en-us/microsoft-edge/webview2/get-started/winui