VISUAL STUDIO   Windows Mac

Part 2 - Configuration and Use

How to configure and launch the Android SDK Emulator

PDF for offline use

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-09

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. You can use a pre-configured virtual device, clone an existing configuration (and modify it), or create a custom device definition. When your virtual device is created and configured, you can launch it and begin using it for testing.

Contents

Using a Pre-Configured Virtual Device

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.)

Installing System Images

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).

Configuring Virtual Devices

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

Launching the Emulator

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 more information about using the Android SDK Emulator, see the following Android Developer topics:

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.