docs: Add msal window changes to docs

unoplatform · Jan 10, 2025 · 878741a · 878741a
1 parent 1710def
commit 878741a
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 4 deletions.
diff --git a/doc/Learn/Authentication/HowTo-MsalAuthentication.md b/doc/Learn/Authentication/HowTo-MsalAuthentication.md
@@ -56,18 +56,21 @@ uid: Uno.Extensions.Authentication.HowToMsalAuthentication
     protected override void OnLaunched(LaunchActivatedEventArgs args)
     {
         var builder = this.CreateBuilder(args)
-            .Configure(host =>
+            .Configure((host, window) =>
             {
                 host
                 .UseAuthentication(builder =>
                 {
-                    builder.AddMsal();
+                    builder.AddMsal(window);
                 });
             });
         ...
     }
     ```
 
+> [!IMPORTANT]
+> The `AddMsal()` method requires a `Window` instance, which the `MsalAuthenticationProvider` uses to set up the authentication dialog. You can access the `Window` instance through the `Configure()` method overload that provides it.
+
 - The `IAuthenticationBuilder` is responsible for managing the lifecycle of the associated provider that was built.
 
 - Because it is configured to use MSAL, the user will eventually be prompted to sign in to their Microsoft account when they use your application. `MsalAuthenticationProvider` will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.
@@ -95,12 +98,12 @@ uid: Uno.Extensions.Authentication.HowToMsalAuthentication
     protected override void OnLaunched(LaunchActivatedEventArgs args)
     {
         var builder = this.CreateBuilder(args)
-            .Configure(host =>
+            .Configure((host, window) =>
             {
                 host
                 .UseAuthentication(builder =>
                 {
-                    builder.AddMsal(msal =>
+                    builder.AddMsal(window, msal =>
                         msal
                         .Builder(msalBuilder => 
                             msalBuilder.WithClientId("161a9fb5-3b16-487a-81a2-ac45dcc0ad3b"))

diff --git a/doc/Learn/UpdatingExtensions.md b/doc/Learn/UpdatingExtensions.md
@@ -0,0 +1,31 @@
+---
+uid: Uno.Extensions.Migration
+---
+
+# Upgrading Extensions Version
+
+## Upgrading to Extensions 5.2
+
+### MSAL Authentication
+
+When upgrading to Uno.Extensions 5.2 or later, you must update your MSAL authentication setup in the host configuration. The `AddMsal()` method now includes an additional parameter to specify the `Window` instance used by the `MsalAuthenticationProvider` to configure the authentication dialog. You can obtain the `Window` instance from the `Configure()` method overload that provides it:
+
+```diff
+private IHost Host { get; set; }
+
+protected override void OnLaunched(LaunchActivatedEventArgs args)
+{
+    var builder = this.CreateBuilder(args)
+-       .Configure(host =>
++       .Configure((host, window) =>
+        {
+            host
+            .UseAuthentication(builder =>
+            {
+-               builder.AddMsal();
++               builder.AddMsal(window);
+            });
+        });
+    ...
+}
+```
diff --git a/doc/toc.yml b/doc/toc.yml
@@ -5,6 +5,8 @@
       href: xref:Uno.Extensions.Overview
     - name: "How-To: Getting Started"
       href: xref:Uno.Extensions.HowToGettingStarted
+    - name: "Upgrading Extensions Version"
+      href: xref:Uno.Extensions.Migration
     - name: Authentication
       href: Learn/Authentication/toc.yml
       topicHref: xref:Uno.Extensions.Authentication.Overview