GrabDuck

Android SDK Emulator - Xamarin

:

This guide discusses how to configure and use the Google Android SDK Emulator with Visual Studio.

This guide explains how to prepare the Google Android SDK Android emulator and how to use it to test/debug Xamarin.Android apps. An emulator can be run in a variety of configurations to simulate different devices. Each one of these configurations is created as a virtual device. In this guide, you will learn how to configure one or more virtual devices, how to launch the emulator from Visual Studio, and how to troubleshoot common problems. In addition, this guide explains how to accelerate the Android emulator for improved performance.

ℹ️

Note: As of Android SDK Tools version 26.0.1 and later, Google has removed support for existing AVD/SDK managers in favor of their new CLI (Command Line Interface) tools. Because of this deprecation change, the Xamarin Android SDK Manager is used instead of the Google Android SDK Manager for Android Tools 26.0.1 and later. (For more information, see Using the SDK Manager). You can continue to run the original Google Android Emulator by remaining on Android SDK Tools version 25.2.5 or lower.

Because the Android SDK Emulator is prohibitively slow without hardware acceleration, Intel's HAXM (Hardware Accelerated Execution Manager) is often installed as a way to drastically improve the performance of the Android SDK Emulator. HAXM is automatically installed by Visual Studio 2015 and later as part of Xamarin.Android installation.

