Merge pull request #5738 from MicrosoftDocs/main

Auto Publish – main to live - 2025-08-26 18:21 UTC

Author: learn-build-service-prod[bot]

hub/apps/develop/data-binding/data-binding-in-depth.md

@@ -162,6 +162,11 @@ In the two examples below, the `Button.Content` property is the binding target,
 <Button Content="{Binding ...}" ... />
 ```
 
+If you're using C++/WinRT, then you'll need to add the [**BindableAttribute**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.bindableattribute) attribute to any runtime class that you want to use the [{Binding}](/windows/uwp/xaml-platform/binding-markup-extension) markup extension with.
+
+> [!IMPORTANT]
+> If you're using C++/WinRT, then the [**BindableAttribute**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.bindableattribute) attribute is available with Windows App SDK. Without that attribute, you'll need to implement the [ICustomPropertyProvider](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.icustompropertyprovider) and [ICustomProperty](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.icustomproperty) interfaces in order to be able to use the [{Binding}](/windows/uwp/xaml-platform/binding-markup-extension) markup extension.
+
 ### Binding object declared using {x:Bind}
 
 There's one step we need to do before we author our [{x:Bind}](/windows/uwp/xaml-platform/x-bind-markup-extension) markup. We need to expose our binding source class from the class that represents our page of markup. We do that by adding a property (of type `HostViewModel` in this case) to our `MainWindow` window class.
@@ -234,6 +239,22 @@ Code to support `{x:Bind}` is generated at compile-time in the partial classes f
 
 ### Binding object declared using {Binding}
 
+If you're using C++/WinRT then, to use the [{Binding}](/windows/uwp/xaml-platform/binding-markup-extension) markup extension, you'll need to add the [**BindableAttribute**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.bindableattribute) attribute to any runtime class that you want to bind to. To use [{x:Bind}](/windows/uwp/xaml-platform/x-bind-markup-extension), you don't need that attribute.
+
+```cppwinrt
+// HostViewModel.idl
+// Add this attribute:
+[Microsoft.UI.Xaml.Data.Bindable]
+runtimeclass HostViewModel : Microsoft.UI.Xaml.Data.INotifyPropertyChanged
+{
+    HostViewModel();
+    String NextButtonText;
+}
+```
+
+> [!IMPORTANT]
+> If you're using C++/WinRT, then the [**BindableAttribute**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.bindableattribute) attribute is available with Windows App SDK. Without that attribute, you'll need to implement the [ICustomPropertyProvider](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.icustompropertyprovider) and [ICustomProperty](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.data.icustomproperty) interfaces in order to be able to use the [{Binding}](/windows/uwp/xaml-platform/binding-markup-extension) markup extension.
+
 [{Binding}](/windows/uwp/xaml-platform/binding-markup-extension) assumes, by default, that you're binding to the [**DataContext**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.datacontext) of your markup window. So we'll set the `DataContext` of our window to be an instance of our binding source class (of type `HostViewModel` in this case). The example below shows the markup that declares the binding object. We use the same `Button.Content` binding target we used in the "Binding target" section earlier, and we bind to the `HostViewModel.NextButtonText` property.
 
 ``` xaml

hub/apps/develop/launch/web-to-app-linking.md

@@ -63,6 +63,21 @@ Create a JSON file (without the .json file extension) named **windows-app-web-li
 
 Windows will make an https connection to your website and will look for the corresponding JSON file on your web server.
 
+### Subdomain support
+
+If your app manifest includes both a main domain (for example, `example.com`) and wildcard subdomains (for example, `*.example.com`), you need to add the `allowSubdomains` field to your JSON file to enable subdomain linking. Without this field, links to subdomains will open in the browser instead of your app.
+
+``` JSON
+[{
+  "packageFamilyName" : "Your app's package family name, e.g MyApp_9jmtgj1pbbz6e",
+  "paths" : [ "*" ],
+  "excludePaths" : [ "/news/*", "/blog/*" ],
+  "allowSubdomains" : true
+ }]
+```
+
+When `allowSubdomains` is set to `true`, links to subdomains like `subdomain.example.com/path` will correctly open in your app instead of the browser.
+
 ### Wildcards
 
 The JSON file example above demonstrates the use of wildcards. Wildcards allow you to support a wide variety of links with fewer lines of code. Web-to-app linking supports two types of wildcards in the JSON file:
