Microsoft Edge WebView2

https://learn.microsoft.com/en-us/microsoft-edge/webview2/
Admin
Microsoft Edge WebView2 is a control that allows developers to embed web technologies (HTML, CSS,...
Tokens:1,286,938
Snippets:9,707
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalfind

Documentation for the Start method of ICoreWebView2ExperimentalFind, including its signature, parameters, remarks, and a C++ example.

```APIDOC
## Start

### Description
Initiates a find using the specified find options asynchronously. Displays the Find bar and starts the find session. If a find session was already ongoing, it will be stopped and replaced with this new instance. If called with an empty string, the Find bar is displayed but no finding occurs. Changing the FindOptions object after initiation won't affect the ongoing find session. To change the ongoing find session, Start must be called again with a new or modified FindOptions object. Start supports HTML and TXT document queries. In general, this API is designed for text-based find sessions. If you start a find session programmatically on another file format that doesn't have text fields, the find session will try to execute but will fail to find any matches. (It will silently fail) Note: The asynchronous action completes when the UI has been displayed with the find term in the UI bar, and the matches have populated on the counter on the find bar. There may be a slight latency between the UI display and the matches populating in the counter. The MatchCountChanged and ActiveMatchIndexChanged events are only raised after Start has completed; otherwise, they will have their default values (-1 for active match index and 0 for match count). To start a new find session (beginning the search from the first match), call `Stop` before invoking `Start`. If `Start` is called consecutively with the same options and without calling `Stop`, the find session will continue from the current position in the existing session. Calling `Start` without altering its parameters will behave either as `FindNext` or `FindPrevious`, depending on the most recent search action performed. Start will default to forward if neither have been called. However, calling Start again during an ongoing find session does not resume from the point of the current active match. For example, given the text "1 1 A 1 1" and initiating a find session for "A", then starting another find session for "1", it will start searching from the beginning of the document, regardless of the previous active match. This behavior indicates that changing the find query initiates a completely new find session, rather than continuing from the previous match index.

### Method
Start

### Signature
`public HRESULT Start(ICoreWebView2ExperimentalFindOptions * options, ICoreWebView2ExperimentalFindStartCompletedHandler * handler)`

### Parameters
- **options** (ICoreWebView2ExperimentalFindOptions*) - Required - The find options to use for the find session.
- **handler** (ICoreWebView2ExperimentalFindStartCompletedHandler*) - Required - The completion handler that is called when the asynchronous operation completes.

### Return Value
HRESULT - Indicates the success or failure of the operation.

### Remarks
- The asynchronous action completes when the UI has been displayed with the find term in the UI bar, and the matches have populated on the counter on the find bar.
- The MatchCountChanged and ActiveMatchIndexChanged events are only raised after Start has completed; otherwise, they will have their default values (-1 for active match index and 0 for match count).
- To start a new find session (beginning the search from the first match), call `Stop` before invoking `Start`.
- If `Start` is called consecutively with the same options and without calling `Stop`, the find session will continue from the current position in the existing session.
- Calling `Start` without altering its parameters will behave either as `FindNext` or `FindPrevious`, depending on the most recent search action performed. Start will default to forward if neither have been called.
- Changing the find query initiates a completely new find session, rather than continuing from the previous match index.

### Example (C++)
```cpp
bool AppWindow::Start(const std::wstring& searchTerm)
{
    auto webView2Experimental29 = m_webView.try_query<ICoreWebView2Experimental29>();
    CHECK_FEATURE_RETURN(webView2Experimental29);

    wil::com_ptr<ICoreWebView2ExperimentalFind> webView2find;
    CHECK_FAILURE(webView2Experimental29->get_Find(&webView2find));
    SetupFindEventHandlers(webView2find);

    // Initialize find configuration/settings
    if (!findOptions)
    {
        findOptions = SetDefaultFindOptions();
    }

    // Check if the search term has changed to determine if UI needs to be updated
    if (m_findOnPageLastSearchTerm != searchTerm)
    {
        m_findOnPageLastSearchTerm =
            searchTerm; // Update the last search term for future comparisons
    }

    // Start the find operation
    CHECK_FAILURE(webView2find->Start(
        findOptions.get(), Callback<ICoreWebView2ExperimentalFindStartCompletedHandler>(
                               [this](HRESULT result) -> HRESULT { return S_OK; })
                               .Get()));
    return true;
}
```
```

--------------------------------

### ChannelSearchKind and ReleaseChannels example

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/how-to/set-preview-channel

Example setting for ChannelSearchKind and ReleaseChannels. With this configuration, the loader tries to run the app with Edge Beta if installed, otherwise falls back to the Stable WebView2 Runtime.

```text
Channel Search Kind: 1 (Least Stable)
Release Channels: 0 (Stable), 1 (Beta)

```

--------------------------------

### Start find session with ICoreWebView2ExperimentalFind::Start

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalfind

Initiates a find session asynchronously. Displays the Find bar and starts the find session. If a session is ongoing, it is replaced. Empty string displays the bar without finding. Changing options after start has no effect. The asynchronous action completes when UI is displayed and matches are populated. MatchCountChanged and ActiveMatchIndexChanged events are only raised after Start completes. Call Stop before Start to begin from the first match. Consecutive Start calls with same options continue from current position. Changing the query starts a new session from the beginning.

```C++
bool AppWindow::Start(const std::wstring& searchTerm)
{
    auto webView2Experimental29 = m_webView.try_query<ICoreWebView2Experimental29>();
    CHECK_FEATURE_RETURN(webView2Experimental29);

    wil::com_ptr<ICoreWebView2ExperimentalFind> webView2find;
    CHECK_FAILURE(webView2Experimental29->get_Find(&webView2find));
    SetupFindEventHandlers(webView2find);

    // Initialize find configuration/settings
    if (!findOptions)
    {
        findOptions = SetDefaultFindOptions();
    }

    // Check if the search term has changed to determine if UI needs to be updated
    if (m_findOnPageLastSearchTerm != searchTerm)
    {
        m_findOnPageLastSearchTerm =
            searchTerm; // Update the last search term for future comparisons
    }

    // Start the find operation
    CHECK_FAILURE(webView2find->Start(
        findOptions.get(), Callback<ICoreWebView2ExperimentalFindStartCompletedHandler>(
                               [this](HRESULT result) -> HRESULT { return S_OK; })
                               .Get()));
    return true;
}

```

--------------------------------

### Print to a specified printer with custom settings (C#)

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/how-to/print

C# example for printing to a specified printer with custom settings. Uses CoreWebView2.PrintAsync and CoreWebView2PrintStatus to handle success, printer unavailable, and other failures. Includes placeholder methods for getting the printer name and creating CoreWebView2PrintSettings.

```csharp
async void PrintToPrinter(object sender, RoutedEventArgs e)
{
  string printerName = GetPrinterName();
  CoreWebView2PrintSettings printSettings = GetSelectedPrinterPrintSettings(printerName);
  string title = WebView2.CoreWebView2.DocumentTitle;
  MessageDialog dialog = new MessageDialog("", "Print");

  try
  {
    CoreWebView2PrintStatus printStatus =
                          await WebView2.CoreWebView2.PrintAsync(printSettings);

    if (printStatus == CoreWebView2PrintStatus.Succeeded)
    {
      dialog = new MessageDialog("Printing " + title +
                        " document to printer succeeded", "Print to printer");
    }
    else if (printStatus == CoreWebView2PrintStatus.PrinterUnavailable)
    {
      dialog = new MessageDialog("Selected printer is not found, not available, " +
                                  "offline or error state", "Print to printer");
    }
    else
    {
      dialog = new MessageDialog("Printing " + title +
                                     " document to printer is failed", "Print");
    }
  }
  catch (ArgumentException)
  {
    dialog = new MessageDialog("Invalid settings provided for the specified printer", "Print");
  }
  catch (Exception)
  {
     dialog = new MessageDialog("Printing " + title + " document already in progress", "Print");
  }
  await dialog.ShowAsync();
}

// Gets the printer name by displaying the list of installed printers to the user,
// and returns the user-selected printer.
string GetPrinterName()
{
  // Use DeviceInformation.FindAllAsync to get the list of local printers with AQS as:
  // System.Devices.HardwareIds:~~"PRINTENUM\LocalPrintQueue"
  // Display the list of printers to the user, and get the desired printer to use.
  // Return the name of the user's selected printer.
}

// Gets print settings for the selected printer.
// You can also get the capabilities from the printer APIs, and display them to the
// user to get the print settings for the current webpage and for the selected printer.
CoreWebView2PrintSettings GetSelectedPrinterPrintSettings(string printerName)
{
  CoreWebView2PrintSettings printSettings = null;
  printSettings = WebView2.CoreWebView2.Environment.CreatePrintSettings();
  printSettings.ShouldPrintBackgrounds = true;
  printSettings.ShouldPrintHeaderAndFooter = true;

  return printSettings;

  // or
  // Get the print ticket and use PrintTicketCapabilities from
  // Windows.Graphics.Printing.PrintTicket to get the capabilities of the selected printer.
  // Display the printer capabilities to the user, along with the page settings.
  // Return the user-selected settings.
}
```

--------------------------------

### NavigateWithWebResourceRequest C++ example

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2_2

Constructs a WebResourceRequest with POST data and custom headers, then navigates the WebView2 to the target URL. The method must be "GET" or "POST"; post data is only sent for POST requests with an HTTP(S) URI. Headers in the request override WebView2 runtime headers except Cookie headers.

```cpp
        wil::com_ptr<ICoreWebView2Environment2> webviewEnvironment2;
        CHECK_FAILURE(appWindow->GetWebViewEnvironment()->QueryInterface(
            IID_PPV_ARGS(&webviewEnvironment2)));
        wil::com_ptr<ICoreWebView2WebResourceRequest> webResourceRequest;
        wil::com_ptr<IStream> postDataStream = SHCreateMemStream(
            reinterpret_cast<const BYTE*>(postDataBytes.get()), sizeNeededForMultiByte);

        // This is acts as a form submit to https://www.w3schools.com/action_page.php
        CHECK_FAILURE(webviewEnvironment2->CreateWebResourceRequest(
            L"https://www.w3schools.com/action_page.php", L"POST", postDataStream.get(),
            L"Content-Type: application/x-www-form-urlencoded", &webResourceRequest));
        wil::com_ptr<ICoreWebView2_2> webview2;
        CHECK_FAILURE(m_appWindow->GetWebView()->QueryInterface(IID_PPV_ARGS(&webview2)));
        CHECK_FAILURE(webview2->NavigateWithWebResourceRequest(webResourceRequest.get()));

```

--------------------------------

### C++ example: CreateCoreWebView2ControllerOptions usage

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalenvironment8

Shows how to query for the experimental environment and create controller options, handling invalid profile names.

```cpp
    auto webViewEnvironment8 =
        m_webViewEnvironment.try_query<ICoreWebView2ExperimentalEnvironment8>();
    if (!webViewEnvironment8)
    {
        FeatureNotAvailable();
        return S_OK;
    }

    Microsoft::WRL::ComPtr<ICoreWebView2ExperimentalControllerOptions> options;
    HRESULT hr = webViewEnvironment8->CreateCoreWebView2ControllerOptions(
        m_webviewOption.profile.c_str(), m_webviewOption.isInPrivateMode, options.GetAddressOf());
    if (hr == E_INVALIDARG)
    {
        ShowFailure(hr, L"Unable to create WebView2 due to an invalid profile name.");
        CloseAppWindow();
        return S_OK;
    }
    CHECK_FAILURE(hr);

```

--------------------------------

### Get and set AreWebViewScriptApisEnabledForServiceWorkers

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalprofile15

C++ example using CHECK_FAILURE to get and then toggle the AreWebViewScriptApisEnabledForServiceWorkers property on an ICoreWebView2ExperimentalProfile15 instance.

```cpp
        CHECK_FAILURE(
            webViewExperimentalProfile15->get_AreWebViewScriptApisEnabledForServiceWorkers(
                &isEnabled));
        CHECK_FAILURE(
            webViewExperimentalProfile15->put_AreWebViewScriptApisEnabledForServiceWorkers(
                !isEnabled));

```

--------------------------------

### Approach 1: Download Evergreen WebView2 Runtime Bootstrapper (product.xml)

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/samples/wv2deploymentvsinstallersample

Commented-out PackageFile line for Approach 1: Downloading the Evergreen WebView2 Runtime Bootstrapper through a link. The PublicKey value may change without notice and may need to be updated in product.xml.

```xml
<!-- Download the MicrosoftEdgeWebview2Setup.exe -->
<!-- <PackageFile Name="MicrosoftEdgeWebview2Setup.exe" HomeSite="WebViewRuntime" PublicKey="..."/> -->
```

--------------------------------

### put_FindTerm example

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalfindoptions

Sets the search term on the find options and starts a find session. Requires ICoreWebView2Experimental29 and ICoreWebView2ExperimentalEnvironment18. The term takes effect on the next Start() call.

```cpp
bool AppWindow::FindTerm()
{
    auto webView2Experimental29 = m_webView.try_query<ICoreWebView2Experimental29>();
    CHECK_FEATURE_RETURN(webView2Experimental29);
    wil::com_ptr<ICoreWebView2ExperimentalFind> webView2find;
    CHECK_FAILURE(webView2Experimental29->get_Find(&webView2find));

    TextInputDialog dialog(
        GetMainWindow(), L"Find on Page Term", L"Find on Page Term:", L"Enter Find Term");

    auto m_env18 = m_webViewEnvironment.try_query<ICoreWebView2ExperimentalEnvironment18>();
    CHECK_FEATURE_RETURN(m_env18);
    CHECK_FAILURE(webView2find->Stop());

    if (!findOptions)
    {
        findOptions = SetDefaultFindOptions();
    }
    CHECK_FAILURE(findOptions->put_FindTerm(dialog.input.c_str()));
    CHECK_FAILURE(webView2find->Start(
        findOptions.get(), Callback<ICoreWebView2ExperimentalFindStartCompletedHandler>(
                               [this](HRESULT result) -> HRESULT { return S_OK; })
                               .Get()));
    return true;
}
```

--------------------------------

### InitializeWebView: CreateCoreWebView2EnvironmentWithOptions

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/samples/webview2apissample

Creates the WebView2 environment with CreateCoreWebView2EnvironmentWithOptions. If the Edge installation is missing, it shows a message box; otherwise it calls ShowFailure.

```cpp
HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
    subFolder, nullptr, options.Get(),
    Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
        this, &AppWindow::OnCreateEnvironmentCompleted)
        .Get());
if (!SUCCEEDED(hr))
{
    if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))
    {
        MessageBox(
            m_mainWindow,
            L"Couldn't find Edge installation. "
            "Do you have a version installed that's compatible with this "
            "WebView2 SDK version?",
            nullptr, MB_OK);
    }
    else
    {
        ShowFailure(hr, L"Failed to create webview environment");
    }
}

```

--------------------------------

### ICoreWebView2ExperimentalNavigationStartingEventArgs Members

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalnavigationstartingeventargs

Methods to get and set additional allowed frame ancestors for the navigation starting event.

```APIDOC
## get_AdditionalAllowedFrameAncestors

### Description
Gets the additional allowed frame ancestors set by the host app.

### Method
HRESULT

### Signature
`public HRESULT get_AdditionalAllowedFrameAncestors(LPWSTR * value)`

### Parameters
- **value** (LPWSTR*) - Output pointer to the additional allowed frame ancestors string.

### Return Value
HRESULT indicating success or failure.
```

```APIDOC
## put_AdditionalAllowedFrameAncestors

### Description
Sets additional allowed frame ancestors to allow a frame to be embedded by additional ancestors beyond those allowed by the HTTP header X-Frame-Options and Content-Security-Policy frame-ancestors directive. This property is ignored for top-level document navigation.

### Method
HRESULT

### Signature
`public HRESULT put_AdditionalAllowedFrameAncestors(LPCWSTR value)`

### Parameters
- **value** (LPCWSTR) - The additional allowed frame ancestors string. For example, `https://example.com https://www.example.com`.

### Return Value
HRESULT indicating success or failure.

### Remarks
- The property is ignored for top-level document navigation.
- Use specific origins instead of wildcards whenever possible.
- Only set this property for trusted origins to avoid Clickjacking attacks.
```

--------------------------------

### Handle DownloadStarting with deferral

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2_4

Handles the DownloadStarting event by showing a dialog to confirm or cancel the download. If confirmed, sets the result file path; otherwise cancels. Uses a deferral to avoid reentrancy and completes it asynchronously.

```cpp
TextInputDialog dialog(
    m_appWindow->GetMainWindow(), L"Download Starting", prompt.c_str(),
    description.c_str(), resultFilePath.get());
if (dialog.confirmed)
{
    // If user selects `OK`, the download will complete normally.
    // Result file path will be updated if a new one was provided.
    CHECK_FAILURE(args->put_ResultFilePath(dialog.input.c_str()));
    UpdateProgress(download.get());
}
else
{
    // If user selects `Cancel`, the download will be canceled.
    CHECK_FAILURE(args->put_Cancel(TRUE));
}
};
```

```cpp
// Obtain a deferral for the event so that the CoreWebView2
// doesn't examine the properties we set on the event args until
// after we call the Complete method asynchronously later.
wil::com_ptr<ICoreWebView2Deferral> deferral;
CHECK_FAILURE(args->GetDeferral(&deferral));

