Merge pull request #705 from MicrosoftDocs/dharshanb/winui3_doc

Documentation for Microsoft.Identity.Client.Desktop.WinUI3 package

Author: DharshanBJ

dotnet/api/overview/index.md

@@ -29,6 +29,8 @@ Check out the [scenario overview](/entra/msal/dotnet/getting-started/scenarios)
 
 [![NuGet badget for Microsoft.Identity.Client.Desktop](https://img.shields.io/nuget/v/Microsoft.Identity.Client.Desktop.svg?style=flat-square&label=Microsoft.Identity.Client.Desktop&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop/)
 
+[![NuGet badge for Microsoft.Identity.Client.Desktop.WinUI3](https://img.shields.io/nuget/v/Microsoft.Identity.Client.Desktop.WinUI3.svg?style=flat-square&label=Microsoft.Identity.Client.Desktop.WinUI3&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop.WinUI3/)
+
 [![NuGet badge for Microsoft.Identity.Client.Extensions.Msal](https://img.shields.io/nuget/v/Microsoft.Identity.Client.Extensions.Msal.svg?style=flat-square&label=Microsoft.Identity.Client.Extensions.Msal&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client.Extensions.Msal/)
 
 ### Higher-Level Libraries

msal-dotnet-articles/advanced/webview2.md

@@ -25,6 +25,13 @@ To use WebView2 in your application, the following requirements must be met:
 - MSAL.NET version 4.28.0 and higher.
 - [WebView2 runtime](/microsoft-edge/webview2/) must be installed on the machine.
 
+### Package Requirements
+
+The package required depends on your target framework and application type:
+
+- **.Net Framework** : Use [`Microsoft.Identity.Client.Desktop`](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop/)
+- **.NET MAUI 9+ and WinAppSDK packaged apps**: Use [`Microsoft.Identity.Client.Desktop.WinUI3`](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop.WinUI3/)
+
 ## Call pattern
 
 When attempting to use the new WebView2 runtime, keep in mind the following required changes:
@@ -50,13 +57,32 @@ var pca = PublicClientApplicationBuilder
 |  .NET Core      | WebView2 with fallback to Legacy<sup>2</sup> | System |
 |  .NET 6<sup>3</sup> | WebView2 with fallback to Legacy<sup>2</sup> | System |
 |  .NET 6 Windows | WebView2, fallback to Legacy | WebView2, embedded |
+|  MAUI 9+/WinAppSDK packaged apps | WebView2 with WinUI 3, no fallback to legacy<sup>4</sup> | WebView2, embedded |
 
 <sup>1</sup> Legacy web view is the default in .NET Framework apps. WebView2 can be used via Microsoft.Identiy.Client.Desktop package.
 <sup>2</sup> .NET Core and .NET 6+ apps can only use web view via Microsoft.Identity.Client package.
 <sup>3</sup> MSAL.NET doesn't provide explicit `net5.0` binaries. .NET 5 apps will follow .NET Core behavior.
+<sup>4</sup> 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](https://www.nuget.org/packages/Microsoft.Identity.Client/) 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`](xref:Microsoft.Identity.Client.MsalClientException).