HAXM is a hardware-assisted virtualization engine (hypervisor) that uses Intel Virtualization Technology (VT) to speed up Android app emulation on a host machine. In combination with Android x86 emulator images provided by Intel and the official Android SDK Manager, HAXM allows for faster Android emulation on VT-enabled systems. If you are developing on a machine with an Intel CPU that has VT capabilities, you can take advantage of HAXM to greatly speed up the Android SDK Emulator (if you're not sure whether your CPU supports VT, see this article).

The Android SDK Emulator automatically makes use of HAXM when it is available. When you select an x86-based virtual device (as described later in this guide), that virtual device will use HAXM for hardware acceleration. Before you use the Android SDK Emulator for the first time, it's a good idea to verify that hardware acceleration is enabled.

You can check to see if HAXM is available by viewing the Starting Android Emulator window while the emulator starts. To start the Android SDK Emulator, do the following:

  1. Launch the Android Emulator Manager by clicking Tools > Android > Android Emulator Manager:

    Android Emulator Manager menu item location

  2. Select an x86 image (for example, VisualStudio_android-23_x86_phone), click Start, then click Launch:

    Starting the Android SDK Emulator with a default virtual device image

  3. Watch for the Starting Android Emulator dialog window while the emulator starts up. If HAXM is installed, you will see the message, HAX is working and emulator runs in fast virt mode as shown in this screenshot:

    HAXM is shown as available in the Starting Android Emulator dialog

    If you do not see this message, then HAXM is probably not installed. To install HAXM, see Install HAXM later in this guide.

ℹ️

Note: You cannot run HAXM on a virtual machine. Also, you cannot use HAXM while Hyper-V is enabled. For more about the limitations and potential problems with HAXM, see HAXM Virtualization Conflicts.

  1. Launch the Android Emulator Manager by clicking Tools > Google Emulator Manager:

    Android Emulator Manager menu item location

  2. Select the x86 image (for example, Android_Accelerated_x86), click Start, then click Launch:

    Starting the Android SDK Emulator with a default virtual device image

  3. Watch for the Starting Android Emulator dialog window while the emulator starts up. If HAXM is installed, you will see the message, HAX is working and emulator runs in fast virt mode as shown in this screenshot:

    HAXM is shown as available in the Starting Android Emulator dialog

    If you do not see this message, then HAXM is probably not installed. To install HAXM, see Install HAXM later in this guide.

After you have verified that hardware acceleration is enabled, the next step is to determine which virtual device to use for testing and debugging your app.

Visual Studio includes pre-configured virtual devices that appear in the device drop-down menu. For example, in the following Visual Studio 2017 screenshot, several pre-configured virtual devices are available:

  • VisualStudio_android-23_arm_phone

  • VisualStudio_android-23_arm_tablet

  • VisualStudio_android-23_x86_phone

  • VisualStudio_android-23_x86_tablet

Virtual devices

Typically, you would select the VisualStudio_android-23_x86_phone virtual device to test and debug a phone app. If one of these pre-configured virtual devices meets your requirements (i.e., matches your app's target API level), skip to Launching the Emulator to begin running your app in the emulator. (If you are not yet familiar with Android API levels, see Understanding Android API Levels.)

If your Xamarin.Android project is using a Target Framework level that is incompatible with the available virtual devices, the drop-down menu will list the unusable virtual devices under Unsupported Devices. For example, the following project has a Target Framework set to Android 7.1 Nougat (API 25), which is incompatible with the Android 6.0 virtual devices that are provided by default:

Incompatible virtual device

You can click Change Minimum Android Target to change the project's Minimum Android Version so that it matches the API level of the available virtual devices. Alternately, you can use the Android Emulator Manager to create new virtual devices that support your target API level as explained later in Configuring Virtual Devices. Before you can configure virtual devices for a new API level, you must first install the corresponding system images for that API level – this is explained in the next section.

Visual Studio for Mac includes pre-configured virtual devices that appear in the device drop-down menu. For example, in the following screenshot, two pre-configured virtual devices are available:

  • Android_Accelerated_x86

  • Android_ARMv7a

Virtual devices

Typically, you would select the Android_Accelerated_x86 virtual device to test and debug a phone app. If this pre-configured virtual device meets your requirements (i.e., matches your app's target API level), skip to Launching the Emulator to begin running your app in the emulator. (If you are not yet familiar with Android API levels, see Understanding Android API Levels.)

Depending on which Android API level(s) you want to target, you must download and install API level-specific system images that are used by the Android SDK emulator. For each Android API level, there are a set of x86 system images that you will need to download and install for creating virtual devices.

To install the necessary system images, start the Android SDK Manager (Tools > Android > Android SDK Manager) and scroll to the API level(s) you want to support. For each API level, enable the check mark next to the following system images:

To install the necessary system images, start the Android SDK Manager (Tools > SDK Manager) and scroll to the API level(s) you want to support. For each API level, enable the check mark next to the following system images:

  • Intel x86 Atom System Image
  • Google APIs Intel x86 Atom System Image

The latter system image adds Google APIs (for example, Google Maps APIs) to the virtual device.

In the following screenshot, Intel x86 Atom images will be installed so that virtual devices running Android 6.0 can be created:

Selecting Android 6.0 x86 system images for the Android Emulator

Selecting Android 6.0 x86 system images for the Android Emulator

If you are developing 64-bit apps, install the following system images instead:

  • Intel x86 Atom_64 System Image
  • Google APIs Intel x86 Atom_64 System Image

You can use these 64-bit system images to run 32-bit apps; however, the 32-bit Intel x86 Atom System Image runs slightly faster in the Android SDK emulator.

If you are developing apps for Android Wear, install the following system images:

  • Android Wear Intel x86 Atom System Image
  • Google APIs Intel x86 Atom System Image

After these system images are installed, you can create x86-based Android virtual devices by selecting the appropriate API level and CPU/ABI choices during virtual device configuration (this is described next).

Virtual devices are configured via the Android Emulator Manager (also referred to as the Android Virtual Device Manager or AVD Manager). To launch the Android Emulator Manager from Visual Studio, click the Android Emulator Manager icon in the toolbar:

AVD icon location

You can also launch the Android Emulator Manager from the menu bar by selecting Tools > Android > Android Emulator Manager:

Android Emulator Manager menu item location

The Android Virtual Device (AVD) Manager dialog displays the list of existing Android virtual devices:

Android Virtual Device Manager

Virtual devices are configured via the Android Emulator Manager (also referred to as the Android Virtual Device Manager or AVD Manager).

You can launch the Android Emulator Manager from the menu bar by selecting Tools > Google Emulator Manager:

Android Emulator Manager menu item location

The Android Virtual Device (AVD) Manager dialog displays the list of existing Android virtual devices:

Android Virtual Device Manager

You can create new virtual device images with different device characteristics and API levels – the next section explains how to create custom device definitions and virtual devices.

Creating a Custom Device Definition

To create a custom device definition, click Create... in the Android Virtual Device (AVD) Manager. This opens the Create new Android Virtual Device (AVD) dialog:

Custom device definition based on Nexus 6

Custom device definition based on Nexus 6

In this dialog, configure the following options:

  • AVD Name – The unique name for your device definition. In the example screenshot above, the name is set to MyNexus. Note that the AVD name cannot contain spaces – the OK button will be disabled if you try to use spaces in the AVD name.

  • Device – Select the hardware profile that you want to emulate (for example, Nexus 5 or Nexus 6).

  • Target – Select the Android API level for the virtual device. This setting should be greater than or equal to the Minimum Android Version of your app.

  • CPU/ABI – Select Google APIs Intel Atom (x86) so that Google APIs will be available in your device definition.

  • Skin – Select the appearance of the virtual device. In the example screenshot above, the HVGA skin is selected (the the emulator screenshot at the end of this article is an example of the HVGA skin).

  • Memory Options – Typically, the default RAM setting is too high and, on Windows, causes the warning: emulating RAM greater than 768M may fail. For most users, we recommend setting RAM to 768MB (as shown in the above screenshot). Large RAM values can slow down the emulator.

  • Use Host GPU – This option causes the emulator to use the host computer's Graphical Processing Unit (GPU) to perform graphics operations. We recommend that you enable this option to further increase the performance of the emulator. For more information on the Emulation Options section, see What are Snapshot and Use Host GPU emulation options used for?

The remaining options can be left at their default settings. When you are ready, click OK to create the new virtual device. The results of the new virtual device configuration are detailed in the next dialog:

Results dialog after creating a new AVD

Results dialog after creating a new AVD

For a detailed explanation of the configuration properties listed in this dialog, see Hardware Profile Properties. After you click OK, the new device configuration is displayed in the list of existing Android virtual devices. In the following screenshot, MyNexus was added to the list:

MyNexus added to the device list

MyNexus added to the device list

The new custom virtual device is also added to the device pull-down menu:

MyNexus added to the device pull-down menu

MyNexus added to the device pull-down menu

Cloning a Device Definition

It is possible to select an existing device definition and clone it to create a new custom device definition. This is a good strategy to use when there is an existing device definition that needs only a few minor adjustments to meet your needs. The Device Definitions tab in the Android Virtual Device (AVD) Manager lists all available device definitions:

List of available device definitions

List of available device definitions

The pre-configured devices in this list cannot be modified – only user-created virtual devices can be edited. It is possible to derive a new device definition from a pre-configured device definition by selecting the device definition and clicking Clone. For example, selecting the Nexus 5 definition and clicking Clone presents the following dialog:

Clone device dialog

Clone device dialog

In the next screenshot, the name is changed to Nexus 5 Custom and the device parameters are modified to create a new custom device definition:

Custom Nexus 5 AVD

Custom Nexus 5 AVD

Clicking Clone Device creates the new device definition, which now appears in the Device Definitions list:

Nexus 5 Custom appears as new User device definition

Nexus 5 Custom appears as new User device definition

Note that each user-created device definition is displayed with a green icon, as shown above. This new device definition can be used to create a new AVD by selecting the definition and clicking Create AVD. This displays the Create new Android Virtual Device (AVD) dialog. In the following example, the name AVD_for_Nexus_5_Custom was automatically generated for new virtual device:

Create AVD from Nexus 5 Custom User device definition

Create AVD from Nexus 5 Custom User device definition

After OK is clicked, the custom device configuration is displayed in the list of existing Android virtual devices. In addition, it is added to the device pull-down menu:

New custom AVD added to device drop-down menu

New custom AVD added to device drop-down menu

Near the top of the IDE, there is a drop-down menu that can be used to select Debug or Release mode. Choosing Debug attaches the debugger to the application process running inside the emulator.

After you have chosen a virtual device from the device drop-down menu, select either Debug or Release mode, then click the Play button to run the application:

Debug and Release modes, Play button

Debug and Release modes, Play button

After the Android emulator starts, Xamarin.Android will deploy the app to the emulator. The emulator runs the app with the configured virtual device image. An example screenshot of the Android SDK Emulator is displayed below (the emulator is running a blank app called MyApp):

Emulator running a blank app

The emulator may be left running; it is not necessary to shut it down and restart it each time the app is run. The first time a Xamarin.Android app is run in the emulator, the Xamarin.Android shared runtime for the targetted API level is installed, followed by the application. The runtime installation may take a few moments, so please be patient. Installation of the runtime takes place only when the first Xamarin.Android app is deployed to the emulator – subsequent deployments are faster because only the app is copied to the emulator.

For additional information about using the Android SDK Emulator, see the following topics:

The most common problems with the Android SDK Emulator (and solutions) are described below.

Deployment Issues

If you get an error about a failure to install the APK on the emulator or a failure to run the Android Debug Bridge (adb), verify that the Android SDK can connect to your emulator. To do this, use the following steps:

  1. Launch the emulator from the Android Virtual Device (AVD) Manager (select your virtual device and click Start).

  2. Open a Command Prompt and go to the folder where adb is installed. For example, on Windows, this might be at: C:\Program Files (x86)\Android\android-sdk\platform-tools\adb.exe.

  3. Type the following command:

    adb devices
  4. If the emulator is accessible from the Android SDK, the emulator should appear in the list of attached devices. For example:

    List of devices attached
    emulator-5554   device
  5. If the emulator does not appear in this list, start the Android SDK Manager, apply all updates, then try launching the emulator again.

HAXM Issues

If the Android SDK Emulator does not start properly, this is usually caused by problems with HAXM. HAXM issues are often the result of conflicts with other virtualization technologies, incorrect BIOS settings, or an out of date HAXM driver.

Install HAXM

If the emulator still does not start, HAXM may have to be installed (or updated) manually. HAXM install packages for both Windows and macOS are available from the Intel Hardware Accelerated Execution Manager page. Use the following steps to download and install HAXM manually:

  1. From the Intel website, download the latest HAXM virtualization engine.

  2. Install the HAXM engine. Accept the default values in the installer dialogs:

    Intel Hardware Accelerated Execution Manager Setup window

    To use HAXM, be sure that your virtual device is using an x86 system image as described earlier in Configuring Virtual Devices.

HAXM Virtualization Conflicts

HAXM can conflict with other technologies that use virtualization, such as Hyper-V, Windows Device Guard, and some antivirus software:

  • Hyper-V – If you are using Windows with Hyper-V enabled, disable it, reboot, and retry the Android SDK Emulator. You can disable Hyper-V from the Control Panel. To do this, go to Programs and Features and click Turn Windows features on or off. Uncheck Hyper-V and restart the computer:

    Disabling Hyper-V in the Windows Features dialog

    Alternately, you can use the following Powershell cmdlet to disable Hyper-V:

    Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-Hypervisor

    Intel HAXM and Microsoft Hyper-V cannot both be active at the same time. Unfortunately, there is currently no way to switch between between Hyper-V and HAXM without restarting your computer. If you want to use the Visual Studio 2015 Emulator for Android (which depends on Hyper-V), you will be unable to use the Android SDK Emulator without rebooting. One way to use both Hyper-V and HAXM is to create a multi-boot setup as explained in Creating a no hypervisor boot entry.

  • Device Guard – Device Guard and Credential Guard can prevent Hyper-V from being disabled on Windows machines. This is often a problem for domain-joined machines that are configured and controlled by an owning organization. On Windows 10, use the following steps to see if Device Guard is running:

    1. In Windows Search, type System info to start the System Information app.

    2. In the System Summary, look to see if Device Guard Virtualization based security is present and is in the Running state.

    3. If Device Guard is enabled, see this article to learn how to disable Device Guard and/or Credential Guard. If the policies of your domained-joined machine prevent you from disabling Device Guard or Credential Guard, you may have to use a non-domain machine in order to use HAXM.

  • Antivirus Software – If you are running antivirus software that uses hardware-assisted virtualization (such as Avast), disable or uninstall this software, reboot, and retry the Android SDK Emulator.

Incorrect BIOS Settings

If you are using HAXM on a Windows PC, HAXM will not work unless virtualization technology (Intel VT-x) is enabled in the BIOS. If VT-x is disabled, you will get an error similiar to the following when you attempt to start the Android SDK Emulator:

This computer meets the requirements for HAXM, but Intel Virtualization Technology (VT-x) is not turned on.

To correct this error, boot the computer into the BIOS, enable both VT-x and SLAT (Second Level Address Translation), then restart the computer back into Windows.

This guide explained the process for configuring the Google Android SDK emulator to run and test an application. It explained how to accelerate the emulator with HAXM, it introduced the pre-configured virtual devices, described how to create custom Android Virtual Devices (AVDs), and provided the steps for deploying an application to the emulator from Visual Studio. In addition, the Troubleshooting guide explained the most common problems and solutions.