// We avoid potential reentrancy from running a message loop in the download
// starting event handler by showing our download dialog later when we
// complete the deferral asynchronously.
m_appWindow->RunAsync([deferral, showDialog]() {
    showDialog();
    CHECK_FAILURE(deferral->Complete());
});

return S_OK;
})
.Get(),
&m_downloadStartingToken));
```

--------------------------------

### C++: PostWebMessageAsJson example with TextInputDialog

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentaldedicatedworker

Shows how to call PostWebMessageAsJson on a dedicated worker from a C++ event handler. It uses a TextInputDialog to get JSON input and posts it asynchronously. The example includes a sample JSON string.

```cpp
    // Do not block from event handler
    m_appWindow->RunAsync(
        [this, dedicatedWorker]
        {
            TextInputDialog dialog(
                m_appWindow->GetMainWindow(), L"Post Web Message JSON", L"Web message JSON",
                L"Enter the web message as JSON.",
                L"{\"command\":\"ADD\",\"first\":2,\"second\":3}");
            // Ex: {"command":"ADD","first":2,"second":3}
            if (dialog.confirmed)
            {
                dedicatedWorker->PostWebMessageAsJson(dialog.input.c_str());
            }
        });
```

--------------------------------

### CreateCoreWebView2CompositionController with environment creation and fallback

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2environment3

Shows how to create a WebView2 environment with options and handle common failures, then in the completion callback create a composition controller when ICoreWebView2Environment3 is available and a DirectComposition or Windows Composition device is present, otherwise fall back to CreateCoreWebView2Controller.

```cpp
HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
        subFolder, m_userDataFolder.c_str(), options.Get(),
        Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
            this, &AppWindow::OnCreateEnvironmentCompleted)
            .Get());
    if (!SUCCEEDED(hr))
    {
        switch (hr)
        {
        case HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND):
        {
            MessageBox(
                m_mainWindow,
                L"Couldn't find Edge WebView2 Runtime. "
                "Do you have a version installed?",
                nullptr, MB_OK);
        }
        break;
        case HRESULT_FROM_WIN32(ERROR_FILE_EXISTS):
        {
            MessageBox(
                m_mainWindow,
                L"User data folder cannot be created because a file with the same name already "
                L"exists.",
                nullptr, MB_OK);
        }
        break;
        case E_ACCESSDENIED:
        {
            MessageBox(
                m_mainWindow, L"Unable to create user data folder, Access Denied.", nullptr,
                MB_OK);
        }
        break;
        case E_FAIL:
        {
            MessageBox(m_mainWindow, L"Edge runtime unable to start", nullptr, MB_OK);
        }
        break;
        default:
        {
            ShowFailure(hr, L"Failed to create WebView2 environment");
        }
        }
    }
}
```

```cpp
// This is the callback passed to CreateWebViewEnvironmentWithOptions.
// Here we simply create the WebView.
HRESULT AppWindow::OnCreateEnvironmentCompleted(
    HRESULT result, ICoreWebView2Environment* environment)
{
    if (result != S_OK)
    {
        ShowFailure(result, L"Failed to create environment object.");
        return S_OK;
    }
    m_webViewEnvironment = environment;

    if (m_webviewOption.entry == WebViewCreateEntry::EVER_FROM_CREATE_WITH_OPTION_MENU ||
        m_creationModeId == IDM_CREATION_MODE_HOST_INPUT_PROCESSING
    )
    {
        return CreateControllerWithOptions();
    }
    auto webViewEnvironment3 = m_webViewEnvironment.try_query<ICoreWebView2Environment3>();

    if (webViewEnvironment3 && (m_dcompDevice || m_wincompCompositor))
    {
        CHECK_FAILURE(webViewEnvironment3->CreateCoreWebView2CompositionController(
            m_mainWindow,
            Callback<ICoreWebView2CreateCoreWebView2CompositionControllerCompletedHandler>(
                [this](
                    HRESULT result,
                    ICoreWebView2CompositionController* compositionController) -> HRESULT
                {
                    auto controller =
                        wil::com_ptr<ICoreWebView2CompositionController>(compositionController)
                            .query<ICoreWebView2Controller>();
                    return OnCreateCoreWebView2ControllerCompleted(result, controller.get());
                })
                .Get()));
    }
    else
    {
        CHECK_FAILURE(m_webViewEnvironment->CreateCoreWebView2Controller(
            m_mainWindow, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
                              this, &AppWindow::OnCreateCoreWebView2ControllerCompleted)
                              .Get()));
    }

    return S_OK;
}
```

--------------------------------

### Set up WebView2 environments with CreateCoreWebView2EnvironmentWithOptions

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/samples/webview2browser

Creates two separate WebView2 environments: one for user web content and one for the browser UI, using CreateCoreWebView2EnvironmentWithOptions with distinct data directories. The content environment is created first, then InitUIWebViews creates the UI environment and calls CreateBrowserControlsWebView and CreateBrowserOptionsWebView.

```cpp
    // Get directory for user data. This will be kept separated from the
    // directory for the browser UI data.
    std::wstring userDataDirectory = GetAppDataDirectory();
    userDataDirectory.append(L"\\User Data");

    // Create WebView environment for web content requested by the user. All
    // tabs will be created from this environment and kept isolated from the
    // browser UI. This environment is created first so the UI can request new
    // tabs when it's ready.
    HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(nullptr, userDataDirectory.c_str(),
        L"", Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
            [this](HRESULT result, ICoreWebView2Environment* env) -> HRESULT
    {
        RETURN_IF_FAILED(result);

        m_contentEnv = env;
        HRESULT hr = InitUIWebViews();

        if (!SUCCEEDED(hr))
        {
            OutputDebugString(L"UI WebViews environment creation failed\n");
        }

        return hr;
    }).Get());

