Skip to content

Document how the virtual host name affects navigation time #3880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Burak Bakir (Burakuslendera) wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Document how the virtual host name affects navigation time #3880

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b27457d
Document how the virtual host name affects navigation time
Burakuslendera Jul 25, 2026
848e2fd
local toc
mikehoffms Jul 28, 2026
b8e92de
Writer/Editor pass
mikehoffms Jul 28, 2026
4852ff1
Merge branch 'main' into pr/3880
mikehoffms Jul 31, 2026
3e93016
Merge branch 'main' into pr/3880
mikehoffms Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 65 additions & 1 deletion microsoft-edge/webview2/concepts/working-with-local-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ ms.author: msedgedevrel
ms.topic: article
ms.service: microsoft-edge
ms.subservice: webview
ms.date: 02/21/2025
ms.date: 07/27/2026
---
# Using local content in WebView2 apps

Expand All @@ -18,6 +18,54 @@ In addition to loading remote content, content can also be loaded locally into W

These approaches are described below.

**Detailed contents:**
* [Selecting an approach](#selecting-an-approach)
* [Loading local content by navigating to a file URL](#loading-local-content-by-navigating-to-a-file-url)
* [Considerations for loading local content by navigating to a file URL](#considerations-for-loading-local-content-by-navigating-to-a-file-url)
* [Cross-origin resources](#cross-origin-resources)
* [Origin-based DOM APIs](#origin-based-dom-apis)
* [DOM APIs requiring secure context](#dom-apis-requiring-secure-context)
* [Dynamic content](#dynamic-content)
* [Additional web resources](#additional-web-resources)
* [Additional web resources resolved in WebView2 process](#additional-web-resources-resolved-in-webview2-process)
* [APIs for loading local content by navigating to a file URL](#apis-for-loading-local-content-by-navigating-to-a-file-url)
* [Example of a file URL](#example-of-a-file-url)
* [Example of navigating to a file URL](#example-of-navigating-to-a-file-url)
* [Loading local content by navigating to an HTML string](#loading-local-content-by-navigating-to-an-html-string)
* [Considerations for loading local content by navigating to an HTML string](#considerations-for-loading-local-content-by-navigating-to-an-html-string)
* [Origin-based DOM APIs](#origin-based-dom-apis-1)
* [DOM APIs requiring secure context](#dom-apis-requiring-secure-context-1)
* [Dynamic content](#dynamic-content-1)
* [Additional web resources](#additional-web-resources-1)
* [Additional web resources resolved in WebView2 process](#additional-web-resources-resolved-in-webview2-process-1)
* [APIs for loading local content by navigating to an HTML string](#apis-for-loading-local-content-by-navigating-to-an-html-string)
* [Example string representation of a webpage](#example-string-representation-of-a-webpage)
* [Example of navigating to an HTML string](#example-of-navigating-to-an-html-string)
* [Loading local content by using virtual host name mapping](#loading-local-content-by-using-virtual-host-name-mapping)
* [Considerations for loading local content by using virtual host name mapping](#considerations-for-loading-local-content-by-using-virtual-host-name-mapping)
* [Choosing a virtual host name](#choosing-a-virtual-host-name)
* [Origin-based DOM APIs](#origin-based-dom-apis-2)
* [DOM APIs requiring secure context](#dom-apis-requiring-secure-context-2)
* [Dynamic content](#dynamic-content-2)
* [Additional web resources](#additional-web-resources-2)
* [Additional web resources resolved in WebView2 process](#additional-web-resources-resolved-in-webview2-process-2)
* [Source maps with virtual host name mapping](#source-maps-with-virtual-host-name-mapping)
* [APIs for loading local content by using virtual host name mapping](#apis-for-loading-local-content-by-using-virtual-host-name-mapping)
* [Example of virtual host name mapping](#example-of-virtual-host-name-mapping)
* [Loading local content by handling the WebResourceRequested event](#loading-local-content-by-handling-the-webresourcerequested-event)
* [Custom scheme registration](#custom-scheme-registration)
* [Considerations for loading local content by handling the WebResourceRequested event](#considerations-for-loading-local-content-by-handling-the-webresourcerequested-event)
* [Choosing a host name for the origin](#choosing-a-host-name-for-the-origin)
* [Origin-based DOM APIs](#origin-based-dom-apis-3)
* [DOM APIs requiring secure context](#dom-apis-requiring-secure-context-3)
* [Dynamic content](#dynamic-content-3)
* [Additional web resources](#additional-web-resources-3)
* [Additional web resources resolved in WebView2 process](#additional-web-resources-resolved-in-webview2-process-3)
* [Source maps with the WebResourceRequested event](#source-maps-with-the-webresourcerequested-event)
* [APIs for loading local content by handling the WebResourceRequested event](#apis-for-loading-local-content-by-handling-the-webresourcerequested-event)
* [Example of handling the WebResourceRequested event](#example-of-handling-the-webresourcerequested-event)
* [See also](#see-also)


<!-- ====================================================================== -->
## Selecting an approach
Expand Down Expand Up @@ -332,6 +380,16 @@ Due to a current limitation, media files that are accessed using a virtual host
#### Considerations for loading local content by using virtual host name mapping


<!-- ---------- -->
###### Choosing a virtual host name

The virtual host name is resolved by the network stack before the mapping is applied, so mapping a name that doesn't resolve can add a DNS timeout to every navigation. The delay falls between the main document being handed to the WebView2 control and the renderer requesting the first subresource.

Reserved top-level domains such as `.example`, `.test`, or `.invalid` don't avoid this. Those are reserved so that nobody registers them, but the resolver still queries the network and waits for the answer.

Use a name under `.localhost` instead, such as `demo.localhost`. [RFC 6761](https://www.rfc-editor.org/rfc/rfc6761#section-6.3) reserves `.localhost` as always resolving to the loopback interface, so the resolver answers it without a network query. The resulting origin is still HTTPS and still a secure context, so the considerations below continue to apply.


<!-- ---------- -->
###### Origin-based DOM APIs

Expand Down Expand Up @@ -455,6 +513,12 @@ If you want to use a custom scheme to make the Web Resource Request that generat
#### Considerations for loading local content by handling the `WebResourceRequested` event


<!-- ---------- -->
###### Choosing a host name for the origin

The host name of the origin you serve is resolved by the network stack, even though your event handler answers the request in your app process. A name that doesn't resolve therefore adds the same per-navigation DNS timeout that's described in [Choosing a virtual host name](#choosing-a-virtual-host-name), above. Use a name under `.localhost`.


<!-- ---------- -->
###### Origin-based DOM APIs

Expand Down