CoreWebView2.SetVirtualHostNameToFolderMapping Method

Definition

Namespace:

Microsoft.Web.WebView2.Core

Assembly:

Microsoft.Web.WebView2.Core.dll

Package:

Microsoft.Web.WebView2 v1.0.2849.39

Sets a mapping between a virtual host name and a folder path to make available to web sites via that host name.

public void SetVirtualHostNameToFolderMapping (string hostName, string folderPath, Microsoft.Web.WebView2.Core.CoreWebView2HostResourceAccessKind accessKind);

member this.SetVirtualHostNameToFolderMapping : string * string * Microsoft.Web.WebView2.Core.CoreWebView2HostResourceAccessKind -> unit

Public Sub SetVirtualHostNameToFolderMapping (hostName As String, folderPath As String, accessKind As CoreWebView2HostResourceAccessKind)

Parameters

hostName

String

A virtual host name.

folderPath

String

A folder path name to be mapped to the virtual host name. The length must not exceed the Windows MAX_PATH limit.

accessKind

CoreWebView2HostResourceAccessKind

The level of access to resources under the virtual host from other sites.

Examples

webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
    "appassets.example", "assets", CoreWebView2HostResourceAccessKind.DenyCors);
webView.Source = new Uri("https://appassets.example/index.html");

This in an example on how to embed a local image. For more information see NavigateToString(String).

webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
    "appassets.example", "assets", CoreWebView2HostResourceAccessKind.DenyCors);
string c_navString = "<img src="http://appassets.example/wv2.png" />";
webview.NavigateToString(c_navString);

Remarks

After setting the mapping, documents loaded in the WebView can use HTTP or HTTPS URLs at the specified host name specified by hostName to access files in the local folder specified by folderPath. This mapping applies to both top-level document and iframe navigations as well as subresource references from a document. This also applies to dedicated and shared worker scripts but does not apply to service worker scripts.

Due to a current implementation limitation, media files accessed using virtual host name can be very slow to load.

As the resource loaders for the current page might have already been created and running, changes to the mapping might not be applied to the current page and a reload of the page is needed to apply the new mapping.

Both absolute and relative paths are supported for folderPath. Relative paths are interpreted as relative to the folder where the exe of the app is in.

For example, after calling SetVirtualHostNameToFolderMapping("appassets.example", "assets", CoreWebView2HostResourceAccessKind.Deny);, navigating to https://appassets.example/my-local-file.html will show content from my-local-file.html in the assets subfolder located on disk under the same path as the app's executable file.

DOM elements that want to reference local files will have their host reference virtual host in the source. If there are multiple folders being used, define one unique virtual host per folder.

You should typically choose virtual host names that are never used by real sites. If you own a domain such as example.com, another option is to use a subdomain reserved for the app (like my-app.example.com).

RFC 6761 has reserved several special-use domain names that are guaranteed to not be used by real sites (for example, .example, .test, and .invalid).

Note that using .local as the top-level domain name will work but can cause a delay during navigations. You should avoid using .local if you can.

Apps should use distinct domain names when mapping folder from different sources that should be isolated from each other. For instance, the app might use app-file.example for files that ship as part of the app, and book1.example might be used for files containing books from a less trusted source that were previously downloaded and saved to the disk by the app.

The host name used in the APIs is canonicalized using Chromium's host name parsing logic before being used internally.

For more information see HTML5 2.6 URLs.

All host names that are canonicalized to the same string are considered identical. For example, EXAMPLE.COM and example.com are treated as the same host name. An international host name and its Punycode-encoded host name are considered the same host name. There is no DNS resolution for host name and the trailing '.' is not normalized as part of canonicalization.

Therefore example.com and example.com. are treated as different host names. Similarly, virtual-host-name and virtual-host-name.example.com are treated as different host names even if the machine has a DNS suffix of example.com.

Specify the minimal cross-origin access necessary to run the app. If there is not a need to access local resources from other origins, use @CoreWebView2HostResourceAccessKind$.Deny. Setting the accessKind parameter does not adjust the app container permission for a folder.

See also

• ClearVirtualHostNameToFolderMapping(String)