```

```cpp
HRESULT BrowserWindow::InitUIWebViews()
{
    // Get data directory for browser UI data
    std::wstring browserDataDirectory = GetAppDataDirectory();
    browserDataDirectory.append(L"\\Browser Data");

    // Create WebView environment for browser UI. A separate data directory is
    // used to isolate the browser UI from web content requested by the user.
    return CreateCoreWebView2EnvironmentWithOptions(nullptr, browserDataDirectory.c_str(),
        L"", Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
            [this](HRESULT result, ICoreWebView2Environment* env) -> HRESULT
    {
        // Environment is ready, create the WebView
        m_uiEnv = env;

        RETURN_IF_FAILED(CreateBrowserControlsWebView());
        RETURN_IF_FAILED(CreateBrowserOptionsWebView());

        return S_OK;
    }).Get());
}

```

--------------------------------

### C++ example: Get file paths from WebMessageReceived and post back as JSON

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2file

This C++ example shows how to handle a WebMessageReceived event, retrieve additional objects (files) from the event args, get their paths using ICoreWebView2File::get_Path, and post the paths back to the webview as a JSON array. It uses wil::com_ptr and wil::unique_cotaskmem_string. The caller must free the string returned by get_Path with CoTaskMemFree.

```cpp
    CHECK_FAILURE(m_webView->add_WebMessageReceived(
        Callback<ICoreWebView2WebMessageReceivedEventHandler>(
            [this](ICoreWebView2* sender, ICoreWebView2WebMessageReceivedEventArgs* args)
            {
                wil::com_ptr<ICoreWebView2WebMessageReceivedEventArgs2> args2 =
                    wil::com_ptr<ICoreWebView2WebMessageReceivedEventArgs>(args)
                        .query<ICoreWebView2WebMessageReceivedEventArgs2>();
                wil::com_ptr<ICoreWebView2ObjectCollectionView> objectsCollection;
                args2->get_AdditionalObjects(&objectsCollection);
                unsigned int length;
                objectsCollection->get_Count(&length);

                // Array of file paths to be sent back to the webview as JSON
                std::wstring pathObjects = L"[";
                for (unsigned int i = 0; i < length; i++)
                {
                    wil::com_ptr<IUnknown> object;
                    objectsCollection->GetValueAtIndex(i, &object);

                    wil::com_ptr<ICoreWebView2File> file = object.query<ICoreWebView2File>();
                    if (file)
                    {
                        // Add the file to message to be sent back to webview
                        wil::unique_cotaskmem_string path;
                        file->get_Path(&path);
                        std::wstring pathObject =
                            L"{\"path\":\"" + std::wstring(path.get()) + L"\"}";
                        // Escape backslashes
                        std::wstring pathObjectEscaped;
                        for (const auto& c : pathObject)
                        {
                            if (c == L'\\')
                            {
                                pathObjectEscaped += L"\\\\";
                            }
                            else
                            {
                                pathObjectEscaped += c;
                            }
                        }
                        pathObjects += pathObjectEscaped;

                        if (i < length - 1)
                        {
                            pathObjects += L",";
                        }
                    }
                }
                pathObjects += L"]";

                // Post the message back to the webview so path is accessible to content
                m_webView->PostWebMessageAsJson(pathObjects.c_str());

                return S_OK;
            })
            .Get(),
        &m_webMessageReceivedToken));