@@ -90,6 +105,9 @@ If you have two apps that you would like to link to your website, list both of t
  }]
 ```
 
+> [!NOTE]
+> If your apps need to support subdomains, add `"allowSubdomains": true` to each app entry in the JSON file.
+
 To provide the best experience for your users, use exclude paths to make sure that online-only content is excluded from the supported paths in your JSON file.
 
 Exclude paths are checked first and if there is a match the corresponding page will be opened with the browser instead of the designated app. In the example above, ‘/news/\*’ includes any pages under that path while ‘/news\*’ (no forward slash trails 'news') includes any paths under ‘news\*’ such as ‘newslocal/’, ‘newsinternational/’, and so on.

hub/apps/develop/security/smart-cards.md

@@ -84,6 +84,64 @@ Once [RequestVirtualSmartCardCreationAsync](/uwp/api/windows.devices.smartcards.
 
 To authenticate with smart cards or virtual smart cards, your app must provide the behavior to complete challenges between the admin key data stored on the card, and the admin key data maintained by the authentication server or management tool.
 
+### Obtaining the admin key
+
+Before you can perform authentication, you need to obtain the admin key. The source of the admin key depends on your scenario:
+
+- **For virtual smart cards you created**: Use the same admin key that was generated during card creation (as shown in the "Create a virtual smart card" section above). You should store this key securely for later authentication use.
+- **For existing physical or virtual smart cards**: The admin key is typically provided by your organization's IT department, card management system, or the service that issued the card.
+- **For development/testing**: You can generate a test admin key using [CryptographicBuffer.GenerateRandom](/uwp/api/windows.security.cryptography.cryptographicbuffer.generaterandom) as shown in the virtual card creation example below.
+
+```cs
+// Example: Store the admin key from virtual card creation for later use
+IBuffer adminkey = CryptographicBuffer.GenerateRandom(24);
+
+// Store this key securely in your app (e.g., in app settings, secure storage, etc.)
+// You'll need this same key for authentication operations
+
+SmartCardProvisioning provisioning = await
+     SmartCardProvisioning.RequestVirtualSmartCardCreationAsync(
+          "Card friendly name",
+          adminkey,
+          pinPolicy);
+
+// Save the adminkey for future authentication
+SaveAdminKeySecurely(adminkey);
+```
+
+### Example admin key management methods
+
+Here are example methods you might implement to securely store and retrieve admin keys:
+
+```cs
+// Example implementation for storing admin key securely
+private void SaveAdminKeySecurely(IBuffer adminKey)
+{
+    // Convert to string for storage (consider encryption for production)
+    string adminKeyString = CryptographicBuffer.EncodeToBase64String(adminKey);
+    
+    // Store in app settings (consider using Windows Credential Manager for production)
+    ApplicationData.Current.LocalSettings.Values["SmartCardAdminKey"] = adminKeyString;
+}
+
+// Example implementation for retrieving stored admin key
+private IBuffer GetStoredAdminKey()
+{
+    // Retrieve from app settings
+    string adminKeyString = ApplicationData.Current.LocalSettings.Values["SmartCardAdminKey"] as string;
+    
+    if (string.IsNullOrEmpty(adminKeyString))
+    {
+        throw new InvalidOperationException("Admin key not found. Ensure the smart card was created by this app or the admin key was provided by your IT department.");
+    }
+    
+    // Convert back to IBuffer
+    return CryptographicBuffer.DecodeFromBase64String(adminKeyString);
+}
+```
+
+### Authentication algorithm
+
 The following code shows how to support smart card authentication for services or modification of physical or virtual card details. If the data generated using the admin key on the card ("challenge") is the same as the admin key data provided by the server or management tool ("adminkey"), authentication is successful.
 
 ```cs
@@ -123,9 +181,14 @@ SmartCardProvisioning provisioning =
 SmartCardChallengeContext context =
     await provisioning.GetChallengeContextAsync();
 
+// Use the admin key that was either:
+// 1. Generated during virtual card creation, or
+// 2. Provided by your IT department/card management system
+IBuffer adminKey = GetStoredAdminKey(); // Your method to retrieve the stored admin key
+
 IBuffer response = ChallengeResponseAlgorithm.CalculateResponse(
     context.Challenge,
-    rootPage.AdminKey);
+    adminKey);
 
 verifyResult = await context.VerifyResponseAsync(response);
 ```
@@ -163,10 +226,13 @@ bool result = await provisioning.RequestPinResetAsync(
 
         try
         {
+            // Use the same admin key from card creation or your secure storage
+            IBuffer adminKey = GetStoredAdminKey(); // Your method to retrieve the stored admin key
+            
             IBuffer response =
                 ChallengeResponseAlgorithm.CalculateResponse(
                     request.Challenge,
-                    rootPage.AdminKey);
+                    adminKey);
             request.SetResponse(response);
         }
         finally

hub/apps/windows-app-sdk/applifecycle/applifecycle-instancing.md

@@ -336,56 +336,47 @@ Unlike the UWP version of `RedirectActivationTo`, the Windows App SDK's implemen
 
 ### Redirection without blocking
 
-Most apps will want to redirect as early as possible, before doing unnecessary initialization work. For some app types, initialization logic runs on an STA thread, which must not be blocked. AppInstance.RedirectActivationToAsync method is asynchronous, and the calling app must wait for the method to complete, otherwise the redirection will fail. However, waiting on an async call will block the STA. In these situations, call RedirectActivationToAsync in another thread, and set an event when the call completes. Then wait on that event using non-blocking APIs such as CoWaitForMultipleObjects. Here’s a C# sample for a WPF app.
+Most apps will want to redirect as early as possible, before doing unnecessary initialization work. For some app types, initialization logic runs on an STA thread, which must not be blocked. **AppInstance.RedirectActivationToAsync** method is asynchronous, and the calling app must wait for the method to complete, otherwise the redirection will fail. However, waiting on an async call will block the STA. In these situations, call **RedirectActivationToAsync** in another thread, and set an event when the call completes. Then wait on that event using non-blocking APIs.
+
+The following is a C# sample for a WPF app:
 
 ```csharp
