WebView2 development best practices

Every development team follows different practices when building their application. When you build WebView2 applications, there are practices we recommend you follow. This article outlines those recommendations and best practices for you when building production-based WebView2 applications.

While Fixed Version has its use cases for apps that have strict compatibility requirements, we generally recommend using the Evergreen WebView2 Runtime. The Evergreen WebView2 Runtime updates automatically and includes the latest features and security patches available to your WebView2 application. The Evergreen WebView2 Runtime also requires less storage space on the disk.

Ensure the Evergreen WebView2 Runtime is installed before using your WebView2 application. For more information, navigate to Deploying the Evergreen WebView2 Runtime.

Run compatibility tests regularly when using the Evergreen WebView2 Runtime

When using the Evergreen WebView2 Runtime, ensure you run regular compatibility tests. Because the runtime updates automatically, test the web content in the WebView2 control against the non-stable versions of Microsoft Edge to ensure that your WebView2 application performs as expected. This guidance is similar to the guidance that we give to web developers. For more information, navigate to Stay compatible in Evergreen mode.

Ensure APIs are supported by the installed WebView2 Runtime

WebView2 applications need both a Webview2 SDK, and a WebView2 Runtime installed on the computer to run. Both the SDK and the runtime are versioned. Since APIs are continually being added to WebView2, new versions of the runtime are also released to support the new APIs. You'll need to ensure that the APIs used by your WebView2 application are supported by the WebView2 Runtime that's installed on the computer.

If you use the Evergreen WebView2 Runtime, there are some scenarios where the runtime may not be updated to use the latest version. For example, when users don't have internet access, the runtime isn't automatically updated in that environment. Additionally, using some group policies pause WebView2 updates. When you push an update to your WebView2 application, the application may break because it uses newer APIs that are not available in the installed runtime.

To solve this situation, you can test for the availability of the APIs in the installed runtime, before your code calls the API. This test for newer functionality is similar to other web development best practices that detect supported features before using new web APIs. To test for API availability in the installed runtime, use:

  • The queryinterface in C/C++.
  • A try/catch block in .NET or WinUI.

For more information, navigate to Determine WebView2 Runtime requirement.

Update the Fixed Version Runtime

If you use the Fixed Version Runtime, ensure you update your runtime regularly to reduce any potential security risk. When using 3rd-party content in Webview2 applications, always consider the content untrusted. For more information, navigate to Fixed Version distribution mode.

Manage new versions of the runtime

Whenever a new version of the Evergreen WebView2 Runtime is downloaded to the device, running WebView2 applications continue using the previous runtime until the browser process is released. This behavior allows applications to run continuously, and prevents the previous runtime from being deleted. To use the new version of the runtime, you'll need to release all references to the previous WebView2 environment objects or restart your application. The next time you create a new WebView2 environment, it will use the new version.

To take action when a new version is available, such as notifying the user to restart the application, you can use the add_NewBrowserVersionAvailable(Win32) or CoreWebView2Environment.NewBrowserVersionAvailable(.NET) event in your code. If your code handles restarting the application, consider saving the user state before the WebView2 application exits.

Manage the lifetime of the user data folder

WebView2 apps create a user data folder to store data such as cookies, credentials, permissions, and so on. After creating the folder, your app is responsible for managing the lifetime of the user data folder, including clean up when the app is uninstalled. For more information, navigate to Managing the User Data Folder.

For any WebView2 application, ensure you follow our recommended WebView2 security best practices. For more information, navigate to Best practices for developing secure WebView2 applications.