```

--------------------------------

### Create WebView2 environment and WebView

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/iwebview2environment

Shows how to create a WebView2 environment and then create a WebView. It closes any existing WebView first to ensure browser switches are applied, then calls CreateWebView2EnvironmentWithDetails and uses the callback to call CreateWebView on the environment. Handles the ERROR_FILE_NOT_FOUND case with a message box.

```cpp
// Create or recreate the WebView and its environment.
void AppWindow::InitializeWebView(InitializeWebViewFlags webviewInitFlags)
{
    m_lastUsedInitFlags = webviewInitFlags;
    // To ensure browser switches get applied correctly, we need to close
    // the existing WebView. This will result in a new browser process
    // getting created which will apply the browser switches.
    CloseWebView();

    LPCWSTR subFolder = nullptr;
    LPCWSTR additionalBrowserSwitches = nullptr;
    HRESULT hr = CreateWebView2EnvironmentWithDetails(
        subFolder, nullptr, additionalBrowserSwitches,
        Callback<IWebView2CreateWebView2EnvironmentCompletedHandler>(
            this, &AppWindow::OnCreateEnvironmentCompleted)
            .Get());
    if (!SUCCEEDED(hr))
    {
        if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))
        {
            MessageBox(
                m_mainWindow,
                L"Couldn't find Edge installation. "
                "Do you have a version installed that's compatible with this "
                "WebView2 SDK version?",
                nullptr, MB_OK);
        }
        else
        {
            ShowFailure(hr, L"Failed to create webview environment");
        }
    }
}

