Merge main into live (#3083)

dotnet-policy-service[bot] · Copilot · jfversluis · web-flow · commit 284a46cdd2d5 · 2025-11-12T10:11:30.000+01:00
* Add documentation for Windows ARM device limitations with Android emulators (#3038) * Initial plan * Add Windows ARM device limitations documentation for Android emulators Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> * Document WebView2/BlazorWebView/HybridWebView issues with Program Files installation (#3035) * Initial plan * Add Windows Program Files warning for WebView2/BlazorWebView/HybridWebView Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Extract WebView2 Program Files warning into reusable include snippet Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Fix markdown linting errors in webview2-program-files-warning.md Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> * Document device-independent units and their relationship to platform-specific units (#3036) * Initial plan * Add comprehensive device-independent units documentation Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> * Update docs/user-interface/device-independent-units.md * Fix markdownlint errors: add blank lines before lists and trailing newline Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com> Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com>
diff --git a/docs/TOC.yml b/docs/TOC.yml
@@ -277,6 +277,8 @@
               href: user-interface/controls/index.md
             - name: Align and position controls
               href: user-interface/align-position.md
+            - name: Device-independent units
+              href: user-interface/device-independent-units.md
             - name: Handlers
               items:
                 - name: Overview
diff --git a/docs/android/emulator/hardware-acceleration.md b/docs/android/emulator/hardware-acceleration.md
@@ -31,6 +31,22 @@ For the best experience on Windows, it's recommended you use WHPX to accelerate
 > [!IMPORTANT]
 > A Virtual Machine (VM) accelerated emulator can run inside another VM, including Microsoft Dev Box, provided that nested virtualization is enabled in the VM.
 
+### Windows ARM device limitations
+
+The Android emulator currently requires x64 processor architecture and is **not supported on Windows ARM devices**. This limitation affects devices such as:
+
+- Surface Pro X
+- Surface Pro 9 (5G/ARM variant)
+- Other Windows devices with ARM64 processors (Snapdragon, etc.)
+
+If you're using a Windows ARM device, consider the following alternatives:
+
+- Use a physical Android device for testing via USB debugging. For more information, see [Set up Android device for debugging](~/android/device/setup.md).
+- Use cloud-based testing services or remote development environments with x64 architecture.
+- Consider using Windows Subsystem for Android (WSA) if available, though this has different limitations and capabilities compared to the Android emulator.
+
+For the latest information about Android emulator requirements, see [Android Emulator requirements](https://developer.android.com/studio/run/emulator#requirements) on developer.android.com.
+
 For information about launching and debugging with the Android emulator, see [Debugging on the Android Emulator](debug-on-emulator.md).
 
 ## Accelerate with Hyper-V
diff --git a/docs/android/emulator/troubleshooting.md b/docs/android/emulator/troubleshooting.md
@@ -60,6 +60,7 @@ Performance issues are typically caused by one of the following problems:
 
 - The emulator is running without hardware acceleration.
 - The virtual device running in the emulator using an Arm-based image.
+- You're trying to run the emulator on a Windows ARM device (not supported).
 
 The following sections cover these scenarios in more detail.
 
@@ -71,6 +72,22 @@ When you start a virtual device, and you don't have hardware acceleration enable
 
 To fix this error, follow the troubleshooting steps in the [Hardware acceleration issues](#hardware-acceleration-issues) section.
 
+### Windows ARM device compatibility
+
+The Android emulator is **not supported on Windows ARM devices** and will not run on devices with ARM64 processors such as:
+
+- Surface Pro X
+- Surface Pro 9 (5G/ARM variant)  
+- Other Windows devices with Snapdragon or ARM-based processors
+
+If you're using a Windows ARM device and encounter emulator startup issues or performance problems, this is likely due to the architecture incompatibility. The Android emulator requires x64 processor architecture.
+
+**Alternatives for Windows ARM devices:**
+
+- Use a physical Android device connected via USB for debugging. For setup instructions, see [Set up Android device for debugging](~/android/device/setup.md).
+- Use cloud-based development environments or remote machines with x64 architecture.
+- Consider Windows Subsystem for Android (WSA) if available in your region, though it has different capabilities and limitations.
+
 ## Hardware acceleration issues
 
 When using hardware acceleration, you may run into configuration problems or conflicts with other software on your computer. The first step in troubleshooting is verifying that hardware acceleration is enabled. You can use the Android's SDK to check this setting. Open a command prompt and entering the following command:
diff --git a/docs/fundamentals/gestures/swipe.md b/docs/fundamentals/gestures/swipe.md
@@ -13,7 +13,7 @@ In .NET MAUI, drag gesture recognition is provided by the <xref:Microsoft.Maui.C
 - <xref:Microsoft.Maui.Controls.SwipeGestureRecognizer.Command>, of type <xref:System.Windows.Input.ICommand>, which is executed when a swipe gesture is recognized.
 - <xref:Microsoft.Maui.Controls.SwipeGestureRecognizer.CommandParameter>, of type `object`, which is the parameter that's passed to the `Command`.
 - <xref:Microsoft.Maui.Controls.SwipeGestureRecognizer.Direction>, of type <xref:Microsoft.Maui.SwipeDirection>, which defines the direction
-- <xref:Microsoft.Maui.Controls.SwipeGestureRecognizer.Threshold>, of type `uint`, which represents the minimum swipe distance that must be achieved for a swipe to be recognized, in device-independent units. The default value of this property is 100, which means that any swipes that are less than 100 device-independent units will be ignored.
+- <xref:Microsoft.Maui.Controls.SwipeGestureRecognizer.Threshold>, of type `uint`, which represents the minimum swipe distance that must be achieved for a swipe to be recognized, in device-independent units. The default value of this property is 100, which means that any swipes that are less than 100 device-independent units will be ignored. For more information about device-independent units, see [Device-independent units](../../user-interface/device-independent-units.md).
 
 These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
 
diff --git a/docs/fundamentals/triggers.md b/docs/fundamentals/triggers.md
@@ -370,6 +370,9 @@ The <xref:Microsoft.Maui.Controls.AdaptiveTrigger.MinWindowHeight> and <xref:Mic
 
 In this example, the <xref:Microsoft.Maui.Controls.AdaptiveTrigger> indicates that the corresponding <xref:Microsoft.Maui.Controls.VisualState> will be applied when the current window width is >= 800 device-independent units and the current window height is >= 1200 device-independent units.
 
+> [!NOTE]
+> For more information about device-independent units, see [Device-independent units](../user-interface/device-independent-units.md).
+
 ### Compare state trigger
 
 The <xref:Microsoft.Maui.Controls.CompareStateTrigger> triggers a <xref:Microsoft.Maui.Controls.VisualState> change when a property is equal to a specific value. This trigger has two bindable properties:
diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md
@@ -295,6 +295,9 @@ To download and install an Android emulator on which to run your apps:
 
     For more information about the `avdmanager` command, see [avdmanager](https://developer.android.com/tools/avdmanager) on developer.android.com.
 
+    > [!IMPORTANT]
+    > **Windows ARM devices**: The Android emulator requires x64 architecture and is not supported on Windows ARM devices (such as Surface Pro X). If you're using a Windows ARM device, consider using a physical Android device for testing instead. For more information, see [Set up Android device for debugging](~/android/device/setup.md).
+
 ### iOS and macOS
 
 To set up your Mac for .NET MAUI development on iOS and Mac Catalyst with Visual Studio Code:
diff --git a/docs/user-interface/align-position.md b/docs/user-interface/align-position.md
@@ -59,7 +59,7 @@ The following diagram illustrates the two concepts:
 :::image type="content" source="media/align-position/margin-padding.png" alt-text="Margin and padding concepts." border="false":::
 
 > [!NOTE]
-> `Margin` values are additive. Therefore, if two adjacent elements specify a margin of 20 device-independent units, the distance between the elements will be 40 device-independent units. In addition, margin and padding values are additive when both are applied, in that the distance between an element and any content will be the margin plus padding.
+> `Margin` values are additive. Therefore, if two adjacent elements specify a margin of 20 device-independent units, the distance between the elements will be 40 device-independent units. In addition, margin and padding values are additive when both are applied, in that the distance between an element and any content will be the margin plus padding. For more information about device-independent units, see [Device-independent units](device-independent-units.md).
 
 The `Margin` and `Padding` properties are both of type `Thickness`. There are three possibilities when creating a `Thickness` structure:
 
diff --git a/docs/user-interface/controls/blazorwebview.md b/docs/user-interface/controls/blazorwebview.md
@@ -1,7 +1,7 @@
 ---
 title: "Host a Blazor web app in a .NET MAUI app using BlazorWebView"
 description: "The .NET MAUI BlazorWebView control enables you to host a Blazor web app in your .NET MAUI app, and integrate the app with device features."
-ms.date: 05/13/2025
+ms.date: 09/19/2025
 ---
 
 # Host a Blazor web app in a .NET MAUI app using BlazorWebView
@@ -33,6 +33,8 @@ Browser developer tools can be used to inspect .NET MAUI Blazor apps. For more i
 > [!NOTE]
 > While Visual Studio installs all the required tooling to develop .NET MAUI Blazor apps, end users of .NET MAUI Blazor apps on Windows must install the [WebView2](https://developer.microsoft.com/microsoft-edge/webview2/) runtime.
 
+[!INCLUDE [WebView2 Program Files warning](includes/webview2-program-files-warning.md)]
+
 For more information about Blazor Hybrid apps, see [ASP.NET Core Blazor Hybrid](/aspnet/core/blazor/hybrid).
 
 [!INCLUDE [browser-engines](includes/browser-engines.md)]
diff --git a/docs/user-interface/controls/hybridwebview.md b/docs/user-interface/controls/hybridwebview.md
@@ -2,7 +2,7 @@
 title: HybridWebView
 description: Learn how to use a HybridWebView to host HTML/JS/CSS content in a WebView, and communicate between that content and .NET.
 ms.topic: concept-article
-ms.date: 08/20/2025
+ms.date: 09/19/2025
 monikerRange: ">=net-maui-9.0"
 
 #customer intent: As a developer, I want to host HTML/JS/CSS content in a web view so that I can publish the web app as a mobile app.
@@ -34,6 +34,8 @@ The entire app, including the web content, is packaged and runs locally on a dev
 > [!IMPORTANT]
 > By default, the <xref:Microsoft.Maui.Controls.HybridWebView> control won't be available when full trimming or Native AOT is enabled. To change this behavior, see [Trimming feature switches](~/deployment/trimming.md#trimming-feature-switches).
 
+[!INCLUDE [WebView2 Program Files warning](includes/webview2-program-files-warning.md)]
+
 [!INCLUDE [browser-engines](includes/browser-engines.md)]
 
 ## Create a .NET MAUI HybridWebView app
diff --git a/docs/user-interface/controls/includes/webview2-program-files-warning.md b/docs/user-interface/controls/includes/webview2-program-files-warning.md
@@ -0,0 +1,16 @@
+---
+ms.topic: include
+ms.date: 09/19/2025
+---
+
+> [!WARNING]
+> On Windows, apps using WebView2-based controls that are installed to the `Program Files` directory may fail to render content properly. This occurs because WebView2 attempts to write its cache and user data files to the app's installation directory, which has restricted write permissions in `Program Files`. To resolve this issue, set the `WEBVIEW2_USER_DATA_FOLDER` environment variable before any WebView control is initialized:
+>
+> ```csharp
+> #if WINDOWS
+> var userDataFolder = Path.Combine(FileSystem.AppDataDirectory, "WebView2");
+> Environment.SetEnvironmentVariable("WEBVIEW2_USER_DATA_FOLDER", userDataFolder);
+> #endif
+> ```
+>
+> Place this code in your `App.xaml.cs` constructor or in `Platforms\Windows\App.xaml.cs` before any WebView control is created. This directs WebView2 to use a writable location in the user's AppData directory instead of the restricted Program Files location.
diff --git a/docs/user-interface/controls/webview.md b/docs/user-interface/controls/webview.md
@@ -1,7 +1,7 @@
 ---
 title: "WebView"
 description: "This article explains how to use the .NET MAUI WebView to display remote web pages, local HTML files, and HTML strings."
-ms.date: 08/19/2025
+ms.date: 09/19/2025
 zone_pivot_groups: devices-platforms
 ---
 
@@ -40,6 +40,8 @@ The `Source` property can be set to an `UrlWebViewSource` object or a `HtmlWebVi
 > [!IMPORTANT]
 > A <xref:Microsoft.Maui.Controls.WebView> must specify its <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> and <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest> properties when contained in a <xref:Microsoft.Maui.Controls.HorizontalStackLayout>, <xref:Microsoft.Maui.Controls.StackLayout>, or <xref:Microsoft.Maui.Controls.VerticalStackLayout>. If you fail to specify these properties, the <xref:Microsoft.Maui.Controls.WebView> will not render.
 
+[!INCLUDE [WebView2 Program Files warning](includes/webview2-program-files-warning.md)]
+
 [!INCLUDE [browser-engines](includes/browser-engines.md)]
 
 ## Display a web page
diff --git a/docs/user-interface/device-independent-units.md b/docs/user-interface/device-independent-units.md
@@ -0,0 +1,216 @@
+---
+title: "Device-independent units"
+description: "Learn about device-independent units in .NET MAUI and how they relate to platform-specific unit systems like iOS points and Android density-independent pixels."
+ms.date: 11/11/2025
+---
+
+# Device-independent units
+
+.NET Multi-platform App UI (.NET MAUI) uses **device-independent units** as its universal measurement system across all platforms. This unit system provides a consistent way to specify sizes, positions, margins, padding, and other measurements that automatically adapt to different screen densities and device types.
+
+## What are device-independent units?
+
+Device-independent units (DIUs) are a virtual unit of measurement that represents a consistent physical size across different devices and platforms, regardless of screen density or resolution. One device-independent unit is designed to represent approximately 1/160th of an inch (0.15875 mm) of physical screen space.
+
+The key characteristics of device-independent units include:
+
+- **Platform consistency**: The same value produces visually similar results across iOS, Android, Windows, and macOS
+- **Density independence**: Automatically scales based on screen density to maintain physical size
+- **Developer simplicity**: Use a single unit system instead of platform-specific calculations
+
+## Relationship to platform-specific units
+
+Device-independent units in .NET MAUI correspond directly to the native unit systems used by each platform:
+
+### iOS - Points
+
+On iOS, device-independent units map to **points** (pt):
+
+- 1 device-independent unit = 1 iOS point
+- Points automatically scale based on device pixel density
+- iPhone standard density: 1 point = 1 pixel
+- iPhone Retina displays: 1 point = 2-4 pixels (depending on the device)
+
+### Android - Density-independent pixels
+
+On Android, device-independent units map to **density-independent pixels** (dp or dip):
+
+- 1 device-independent unit = 1 Android dp
+- Based on 160 DPI as the baseline density
+- Automatically scales: `pixels = dp × (dpi / 160)`
+- Common scale factors: 1x (mdpi), 1.5x (hdpi), 2x (xhdpi), 3x (xxhdpi), 4x (xxxhdpi)
+
+### Windows - Device-independent pixels
+
+On Windows, device-independent units map to **device-independent pixels**:
+
+- 1 device-independent unit = 1 Windows device-independent pixel
+- Based on 96 DPI as the baseline
+- Scales with system DPI settings and display scale factor
+
+### macOS - Points
+
+On macOS, device-independent units map to **points**:
+
+- 1 device-independent unit = 1 macOS point
+- Similar to iOS, points scale based on display density
+- Standard displays: 1 point = 1 pixel
+- Retina displays: 1 point = 2 pixels
+
+## Usage in .NET MAUI
+
+Device-independent units are used throughout .NET MAUI for various measurements:
+
+### Layout and positioning
+
+```xaml
+<!-- Margin using device-independent units -->
+<Label Text="Hello World" Margin="10,20,10,5" />
+
+<!-- Width and height using device-independent units -->
+<BoxView WidthRequest="100" HeightRequest="50" />
+
+<!-- Padding using device-independent units -->
+<StackLayout Padding="15">
+    <Label Text="Content with padding" />
+</StackLayout>
+```
+
+### Font sizes
+
+```xaml
+<!-- Font size in device-independent units -->
+<Label Text="Large text" FontSize="24" />
+```
+
+The equivalent C# code:
+
+```csharp
+var label = new Label 
+{ 
+    Text = "Large text", 
+    FontSize = 24  // 24 device-independent units
+};
+```
+
+### Border and stroke widths
+
+```xaml
+<!-- Border width in device-independent units -->
+<Border StrokeThickness="2">
+    <Label Text="Bordered content" />
+</Border>
+```
+
+### Animation and transforms
+
+```csharp
+// Translate by 100 device-independent units
+await image.TranslateTo(100, 100, 1000);
+
+// Scale maintains proportions across devices
+await button.ScaleTo(1.5, 250);
+```
+
+## Practical examples
+
+### Creating consistent spacing
+
+```xaml
+<StackLayout Spacing="16">
+    <Label Text="Item 1" />
+    <Label Text="Item 2" />
+    <Label Text="Item 3" />
+</StackLayout>
+```
+
+This creates 16 device-independent units of space between items, which translates to:
+
+- **iOS**: 16 points
+- **Android**: 16 dp (approximately 1/10th inch on most devices)
+- **Windows**: 16 device-independent pixels
+
+### Responsive design with consistent measurements
+
+```xaml
+<Grid>
+    <Grid.RowDefinitions>
+        <RowDefinition Height="60" />  <!-- Header: 60 DIUs -->
+        <RowDefinition Height="*" />   <!-- Content: Remaining space -->
+        <RowDefinition Height="80" />  <!-- Footer: 80 DIUs -->
+    </Grid.RowDefinitions>
+    
+    <!-- Header with consistent height across platforms -->
+    <Label Grid.Row="0" Text="Header" FontSize="18" />
+    
+    <!-- Main content -->
+    <ScrollView Grid.Row="1">
+        <StackLayout Padding="20">  <!-- 20 DIU padding -->
+            <Label Text="Content" />
+        </StackLayout>
+    </ScrollView>
+    
+    <!-- Footer with consistent height -->
+    <Button Grid.Row="2" Text="Action" Margin="10" />
+</Grid>
+```
+
+## Best practices
+
+### Use appropriate values
+
+Choose device-independent unit values that work well across platforms:
+
+```xaml
+<!-- Good: Common spacing values -->
+<StackLayout Spacing="8">   <!-- Small spacing -->
+<StackLayout Spacing="16">  <!-- Medium spacing -->
+<StackLayout Spacing="24">  <!-- Large spacing -->
+
+<!-- Good: Touch-friendly button sizes -->
+<Button WidthRequest="120" HeightRequest="44" />
+
+<!-- Good: Readable font sizes -->
+<Label FontSize="14" />  <!-- Body text -->
+<Label FontSize="18" />  <!-- Subtitle -->
+<Label FontSize="24" />  <!-- Title -->
+```
+
+### Consider minimum touch targets
+
+Ensure interactive elements meet platform guidelines:
+
+```xaml
+<!-- Minimum recommended button size -->
+<Button Text="Tap me" 
+        WidthRequest="44" 
+        HeightRequest="44" />
+```
+
+This ensures the button meets accessibility guidelines across all platforms (approximately 44 points on iOS, 48 dp on Android).
+
+### Avoid platform-specific conversions
+
+Let .NET MAUI handle the platform-specific scaling automatically:
+
+```csharp
+// Good: Use device-independent units directly
+myView.Margin = new Thickness(16);
+
+// Avoid: Manual platform-specific calculations
+// Don't manually convert between pixels and DIUs
+```
+
+## Related concepts
+
+- **Screen density**: The number of pixels per inch (PPI/DPI) of a display
+- **Scale factor**: The multiplier used to convert device-independent units to physical pixels
+- **Viewport**: The visible area of the app, measured in device-independent units
+- **Physical pixels**: The actual dots of color on the screen hardware
+
+## See also
+
+- [Align and position controls](align-position.md)
+- [Layouts](layouts/index.md)
+- [Fonts](fonts.md)
+- [Unit converters](../platform-integration/device-media/unit-converters.md)
diff --git a/docs/user-interface/fonts.md b/docs/user-interface/fonts.md
diff --git a/docs/user-interface/includes/basic-animation-dotnet10.md b/docs/user-interface/includes/basic-animation-dotnet10.md