-private static bool DecideRedirection()
+private static bool DecideRedirection(string key)
 {
     bool isRedirect = false;
 
     // Find out what kind of activation this is.
     AppActivationArguments args = AppInstance.GetCurrent().GetActivatedEventArgs();
     ExtendedActivationKind kind = args.Kind;
-    if (kind == ExtendedActivationKind.File)
+
+    if (kind == ExtendedActivationKind.Launch)
     {
         try
         {
-            // This is a file activation: here we'll get the file information,
-            // and register the file name as our instance key.
-            if (args.Data is IFileActivatedEventArgs fileArgs)
+            AppInstance keyInstance = AppInstance.FindOrRegisterForKey(key);
+
+            // If we successfully registered the key, we must be the
+            // only instance running that was activated for this key.
+            if (keyInstance.IsCurrent)
+            {
+                // Hook up the Activated event, to allow for this instance of the app
+                // getting reactivated as a result of multi-instance redirection.
+                keyInstance.Activated += OnKeyInstanceActivated;
+            }
+            else
             {
-                IStorageItem file = fileArgs.Files[0];
-                AppInstance keyInstance = AppInstance.FindOrRegisterForKey(file.Name);
+                isRedirect = true;
 
-                // If we successfully registered the file name, we must be the
-                // only instance running that was activated for this file.
-                if (keyInstance.IsCurrent)
+                // Ensure we don't block the STA, by doing the redirect operation
+                // in another thread, and using an event to signal when it has completed.
+                var redirectSemaphore = new Semaphore(0, 1);
+                Task.Run(() =>
                 {
-                    // Hook up the Activated event, to allow for this instance of the app
-                    // getting reactivated as a result of multi-instance redirection.
-                    keyInstance.Activated += OnActivated;
-                }
-                else
-                {
-                    isRedirect = true;
-
-                    // Ensure we don't block the STA, by doing the redirect operation
-                    // in another thread, and using an event to signal when it has completed.
-                    redirectEventHandle = CreateEvent(IntPtr.Zero, true, false, null);
-                    if (redirectEventHandle != IntPtr.Zero)
-                    {
-                        Task.Run(() =>
-                        {
-                            keyInstance.RedirectActivationToAsync(args).AsTask().Wait();
-                            SetEvent(redirectEventHandle);
-                        });
-                        uint CWMO_DEFAULT = 0;
-                        uint INFINITE = 0xFFFFFFFF;
-                        _ = CoWaitForMultipleObjects(
-                            CWMO_DEFAULT, INFINITE, 1, 
-                            new IntPtr[] { redirectEventHandle }, out uint handleIndex);
-                    }
-                }
+                    keyInstance.RedirectActivationToAsync(args).AsTask().Wait();
+                    redirectSemaphore.Release();
+                });
+                redirectSemaphore.WaitOne();
+
             }
         }
         catch (Exception ex)

hub/powertoys/hosts-file-editor.md

@@ -45,8 +45,8 @@ From the Settings menu, the following options can be configured:
 | :--- | :--- |
 | Open as administrator | Open as administrator to be able edit the hosts file. If disabled, the editor is run in read-only mode. Hosts File Editor is started as administrator by default. |
 | Show a warning at startup | Warns that editing hosts can change DNS names resolution. Enabled by default. |
-| Placement of additional content | Default value is **Top**. If **Bottom** is selected, the file header is moved below hosts settings to the bottom. |
-| Consider loopback addresses as duplicates | Loopback addresses (like 127.0.0.1 and ::1) are considered as duplicates. |
+| Placement of additional content | Determines where new host entries are added in the hosts file. Default value is **Top** (new entries are added near the top of the file after the default Windows header comments). If **Bottom** is selected, new entries are added at the end of the file. This affects the organization of your hosts file and can impact which entries take precedence if there are conflicts. |
+| Consider loopback addresses as duplicates | When enabled, multiple loopback addresses (127.0.0.1, ::1) pointing to the same hostname are treated as duplicates. This prevents adding redundant entries and helps avoid conflicts. When disabled, you can add multiple loopback entries for the same hostname, which may be useful for testing different network configurations but could lead to unexpected behavior. |
 | Encoding | Default value is **UTF-8**. If **UTF-8 with BOM** is selected, a Byte Order Mark (BOM) is included at the start of the file. |
 
 ## Troubleshooting