// This is the callback passed to CreateWebViewEnvironmnetWithDetails.
// Here we simply create the WebView.
HRESULT AppWindow::OnCreateEnvironmentCompleted(
    HRESULT result, IWebView2Environment* environment)
{
    CHECK_FAILURE(result);

    CHECK_FAILURE(environment->QueryInterface(IID_PPV_ARGS(&m_webViewEnvironment)));
        CHECK_FAILURE(m_webViewEnvironment->CreateWebView(
            m_mainWindow, Callback<IWebView2CreateWebViewCompletedHandler>(
                              this, &AppWindow::OnCreateWebViewCompleted)
                              .Get()));
    return S_OK;
}

```

--------------------------------

### get_Icon

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalcontextmenuitem

Gets the Icon for the ContextMenuItem in PNG, Bitmap or SVG formats in the form of an IStream. The stream will be rewound to the start of the image data.

```APIDOC
## get_Icon

### Description
Gets the Icon for the ContextMenuItem in PNG, Bitmap or SVG formats in the form of an IStream. The stream will be rewound to the start of the image data.

### Method
HRESULT

### Signature
public HRESULT get_Icon(IStream ** value)

### Parameters
- **value** (IStream**) - Required - Receives the icon stream.

### Return Value
HRESULT indicating success or failure.
```

--------------------------------

### Get cookie manager with ICoreWebView2Profile5::get_CookieManager

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2profile5

Shows how to query the ICoreWebView2Profile5 interface from a WebView2 instance and call get_CookieManager to retrieve the cookie manager. The example uses wil::com_ptr and CHECK_FAILURE macros.

```cpp
        auto webView2_13 = m_webView.try_query<ICoreWebView2_13>();
        CHECK_FEATURE_RETURN_EMPTY(webView2_13);
        wil::com_ptr<ICoreWebView2Profile> webView2Profile;
        CHECK_FAILURE(webView2_13->get_Profile(&webView2Profile));
        auto webView2Profile5 = webView2Profile.try_query<ICoreWebView2Profile5>();
        CHECK_FEATURE_RETURN_EMPTY(webView2Profile5);
        CHECK_FAILURE(webView2Profile5->get_CookieManager(&m_cookieManager));

