WinForms HTML viewer: load a local page with WebView2

Consider a fictional inspection report delivered as index.html, report.css, and photos/pump.jpg. The desktop viewer must load the report and its accompanying files after installation, rather than relying on an author's original filesystem path.

Add the native control first

Microsoft's WinForms getting-started guide covers the Microsoft.Web.WebView2 NuGet package, the control, initialization, and the WebView2 Runtime. Follow that setup for your project's target framework and deployment method. Installing a NuGet package in development does not by itself establish that the intended user's machine has the required runtime. WinForms setup

The following is a form integration fragment. It assumes the designer already created a control named webView, and that the application's output includes the Report folder:

using Microsoft.Web.WebView2.Core;
using System;
using System.IO;
using System.Windows.Forms;

private async void ReportForm_Load(
    object sender, EventArgs e)
{
    try
    {
        string folder = Path.Combine(
            AppContext.BaseDirectory, "Report");

        if (!File.Exists(
            Path.Combine(folder, "index.html")))
        {
            MessageBox.Show("Report is missing.");
            return;
        }

        await webView.EnsureCoreWebView2Async();

        webView.CoreWebView2
            .SetVirtualHostNameToFolderMapping(
                "report.example", folder,
                CoreWebView2HostResourceAccessKind
                    .DenyCors);

        webView.CoreWebView2.Navigate(
            "https://report.example/index.html");
    }
    catch (Exception ex)
    {
        MessageBox.Show(
            "Could not open report: " + ex.Message);
    }
}

Attach the handler once to the form's Load event. Use the application's normal logging and user-facing error handling in production; the message boxes keep this integration fragment short.

Keep dependencies inside the mapped folder

The virtual host maps a local directory to an HTTPS URL inside WebView2. It does not upload that directory to a public server or create an externally shareable website. Microsoft documents this route for local resources and an origin suitable for browser APIs that depend on one. Virtual host mapping

Use relative references in the report:

<link rel="stylesheet" href="report.css">
<img src="photos/pump.jpg"
     alt="Pump label beside the shutoff valve">

An absolute path into the author's Downloads folder will not become portable through mapping. Include the report assets in the deployed folder and verify their exact filenames. Map only the dedicated report directory, rather than a broad directory containing unrelated user files.

Choose string navigation for a different job

NavigateToString displays generated HTML without first writing a file. Its document uses about:blank, and the HTML string has a documented 2 MB limit. It is useful for a small self-contained status message; it does not give relative images the same base URL as the report-folder mapping. String navigation considerations

Use one route deliberately. If the report consists of several files, folder mapping keeps their relationship visible. If it is a short generated string, include what that view requires and keep the size and origin constraints in mind.

Review navigation and native access separately

WebView2 is a browser surface inside a desktop application. If the application accepts HTML from other people, decide which navigation destinations and native capabilities it allows. Validate the origin before exchanging sensitive data or exposing host objects; a locally displayed document should not inherit unrestricted desktop authority. Microsoft's security guidance explains those boundaries. WebView2 security

This fragment adds no host object or message bridge. Add those only when the actual application needs them, with separate validation.

Check the installed report, not just the development copy

Run the viewer from the deployed output folder and confirm the report title, stylesheet, and pump photograph load. Rename the fixture photograph temporarily in development and confirm that the missing asset is visible as a failure, then restore it. Resize the form and check that the report remains readable.

Diagnosing missing HTML images covers relative-path mistakes within the document. Here the additional responsibility is the desktop application's loading route: reopen the packaged report on the intended machine and confirm that its complete folder travels with it.