Изменить

Поделиться через

Using WebView2 with MSAL.NET

WebView2 is a modern embedded browser runtime based on Microsoft Edge, capable of performing Windows Hello authentication, log in with FIDO keys, and more. This browser replaces the legacy web view based on Internet Explorer.

Availability

To use WebView2 in your application, the following requirements must be met:

  • Windows 10 OS or newer (supported by the WebView2 runtime).
  • MSAL.NET version 4.28.0 and higher.
  • WebView2 runtime must be installed on the machine.

Package Requirements

The package required depends on your target framework and application type:

Call pattern

When attempting to use the new WebView2 runtime, keep in mind the following required changes:

var pca = PublicClientApplicationBuilder
        .Create("0f887a65-3c78-4b16-9529-6209b8741c26")
        .WithWindowsEmbeddedBrowserSupport()
        .Build();

Important

WebView2 is not supported for Microsoft Entra ID (formerly known as Azure Active Directory) authorities. Using .WithWindowsEmbeddedBrowserSupport() in that context is always going to default to the legacy web view, regardless of the setting provided during the instantiation of the public client application. This is caused by stability bugs identified during MSAL development. For B2C and Active Directory Federation Services (ADFS) authorities, WebView2 will be shown.

Behaviour

Framework Embedded web view Default web view
.NET Framework Legacy, WebView2 with fallback to Legacy1 Legacy embedded
.NET Core WebView2 with fallback to Legacy2 System
.NET 63 WebView2 with fallback to Legacy2 System
.NET 6 Windows WebView2, fallback to Legacy WebView2, embedded
MAUI 9+/WinAppSDK packaged apps WebView2 with WinUI 3, no fallback to legacy4 WebView2, embedded

1 Legacy web view is the default in .NET Framework apps. WebView2 can be used via Microsoft.Identiy.Client.Desktop package. 2 .NET Core and .NET 6+ apps can only use web view via Microsoft.Identity.Client package. 3 MSAL.NET doesn't provide explicit net5.0 binaries. .NET 5 apps will follow .NET Core behavior. 4 Use WinUI 3-based WebView2 implementation with B2C/ADFS support for MAUI 9+ and WinAppSDK packaged applications.

When to Use

Use Microsoft.Identity.Client.Desktop.WinUI3 when:

  • Building .NET MAUI 9+ applications
  • Developing WinAppSDK packaged applications
  • Requiring reliable B2C or ADFS authentication flows
  • Requiring WinRT framework compatibility

Use Microsoft.Identity.Client.Desktop in all other scenarios.

Troubleshooting

Package Selection Issues

If you encounter issues with WebView2 integration, ensure you're using the correct package for your target framework:

  • Error: Could not load file or assembly 'Microsoft.Web.WebView2.Core' or WinRT-related exceptions in .NET MAUI 9+ or WinAppSDK packaged apps
  • Solution: Switch from Microsoft.Identity.Client.Desktop to Microsoft.Identity.Client.Desktop.WinUI3 for MAUI 9+ and WinAppSDK packaged applications.

WebView2 on .NET Framework

There's a scenario when an app that targets .NET Framework and references the MSAL.NET NuGet package tries to acquire token interactively with WebView2 embedded browser, WebView2 will throw exceptions. These errors can be System.BadImageFormatException: An attempt was made to load a program with an incorrect format. or System.DllNotFoundException: 'Unable to load DLL 'WebView2Loader.dll': The specified module could not be found. As of MSAL.NET 4.32.0 these exceptions are wrapped into MsalClientException.

This occurs due to an existing bug in the WebView2 SDK on the .NET Framework platform because the library cannot figure out the target platform of its dependencies. One workaround is to add a <PlatformTarget> with values AnyCPU, x86, or x64 to your application project file. x86 or x64 have to match the target framework of the WebView2 installed on the machine. Another workaround is to add <PlatformTarget>AnyCPU</PlatformTarget> in your app's project file and also directly reference the WebView2 NuGet package. For details, see issues #2482, #730.

  • Last updated on