```

--------------------------------

### Approach 2: Package Evergreen WebView2 Runtime Bootstrapper (product.xml)

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/samples/wv2deploymentvsinstallersample

Un-commented PackageFile line for Approach 2: Packaging the Evergreen WebView2 Runtime Bootstrapper with the app. This is the default approach in the repo's product.xml.

```xml
<!-- Package the MicrosoftEdgeWebview2Setup.exe -->
<PackageFile Name="MicrosoftEdgeWebview2Setup.exe" />
```

--------------------------------

### Get user data folder with ICoreWebView2Environment7::get_UserDataFolder

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2environment7

C++ example that queries the ICoreWebView2Environment7 interface and calls get_UserDataFolder to retrieve the user data folder. The returned string must be freed with CoTaskMemFree.

```cpp
        auto environment7 = m_webViewEnvironment.try_query<ICoreWebView2Environment7>();
        CHECK_FEATURE_RETURN(environment7);
        wil::unique_cotaskmem_string userDataFolder;
        environment7->get_UserDataFolder(&userDataFolder);
        MessageBox(m_mainWindow, userDataFolder.get(), L"User Data Folder", MB_OK);

```

--------------------------------

### CreateCoreWebView2Controller with environment options and error handling

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2environment

Shows how to create a WebView2 environment with options and handle the completion callback. It retrieves the effective allowed port range for WebRTC UDP, then calls CreateCoreWebView2EnvironmentWithOptions. The callback OnCreateEnvironmentCompleted creates either a composition controller or a regular controller depending on the environment and device availability.

```cpp
    // Get the configured port range
        CHECK_FAILURE(optionsExperimental->GetEffectiveAllowedPortRange(
            COREWEBVIEW2_ALLOWED_PORT_RANGE_SCOPE_WEB_RTC,
            COREWEBVIEW2_TRANSPORT_PROTOCOL_KIND_UDP, &m_udpPortRange.minPort,
            &m_udpPortRange.maxPort));
    }

    HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
        subFolder, m_userDataFolder.c_str(), options.Get(),
        Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
            this, &AppWindow::OnCreateEnvironmentCompleted)
            .Get());
    if (!SUCCEEDED(hr))
    {
        switch (hr)
        {
        case HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND):
        {
            MessageBox(
                m_mainWindow,
                L"Couldn't find Edge WebView2 Runtime. "
                "Do you have a version installed?",
                nullptr, MB_OK);
        }
        break;
        case HRESULT_FROM_WIN32(ERROR_FILE_EXISTS):
        {
            MessageBox(
                m_mainWindow,
                L"User data folder cannot be created because a file with the same name already "
                L"exists.",
                nullptr, MB_OK);
        }
        break;
        case E_ACCESSDENIED:
        {
            MessageBox(
                m_mainWindow, L"Unable to create user data folder, Access Denied.", nullptr,
                MB_OK);
        }
        break;
        case E_FAIL:
        {
            MessageBox(m_mainWindow, L"Edge runtime unable to start", nullptr, MB_OK);
        }
        break;
        default:
        {
            ShowFailure(hr, L"Failed to create WebView2 environment");
        }
        }
    }
}
// This is the callback passed to CreateWebViewEnvironmentWithOptions.
// Here we simply create the WebView.
HRESULT AppWindow::OnCreateEnvironmentCompleted(
    HRESULT result, ICoreWebView2Environment* environment)
{
    if (result != S_OK)
    {
        ShowFailure(result, L"Failed to create environment object.");
        return S_OK;
    }
    m_webViewEnvironment = environment;

    if (m_webviewOption.entry == WebViewCreateEntry::EVER_FROM_CREATE_WITH_OPTION_MENU ||
        m_creationModeId == IDM_CREATION_MODE_HOST_INPUT_PROCESSING
    )
    {
        return CreateControllerWithOptions();
    }
    auto webViewEnvironment3 = m_webViewEnvironment.try_query<ICoreWebView2Environment3>();

    if (webViewEnvironment3 && (m_dcompDevice || m_wincompCompositor))
    {
        CHECK_FAILURE(webViewEnvironment3->CreateCoreWebView2CompositionController(
            m_mainWindow,
            Callback<ICoreWebView2CreateCoreWebView2CompositionControllerCompletedHandler>(
                [this](
                    HRESULT result,
                    ICoreWebView2CompositionController* compositionController) -> HRESULT
                {
                    auto controller =
                        wil::com_ptr<ICoreWebView2CompositionController>(compositionController)
                            .query<ICoreWebView2Controller>();
                    return OnCreateCoreWebView2ControllerCompleted(result, controller.get());
                })
                .Get()));
    }
    else
    {
        CHECK_FAILURE(m_webViewEnvironment->CreateCoreWebView2Controller(
            m_mainWindow, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
                              this, &AppWindow::OnCreateCoreWebView2ControllerCompleted)
                              .Get()));
    }

    return S_OK;
}
```

--------------------------------

### Get OS locale using GetLocaleInfoEx

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimentalcontrolleroptions

Retrieves the OS locale using the GetLocaleInfoEx API. The returned string must be freed with CoTaskMemFree. This example is used to determine the OS region for the LocaleRegion property.

```cpp
int LanguageCodeBufferSize =
    ::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, nullptr, 0);
