Merge main to live (#1970)

* Fix globbing pattern. (#1957) * Add constraints warning (#1960) * Add constraints warning. * Fix xrefs. * Edits. * Edits. * Emulator can be ran in VMs (#1962) * Emulator can be ran in VMs. * Edit. * Android emulator overview (#1964) * Android emulator overview. * Fix link. * Add icons to table. * Fix linting error. * Remove stray link. * Edit. * Resize images * Edit. * Edits. * Add .NET 8 VSMac enablement instructions to installation doc (#1966) * Add .NET 8 VSMac enablement instructions to installation doc * Edit. * Update for .NET (#1967) * Clearly specify the build action (#1968) * Clearly specify the build action. * Fix typo. * UWP manual upgrade (#1849) * Draft of UWP manual upgrade; used generative ai. * address: lint, comments, links * spaces * Make the PR build successfully. * Try again. * Initial edits. * Update uwp-projects.md to address comments * rm long link * Edits. * Major edits. * Fix warning. * More edits. * Edits. * Edits. * Edits. * Final edits. * Remove next steps section. --------- Co-authored-by: Diana Soltani <[email protected]> Co-authored-by: David Britch <[email protected]> --------- Co-authored-by: Diana Soltani <[email protected]> Co-authored-by: Diana Soltani <[email protected]>
dotnet · Dec 20, 2023 · b1ac4d0 · b1ac4d0
1 parent 633f1e0
commit b1ac4d0
Show file tree

Hide file tree

Showing 32 changed files with 299 additions and 58 deletions.
diff --git a/docs/TOC.yml b/docs/TOC.yml
@@ -17,6 +17,8 @@
           items:
             - name: Emulator
               items:
+                - name: Overview
+                  href: android/emulator/index.md
                 - name: How to enable hardware acceleration
                   href: android/emulator/hardware-acceleration.md
                 - name: Manage and create virtual devices
@@ -67,6 +69,8 @@
                   href: migration/apple-projects.md
                 - name: iOS binding project migration
                   href: migration/ios-binding-projects.md
+            - name: UWP project migration
+              href: migration/uwp-projects.md
             - name: Xamarin.Essentials migration
               href: migration/native-essentials.md
         - name: Xamarin.Forms projects
@@ -823,6 +827,6 @@
         - name: MVVM community toolkit features
           href: /dotnet/architecture/maui/mvvm-community-toolkit-features?toc=/dotnet/maui/toc.json&bc=/dotnet/maui/breadcrumb/toc.json
         - name: Unit testing
-          href: /dotnet/architecture/maui/unit-testing?toc=/dotnet/maui/toc.json&bc=/dotnet/maui/breadcrumb/toc.json                  
+          href: /dotnet/architecture/maui/unit-testing?toc=/dotnet/maui/toc.json&bc=/dotnet/maui/breadcrumb/toc.json
     - name: Troubleshooting
       href: troubleshooting.md
diff --git a/docs/android/device/setup.md b/docs/android/device/setup.md
@@ -6,7 +6,7 @@ ms.date: 02/23/2022
 
 # Set up Android device for debugging
 
-While the [Android emulator](../emulator/debug-on-emulator.md) is a great way to rapidly develop and test your app, you'll want to test your apps on a real Android device. To run on a device, you'll need to enable developer mode on the device and connect it to your computer.
+While the [Android emulator](../emulator/debug-on-emulator.md) is a great way to rapidly develop and test your app, you'll want to test your apps on a real Android device. To run on a device, you'll need to enable developer mode on the device and connect it to your computer. For more information, see [Run apps on a hardware device](https://developer.android.com/studio/run/device) on developer.android.com.
 
 > [!IMPORTANT]
 > The steps in this article are written generically, to work on as many devices as possible. If you can't find these settings on your device, consult your device manufacturer's documentation.
@@ -53,6 +53,9 @@ It's possible to debug an android device over WiFi, without keeping the device p
 
 By default, the Android Debug Bridge (adb) is configured to communicate with an Android device via USB. It's possible to reconfigure it to use TCP/IP instead of USB. To do this, both the device and the computer must be on the same WiFi network.
 
+> [!NOTE]
+> The Google USB driver is required to perform `adb` debugging on Windows with Google devices. For more information, see [Get the Google USB Driver](https://developer.android.com/studio/run/win-usb) on developer.android.com. Windows drivers for all other devices are provided by the respective hardware manufacturer. For more information, see [Install OEM USB drivers](https://developer.android.com/studio/run/oem-usb) on developer.android.com.
+
 First, enable Wireless debugging on your Android device:
 
 01. Follow the steps in the [Enable developer mode on the device](#enable-developer-mode-on-the-device) section.
@@ -100,3 +103,7 @@ Next, use adb to connect to your device, first through a USB connection:
     ```command
     adb devices
     ```
+
+## Configure on-device developer options
+
+The Settings app on Android includes a screen called **Developer options** where you can configure system behaviors that help you profile and debug your app performance. For more information, see [Configure on-device developer options](https://developer.android.com/studio/debug/dev-options) on developer.android.com.
diff --git a/docs/android/emulator/device-manager.md b/docs/android/emulator/device-manager.md
@@ -7,7 +7,7 @@ no-loc: ["user.config"]
 
 # Managing virtual devices with the Android Device Manager
 
-This article explains how to use the Android Device Manager to create and configure Android Virtual Devices (AVDs) that emulate physical Android devices. You can use these virtual devices to run and test your app without having to rely on a physical device.
+This article explains how to use the Android Device Manager to create and configure Android Virtual Devices (AVDs) that emulate physical Android devices. You can use these virtual devices to run and test your app without having to rely on a physical device. For more information about Android virtual devices, see [Create and manage virtual devices](https://developer.android.com/studio/run/managing-avds) on developer.android.com.
 
 > [!IMPORTANT]
 > Enable hardware acceleration for the Android devices. For more information, see [Hardware Acceleration for Emulator Performance](hardware-acceleration.md).

diff --git a/docs/android/emulator/device-properties.md b/docs/android/emulator/device-properties.md
@@ -6,7 +6,7 @@ ms.date: 02/23/2022
 
 # Editing Android virtual device properties
 
-This article explains how to use the Android Device Manager (AVD) to edit the profile properties of an Android virtual device.
+This article explains how to use the Android Device Manager (AVD) to edit the profile properties of an Android virtual device. For more information about Android virtual devices, see [Create and manage virtual devices](https://developer.android.com/studio/run/managing-avds) on developer.android.com.
 
 <!-- ::: zone pivot="windows" -->
 

diff --git a/docs/android/emulator/hardware-acceleration.md b/docs/android/emulator/hardware-acceleration.md
@@ -7,7 +7,7 @@ ms.topic: how-to
 
 # How to enable hardware acceleration with Android emulators (Hyper-V & AEHD)
 
-With Visual Studio, you can easily test and debug your .NET MAUI app for Android in emulators for situations where an Android device isn't available. However, if hardware acceleration isn't available or enabled, the emulator will run very slowly. You can significantly improve the performance of the emulator by enabling hardware acceleration and using *x86-64* or *x86* virtual device images.
+With Visual Studio, you can easily test and debug your .NET MAUI app for Android in emulators for situations where an Android device isn't available. However, if hardware acceleration isn't available or enabled, the emulator will run very slowly. You can significantly improve the performance of the emulator by enabling hardware acceleration and by using virtual device images that are appropriate for your processor architecture. For more information, see [Configure hardware acceleration for the Android Emulator](https://developer.android.com/studio/run/emulator-acceleration) on developer.android.com
 
 ## Accelerate Android emulators on Windows
 
@@ -25,7 +25,7 @@ For the best experience on Windows, it's recommended you use WHPX to accelerate
 - The emulator is running a system image created for an **x86-64** or **x86**-based virtual device.
 
 > [!IMPORTANT]
-> You can't run a VM-accelerated emulator inside another VM, such as a VM hosted by VirtualBox, VMware, or Docker (unless using WSL2). You must run the Android emulator [directly on your system hardware](https://developer.android.com/studio/run/emulator-acceleration.html#extensions).
+> A Virtual Machine (VM) accelerated emulator can run inside another VM, including Microsoft Dev Box, provided that nested virtualization is enabled in the VM.
 
 For information about launching and debugging with the Android emulator, see [Debugging on the Android Emulator](debug-on-emulator.md).
 
@@ -62,6 +62,9 @@ If all listed Hyper-V requirements have a value of **Yes**, then your computer c
 
 If the Hyper-V result indicates that a hypervisor is currently running, Hyper-V is already enabled.
 
+> [!IMPORTANT]
+> If Windows is running inside a virtual machine, nested virtualization must be enabled in the host hypervisor.
+
 ### Enable Hyper-V acceleration in Windows
 
 If your computer meets the above criteria, use the following steps to accelerate the Android emulator with Hyper-V:
@@ -202,7 +205,3 @@ For help with troubleshooting hardware acceleration issues, see the Android emul
 
 ::: zone-end
 -->
-
-## See also
-
-- [Configure hardware acceleration for the Android Emulator](https://developer.android.com/studio/run/emulator-acceleration) on developer.android.com
diff --git a/docs/android/emulator/index.md b/docs/android/emulator/index.md
@@ -0,0 +1,80 @@
+---
+title: "Android emulator"
+description: "Learn how to get started with the Android emulator, so that you can test your apps on a variety of devices and Android API levels without requiring physical devices."
+ms.date: 12/18/2023
+---
+
+# Android emulator
+
+The Android emulator, which is produced by Google, simulates Android devices on your computer so that you can test your apps on a variety of devices and Android API levels, without needing to have each physical device. When you deploy and test your app on the emulator you select a pre-configured or custom virtual device, known as an Android Virtual Device (AVD) that simulates a physical Android device such as a Pixel phone. Alternatively, you can deploy your app to a physical device. For more information about deploying your app to physical device, see [Set up Android device for debugging](~/android/device/setup.md).
+
+The Android emulator is installed by Visual Studio, and an AVD created, when you build your first .NET Multi-platform App UI (.NET MAUI) app for Android. For more information, see [Build your first app](~/get-started/first-app.md?pivots=devices-android).
+
+If hardware acceleration isn't available or enabled, the emulator will run very slowly. You can significantly improve the performance of the emulator by enabling hardware acceleration and by using virtual device images that are appropriate for your processor architecture. For more information, see [How to enable hardware acceleration with Android emulators](hardware-acceleration.md).
+
+Physical Android devices are emulated by AVDs, which specify the Android version and hardware characteristics of the simulated device. To test an app, create AVDs that model each device your app is designed to run on. Each AVD runs as an independent device with its own storage for user data, and SD card data. The emulator stores the user data, and SD card data in a folder specific to the AVD. When you launch the emulator, it loads the user data and SD card data from the AVD folder. For information about managing virtual devices, see [Managing virtual devices with the Android Device Manager](device-manager.md). For information about editing the configuration of a virtual device, see [Editing Android virtual device properties](device-properties.md).
+
+After you've created an AVD you can launch the emulator and debug an app in it. For more information, see [Debug on the Android emulator](debug-on-emulator.md). Once an app is installed on an AVD, you can run it from the device as you would run any app on a device.
+
+For information about diagnosing emulator issues, see [Android emulator troubleshooting](troubleshooting.md).
+
+## Use the emulator
+
+When the Android emulator is running, you use your computer mouse pointer to mimic your finger on the touch screen, select menu items and input fields, and click buttons and controls. You can type in the emulator by using your computer keyboard or by using the onscreen keyboard that appears in the emulator.
+
+Common actions can be performed in the emulator via its panel on the right hand side:
+
+| Action | Icon | Description |
+| ------ | ---- | ----------- |
+| Close | :::image type="content" source="media/close.png" alt-text="Screenshot of the close button in the Android emulator window." border="false"::: | Close the emulator. |
+| Minimize | :::image type="content" source="media/minimize.png" alt-text="Screenshot of the minimize button in the Android emulator window." border="false"::: | Minimize the emulator window. |
+| Power | :::image type="content" source="media/power.png" alt-text="Screenshot of the power button in the Android emulator window." border="false"::: | Click to turn the screen on/off. Click and hold to turn the device on/off. |
+| Volume up | :::image type="content" source="media/volume-up.png" alt-text="Screenshot of the volume up button in the Android emulator window." border="false"::: | Increase the volume. |
+| Volume down | :::image type="content" source="media/volume-down.png" alt-text="Screenshot of the volume down button in the Android emulator window." border="false"::: | Decrease the volume. |
+| Rotate left | :::image type="content" source="media/rotate-left.png" alt-text="Screenshot of the rotate left button in the Android emulator window." border="false"::: | Rotate the screen 90 degrees left. |
+| Rotate right | :::image type="content" source="media/rotate-right.png" alt-text="Screenshot of the rotate right button in the Android emulator window." border="false"::: | Rotate the screen 90 degrees right. |
+| Take screenshot | :::image type="content" source="media/screenshot.png" alt-text="Screenshot of the screenshot button in the Android emulator window." border="false"::: | Click to take a screenshot of the device. |
+| Enter zoom mode | :::image type="content" source="media/zoom.png" alt-text="Screenshot of the zoom button in the Android emulator window." border="false"::: | Click to change the cursor to the zoom icon. Click again to exit zoom mode. |
+| Back | :::image type="content" source="media/back.png" alt-text="Screenshot of the back button in the Android emulator window." border="false"::: | Return to the previous screen, or close an options menu, dialog, onscreen keyboard, or Notifications panel. |
+| Home | :::image type="content" source="media/home.png" alt-text="Screenshot of the home button in the Android emulator window." border="false"::: | Return to the Home screen. |
+| Overview (recent apps) | :::image type="content" source="media/overview.png" alt-text="Screenshot of the overview button in the Android emulator window." border="false"::: | Click to open a list of apps you've worked with recently. To open an app, tap its thumbnail.  |
+| More | :::image type="content" source="media/more.png" alt-text="Screenshot of the more button in the Android emulator window." border="false"::: | Click for more features and settings. |
+
+The following gestures can be simulated in the emulator:
+
+| Gesture | Description |
+| ------- | ----------- |
+| Tap | Press and release the primary mouse button. |
+| Double tap | Double-click and then release the primary mouse button. |
+| Drag | Press and hold the primary mouse button, move the item, and then release. |
+| Touch and hold | Press the primary mouse button, hold, and release. |
+| Pinch | Press the CTRL key on Windows, or the Command key on macOS, to display a pinch gesture multi-touch interface. The mouse acts as the first finger, which can be moved by dragging the cursor. The second finger is across from the anchor point. Pressing the left mouse button simulates touching both points, and releasing simulates removing both points. |
+| Swipe | Press and hold the primary mouse button, swipe, and then release. |
+| Vertical swipe | Open a vertical menu on the screen and use the mouse scroll wheel to scroll through the menu items. |
+
+## Advanced emulator scenarios
+
+You might want to test your app on a virtual device using more than just basic touch gestures. For example, you might want to simulate different network conditions. The following table lists where to find more information about advanced Android emulator scenarios:
+
+| Scenarios | More information |
+| ------- | ---------------- |
+| Use the camera | [Camera support](https://developer.android.com/studio/run/emulator-use-camera) on developer.android.com |
+| Install and add files | [Install and add files](https://developer.android.com/studio/run/emulator-install-add-files) on developer.android.com |
+| Use Wi-Fi | [Wi-Fi](https://developer.android.com/studio/run/emulator-wifi) on developer.android.com |
+| Use extended controls | [Extended controls, settings, and help](https://developer.android.com/studio/run/emulator-extended-controls) on developer.android.com |
+| Use snapshots | [Snapshots](https://developer.android.com/studio/run/emulator-snapshots) on developer.android.com |
+| Use the emulator from the command line | [Start the emulator from the command line](https://developer.android.com/studio/run/emulator-commandline) on developer.android.com |
+| Send console commands | [Send emulator console commands](https://developer.android.com/studio/run/emulator-console) on developer.android.com |
+| Set up networking | [Set up Android Emulator networking](https://developer.android.com/studio/run/emulator-networking) on developer.android.com |
+| Configure hardware acceleration | [Configure hardware acceleration for the Android Emulator](https://developer.android.com/studio/run/emulator-acceleration) on developer.android.com |
+| Android emulator tools | [Comparison of Android Emulator tools](https://developer.android.com/studio/run/emulator-comparison) on developer.android.com |
+
+## Limitations
+
+The Android Emulator doesn't include virtual hardware for the following:
+
+- Bluetooth
+- NFC
+- SD card insert/eject
+- Device-attached headphones
+- USB
diff --git a/docs/android/emulator/media/back.png b/docs/android/emulator/media/back.png
diff --git a/docs/android/emulator/media/close.png b/docs/android/emulator/media/close.png
diff --git a/docs/android/emulator/media/home.png b/docs/android/emulator/media/home.png
diff --git a/docs/android/emulator/media/minimize.png b/docs/android/emulator/media/minimize.png
diff --git a/docs/android/emulator/media/more.png b/docs/android/emulator/media/more.png
diff --git a/docs/android/emulator/media/overview.png b/docs/android/emulator/media/overview.png
diff --git a/docs/android/emulator/media/power.png b/docs/android/emulator/media/power.png
diff --git a/docs/android/emulator/media/rotate-left.png b/docs/android/emulator/media/rotate-left.png
diff --git a/docs/android/emulator/media/rotate-right.png b/docs/android/emulator/media/rotate-right.png
diff --git a/docs/android/emulator/media/screenshot.png b/docs/android/emulator/media/screenshot.png
diff --git a/docs/android/emulator/media/volume-down.png b/docs/android/emulator/media/volume-down.png
diff --git a/docs/android/emulator/media/volume-up.png b/docs/android/emulator/media/volume-up.png
diff --git a/docs/android/emulator/media/zoom.png b/docs/android/emulator/media/zoom.png
diff --git a/docs/android/emulator/troubleshooting.md b/docs/android/emulator/troubleshooting.md
@@ -7,7 +7,7 @@ ms.date: 10/14/2022
 
 # Android emulator troubleshooting
 
-This article describes the most common warning messages and issues that occur while configuring and running the Android Emulator. Also, it describes solutions for resolving these errors and various troubleshooting tips to help you diagnose emulator problems.
+This article describes the most common warning messages and issues that occur while configuring and running the Android Emulator. Also, it describes solutions for resolving these errors and various troubleshooting tips to help you diagnose emulator problems. For more information, see [Troubleshoot known issues with Android Emulator](https://developer.android.com/studio/run/emulator-troubleshooting) on developer.android.com.
 
 ## Deployment issues on Windows
 

diff --git a/docs/get-started/first-app.md b/docs/get-started/first-app.md
@@ -212,8 +212,7 @@ If your app fails to compile, review [Troubleshooting known issues](../troublesh
 
 - Visual Studio 2022 for Mac 17.6 with the .NET, .NET MAUI, Android, and iOS workloads installed. For more information, see [Installation](installation.md?tabs=vsmac).
 
-> [!IMPORTANT]
-> To use Visual Studio for Mac with .NET 8, enable the **Visual Studio > Preferences > Other > Preview Features > Use the .NET 8 SDK if installed (requires restart)** checkbox.
+[!INCLUDE [Enable .NET 8 support in Visual Studio Mac](includes/vsmac-net8.md)]
 
 ## Create an app
 

diff --git a/docs/get-started/includes/vsmac-net8.md b/docs/get-started/includes/vsmac-net8.md
@@ -0,0 +1,7 @@
+---
+ms.topic: include
+ms.date: 12/19/2023
+---
+
+> [!IMPORTANT]
+> To use Visual Studio for Mac with .NET 8, enable the **Visual Studio > Preferences > Other > Preview Features > Use the .NET 8 SDK if installed (requires restart)** checkbox.
diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md
@@ -86,6 +86,8 @@ To build, sign, and deploy .NET MAUI apps for iOS or macOS, you'll also need:
 1. Install .NET 8 through the [standalone installer](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).
 1. After .NET 8 has finished installing, run `dotnet workload install maui` in a terminal.
 
+    [!INCLUDE [Enable .NET 8 support in Visual Studio Mac](includes/vsmac-net8.md)]
+
 If you have network trouble while installing in a corporate environment, review the [installing behind a firewall or proxy](#installation-behind-a-firewall-or-proxy-server) instructions.
 
 ## Installation behind a firewall or proxy server