std::unique_ptr<char[]> buffer(new char[LanguageCodeBufferSize]);
WCHAR* w_language_code = new WCHAR[LanguageCodeBufferSize];
::GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT, LOCALE_SNAME, w_language_code,
                  LanguageCodeBufferSize);
wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize);
delete[] w_language_code;
return buffer;

```

--------------------------------

### Create a WebView2 control and navigate to Bing in HelloWebView.cpp

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/get-started/win32

This code creates a WebView2 environment and controller, sets settings, resizes the control to fill the parent window, and navigates to Bing. It should be pasted between the comment markers in HelloWebView.cpp.

```cpp
// Step 3 - Create a single WebView within the parent window
// Locate the browser and set up the environment for WebView
CreateCoreWebView2EnvironmentWithOptions(nullptr, nullptr, nullptr,
   Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
      [hWnd](HRESULT result, ICoreWebView2Environment* env) -> HRESULT {

         // Create a CoreWebView2Controller and get the associated CoreWebView2 whose parent is the main window hWnd
         env->CreateCoreWebView2Controller(hWnd, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
            [hWnd](HRESULT result, ICoreWebView2Controller* controller) -> HRESULT {
               if (controller != nullptr) {
                  webviewController = controller;
                  webviewController->get_CoreWebView2(&webview);
               }

               // Add a few settings for the webview
               // The demo step is redundant since the values are the default settings
               wil::com_ptr<ICoreWebView2Settings> settings;
               webview->get_Settings(&settings);
               settings->put_IsScriptEnabled(TRUE);
               settings->put_AreDefaultScriptDialogsEnabled(TRUE);
               settings->put_IsWebMessageEnabled(TRUE);

               // Resize WebView to fit the bounds of the parent window
               RECT bounds;
               GetClientRect(hWnd, &bounds);
               webviewController->put_Bounds(bounds);

               // Schedule an async task to navigate to Bing
               webview->Navigate(L"https://www.bing.com/");

               // Step 4 - Navigation events

               // Step 5 - Scripting

               // Step 6 - Communication between host and web content

               return S_OK;
            }).Get());
         return S_OK;
      }).Get());

```

--------------------------------

### Get failure report folder path with ICoreWebView2Environment11

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2environment11

Retrieves the crash dump folder path using the get_FailureReportFolderPath method. The returned string must be freed with CoTaskMemFree. This example is from the C++ reference documentation.

```cpp
        auto environment11 = m_webViewEnvironment.try_query<ICoreWebView2Environment11>();
        CHECK_FEATURE_RETURN(environment11);
        wil::unique_cotaskmem_string failureReportFolder;
        environment11->get_FailureReportFolderPath(&failureReportFolder);
        MessageBox(m_mainWindow, failureReportFolder.get(), L"Failure Report", MB_OK);

```

--------------------------------

### Create AppWindow with window controls overlay enabled

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimental31

Shows how to create an AppWindow with the window controls overlay enabled by setting the useWco option to true. The sampleUri is obtained from the current AppWindow's local path.

```cpp
    std::wstring sampleUri = appWindow->GetLocalUri(c_samplePath);
    WebViewCreateOption options = appWindow->GetWebViewOption();
    options.useWco = true;
    AppWindow* appWindowWco = new AppWindow(appWindow->GetCreationModeId(), options, sampleUri);

```

--------------------------------

### Get OS region with CultureInfo

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controlleroptions

Shows how to retrieve the current thread's culture name to determine the OS region, which can be used with the ScriptLocale property to match the OS region. The example returns the culture name as a string.

```C#
CultureInfo cultureInfo = Thread.CurrentThread.CurrentCulture;
return cultureInfo.Name

```

--------------------------------

### Initialize WebView for visual hosting with DComp or WinComp

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2environment3

Shows how to initialize a WebView for visual hosting using either DComp or WinComp. It closes any existing WebView to apply browser switches, creates the appropriate compositor device, and shows error messages if creation fails. This is part of the CreateCoreWebView2CompositionController documentation.

```cpp
// Create or recreate the WebView and its environment.
void AppWindow::InitializeWebView()
{
    // To ensure browser switches get applied correctly, we need to close
    // the existing WebView. This will result in a new browser process
    // getting created which will apply the browser switches.
    CloseWebView();
    m_dcompDevice = nullptr;
    m_wincompCompositor = nullptr;
    LPCWSTR subFolder = nullptr;

    if (m_creationModeId == IDM_CREATION_MODE_VISUAL_DCOMP ||
        m_creationModeId == IDM_CREATION_MODE_TARGET_DCOMP)
    {
        HRESULT hr = DCompositionCreateDevice2(nullptr, IID_PPV_ARGS(&m_dcompDevice));
        if (!SUCCEEDED(hr))
        {
            MessageBox(
                m_mainWindow,
                L"Attempting to create WebView using DComp Visual is not supported.\r\n"
                "DComp device creation failed.\r\n"
                "Current OS may not support DComp.",
                L"Create with Windowless DComp Visual Failed", MB_OK);
            return;
        }
    }
    else if (m_creationModeId == IDM_CREATION_MODE_VISUAL_WINCOMP)
    {
        HRESULT hr = TryCreateDispatcherQueue();
        if (!SUCCEEDED(hr))
        {
            MessageBox(
                m_mainWindow,
                L"Attempting to create WebView using WinComp Visual is not supported.\r\n"
                "WinComp compositor creation failed.\r\n"
                "Current OS may not support WinComp.",
                L"Create with Windowless WinComp Visual Failed", MB_OK);
            return;
        }
        m_wincompCompositor = winrtComp::Compositor();
    }

```

--------------------------------

### Post JSON web message to dedicated worker

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2dedicatedworker

Example of posting a JSON web message to a dedicated worker from a C++ app, using RunAsync to avoid blocking the event handler and a TextInputDialog to get user input.

```cpp
    // Do not block from event handler
    m_appWindow->RunAsync(
        [this, dedicatedWorker]
        {
            TextInputDialog dialog(
                m_appWindow->GetMainWindow(), L"Post Web Message JSON", L"Web message JSON",
                L"Enter the web message as JSON.",
                L"{\"command\":\"ADD\",\"first\":2,\"second\":3}");
            // Ex: {"command":"ADD","first":2,"second":3}
            if (dialog.confirmed)
            {
                dedicatedWorker->PostWebMessageAsJson(dialog.input.c_str());
            }
        });

```

--------------------------------

### Toggle MemoryUsageTargetLevel in C++

Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2experimental5

C++ example showing how to toggle the memory usage target level between LOW and NORMAL using ICoreWebView2Experimental5. It queries the interface, gets the current level, toggles it, sets it, and shows a message box with the new level.

```cpp
void ViewComponent::ToggleMemoryUsageTargetLevel()
{
    wil::com_ptr<ICoreWebView2Experimental5> webView;
    webView = m_webView.try_query<ICoreWebView2Experimental5>();
    if (!webView)
    {
        ShowFailure(E_NOINTERFACE, L"MemoryUsageTargetLevel API not available");
        return;
    }
    COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL memory_target_level =
        COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_NORMAL;
    CHECK_FAILURE(webView->get_MemoryUsageTargetLevel(&memory_target_level));
    memory_target_level = (memory_target_level == COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW)
                              ? COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_NORMAL
                              : COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW;
    CHECK_FAILURE(webView->put_MemoryUsageTargetLevel(memory_target_level));
    MessageBox(
        nullptr,
        (memory_target_level == COREWEBVIEW2_MEMORY_USAGE_TARGET_LEVEL_LOW)
            ? L"MemoryUsageTargetLevel is set to LOW."
            : L"MemoryUsageTargetLevel is set to NORMAL.",
        L"MemoryUsageTargetLevel change", MB_OK);
}
```
Tokens:
Raw