Xamarin Android Device Manager

The Xamarin Android Device Manager, currently in preview, replaces Google's legacy Device Manager. This guide explains how to use the Xamarin Android Device Manager to create and configure Android Virtual Devices (AVDs) that emulate Android devices. You can use these virtual devices to run and test your app without having to rely on a physical device.

Currently in preview

Overview

After you have verified that hardware acceleration is enabled (as described in Hardware Acceleration), the next step is to create virtual devices to use for testing and debugging your app. You can use the Xamarin Android Device Manager to create virtual devices for use by the Android SDK Emulator.

Why would you want to use the Xamarin Android Device Manager instead of the Google Device Manager? As of Android SDK Tools version 26.0.1, Google has removed support for their UI-based AVD and SDK managers in favor of their new CLI (Command Line Interface) tools. Because of this change, you must use the Xamarin SDK Manager and Xamarin Android Device Manager when you update to Android SDK Tools 26.0.1 and later (which is required for Android 8.0 Oreo development).

This guide explains how to install and use the Xamarin Android Device Manager for Visual Studio on Windows (or for Mac):

Screenshot of the Xamarin Android Device Manager in the Devices tab

You use the Xamarin Android Device Manager to create and configure Android Virtual Devices (AVDs) that you run in the Android SDK Emulator. Each AVD is an emulator configuration that simulates a physical Android device. This makes it possible to run and test your app in a variety of configurations that simulate different physical Android devices. The Xamarin Android Device Manager replaces Google's standalone AVD Manager (which has been deprecated).

In this guide, you will learn how to install and start the Android Device Manager. You will learn how to create, duplicate, customize, and launch virtual devices. This guide also explains how to configure properties for each virtual device (such as API Level, CPU, memory, and resolution), to enable/disable simulated sensors such as accelerometer, GPS, orientation, and light sensor, and to configure the type of hardware acceleration used by that virtual device.

Requirements

To use the Xamarin Android Device Manager, you will need the following:

  • Visual Studio 2017 version 15.5 or later is required. Visual Studio Community edition and higher is supported.

  • Xamarin for Visual Studio version 4.8 or later. For information about updating Xamarin, see Change the Updates Channel.

  • The latest version of the Xamarin Device Manager installer for Windows.

  • Android SDK – The Android SDK must be installed (see Android SDK Setup), and SDK tools version 26.0 must be installed as explained in the next section. Be sure to install the Android SDK at the following location (if it is not already installed): C:\Program Files (x86)\Android\android-sdk.

Installing the Device Manager

Use the following steps to install the Xamarin Android Device Manager:

  1. Download the Xamarin Device Manager installer for Windows.

  2. Double-click Xamarin.DeviceManager.msi and follow the installation directions:

    Xamarin Android Device Manager setup wizard

Launching the Device Manager

In Visual Studio 15.6 Preview 3 and later, you can launch the Xamarin Android Device Manager from the Tools menu. If you are using Visual Studio 15.6 Preview 3 or later, start the Device Manager by clicking Tools > Android Emulator Manager:

Launching from the Tools menu

If you are using an earlier version of Visual Studio, the Xamarin Android Device Manager must be launched from the Windows Start menu.

Xamarin Android Device Manager in the start menu

Right-click Xamarin Android Device Manager and select More > Run as administrator. If you see the following error dialog on launch, see the Troubleshooting section for workaround instructions:

Android SDK instance error

Before you can use the Android Device Manager, you must install Android SDK tools version 26.0.0 or later. If Android SDK tools 26.0.0 or later is not installed, you will see this error dialog on launch:

If you see this error dialog, click OK to open the Android SDK Manager. In the Android SDK Manager, click the Tools tab and install Android SDK Tools 26.0.2 or later, Android SDK Platform-Tools 26.0.0 or later, and Android SDK Build-Tools 26.0.0 (or later):

Installing Android SDK Tools 26.0

After these packages are installed, you can close the SDK Manager and re-launch the Android Device Manager.

Main Screen

When you first launch the Android Device Manager, it presents a screen that displays all currently-configured virtual devices. For each device, the Name, Operating System (Android API Level), CPU, Memory size, and screen resolution are displayed:

List of installed devices and their parameters

When you click a device in the list, the Start button appears on the right. You can click the Start button to launch the emulator with this virtual device:

Start button for a device image

After the emulator starts with the selected virtual device, the Start button changes to a Stop button that you can use to halt the emulator:

Stop button for the running device

New Device

To create a new device, click the New button (located in the upper right-hand area of the screen):

New button for creating a new device

Clicking New launches the New Device screen:

New Device screen of the Device Manager

To configure a new device in the New Device screen, use the following steps:

  1. Select a physical device to emulate by clicking the Device pull-down menu:

    Device pull-down menu

  2. Select a system image to use with this virtual device by clicking the System image pull-down menu. This menu lists the installed system images under Installed. The Download section lists system images that are currently unavailable on your development computer but can be automatically installed:

    System image pull-down menu

  3. Give the device a new name. In the following example, the new device is named Nexus 5 API 25:

    Naming the new device

  4. Edit any properties that you need to modify. To make changes to properties, see Profile Properties later in this guide.

  5. Add any additional properties that you need to explicitly set. The New Device screen lists only the most commonly-modified properties, but you can click the Add Property pull-down menu (in the bottom left-hand corner) to add additional properties. In the following example, the hw.lcd.backlight property is being added:

    Add Property pull-down menu

  6. Click the Create button (lower right-hand corner) to create the new device:

    Create button

  7. You might get a License Acceptance screen. Click Accept if you agree to the license terms:

    License Acceptance screen

  8. The Android Device Manager adds the new device to the list of installed virtual devices with a Creating progress indicator while it creates the device:

    Creation progress Indicator

  9. When the creation process is complete, the new device is shown in the list of installed virtual devices with a Start button, ready to launch:

    Newly-created device ready to launch

Edit Device

To edit an existing virtual device, select the device and click the Edit button (located in the upper right-hand corner of the screen):

Edit button for modifying a new device

Clicking Edit launches the Device Editor for the selected virtual device:

The Device Editor screen lists the properties of the virtual device in the first column, with the corresponding values of each property in the second column. When you select a property, a detailed description of that property is displayed on the right.

For example, in the following screenshot the hw.lcd.density property is being changed from 420 to 240:

Device Editing example

After you have made the necessary configuration changes, click the Save button. For more information about changing virtual device properties, see Profile Properties later in this guide.

Additional Options

Additional options for working with devices are available from the … menu in the upper right-hand corner:

Location of additional options menu

The additional options menu contains the following items:

  • Duplicate and Edit – Duplicates the currently-selected device and opens it in the New Device screen with a different unique name. For example, selecting VisualStudio_android-23_x86_phone and clicking Duplicate and Edit appends a counter to the name:

    Duplicate and Edit screen

  • Reveal in Explorer – Opens a Windows Explorer window in the folder that holds the files for the virtual device. For example, selecting Nexus 5X API 25 and clicking Reveal in Explorer opens a window like the following:

    Results of clicking Reveal in Explorer

  • Factory Reset – Resets the selected device to its default settings, erasing any user changes made to the internal state of the device while it was running. This change does not alter modifications that you make to the virtual device during creation and editing. A dialog box will appear with the reminder that this reset cannot be undone. Click Wipe user data to confirm the reset.

  • Delete – Permanently deletes the selected virtual device. A dialog box will appear with the reminder that deleting a device cannot be undone. Click Delete if you are certain that you want to delete the device.

Profile Properties

The New Device and Device Edit screens list the properties of the virtual device in the first column, with the corresponding values of each property in the second column. When you select a property, a detailed description of that property is displayed on the right. You can modify its hardware profile properties and its AVD properties. Hardware profile properties (such as hw.ramSize and hw.accelerometer) describe the physical characteristics of the emulated device. These characteristics include screen size, the amount of available RAM, whether or not an accelerometer is present. AVD properties specify the operation of the AVD when it runs. For example, AVD properties can be configured to specify how the AVD uses your development computer's graphics card for rendering.

You can change properties by using the following guidelines:

  • To change a boolean property, click the check mark to the right of the boolean property:

    Changing a boolean property

  • To change an enum (enumerated) property, click the down-arrow to the right of the property and choose a new value.

    Changing an enum property

  • To change a string or integer property, double-click the current string or integer setting in the value column and enter a new value.

    Changing an integer property

The following table provides a detailed explanation of the properties listed in the New Device and Device Editor screens:

Property Description Options
abi.type ABI type – Specifies the ABI (application binary interface) type of the emulated device. The x86 option is for the instruction set commonly referred to as "x86" or "IA-32." The x86_64 option is for the 64-bit x86 instruction set. The armeabi-v7a option is for the ARM instruction set with v7-a ARM extensions. The arm64-v8a option is for the ARM instruction set that supports AArch64. x86, x86_64, armeabi-v7a, arm64-v8a
disk.cachePartition Cache partition – Determines whether the emulated device will use a /cache partition on the device. The /cache partition (which is initially empty) is the location where Android stores frequently accessed data and app components. If set to no, the emulator will not use a /cache partition and the other disk.cache settings will be ignored. yes, no
disk.cachePartition.path Cache partition path – Specifies a cache partition image file on your development computer. The emulator will use this file for the /cache partition. Enter an absolute path or a path relative to the emulator's data directory. If not set, the emulator creates an empty temporary file called cache.img on your development computer. If the file does not exist, it is created as an empty file. This option is ignored if disk.cachePartition is set to no.
disk.cachePartition.size Cache partition size – The size of the cache partition file (in megabytes). Normally you do not need to set this option unless the app will be downloading very large files that are larger than the default cache size of 66 megabytes. This option is ignored if disk.cachePartition is set to no.
disk.dataPartition.initPath Initial path to the data partition – Specifies the initial contents of the data partition. After wiping user data, the emulator copies the contents of the specified file to user data (by default, userdata-qemu.img) instead of using userdata.img as the initial version.
disk.dataPartition.path Path to the data partition – Specifies the user data partition file. To configure a persistent user data file, enter a filename and a path on your development computer. If the file doesn't exist, the emulator creates an image from the default file userdata.img, stores it in the filename specified by disk.dataPartition.path, and persists user data to it when the emulator shuts down. If you don't specify a path, the default file is named userdata-qemu.img. The special value causes the emulator to create and use a temporary file. If disk.dataPartition.initPath is set, its content will be copied to the disk.dataPartition.path file at boot-time. Note that this option cannot be left blank.
disk.dataPartition.size Data partition size – Specifies the size of the user data partition in megabytes.
disk.ramdisk.path Ramdisk path – Path to the boot partition (ramdisk) image. The ramdisk image is a subset of the system image that is loaded by the kernel before the system image is mounted. The ramdisk image typically contains boot-time binaries and initialization scripts. If this option is not specified, the default is ramdisk.img in the emulator system directory.
disk.snapStorage.path Snapshot storage path – Path to the snapshot storage file where all snapshots are stored. All snapshots made during execution will be saved to this file. Only snapshots that are saved to this file can be restored during the emulator run. If this option is not specified, the default is snapshots.img in the emulator data directory.
disk.systemPartition.initPath System partition init path – Path to the read-only copy of the system image file; specifically, the partition containing the system libraries and data corresponding to the API level and any variant. If this path is not specified, the default is system.img in the emulator system directory.
disk.systemPartition.path System partition path – Path to the read/write system partition image. If this path is not set, a temporary file will be created and initialized from the contents of the file specified by disk.systemPartition.initPath.
disk.systemPartition.size System partition size – The ideal size of the system partition (in megabytes). The size is ignored if the actual system partition image is larger than this setting; otherwise, it specifies the maximum size that the system partition file can grow to.
hw.accelerometer Accelerometer – Determines whether the emulated device contains an accelerometer sensor. The accelerometer helps the device determine orientation (used for auto-rotation). The accelerometer reports the acceleration of the device along three sensor axes. yes, no
hw.audioInput Audio recording support – Determines whether the emulated device can record audio. yes, no
hw.audioOutput Audio playback support – Determines whether the emulated device can play audio. yes, no
hw.battery Battery support – Determines whether the emulated device can run on a battery. yes, no
hw.camera Camera support – Determines whether the emulated device has a camera. yes, no
hw.camera.back Back-facing camera – Configures the back-facing camera (the lens faces away from the user). If you are using a webcam on your development computer to simulate the back-facing camera on the emulated device, this value must be set to webcamn, where n selects the webcam (if you have only one webcam, choose webcam0). If set to emulated, the emulator simulates the camera in software. To disable the back-facing camera, set this value to none. If you enable the back-facing camera, be sure to also enable hw.camera. emulated, none, webcam0
hw.camera.front Front-facing camera – Configures the front-facing camera (the lens faces towards the user). If you are using a webcam on your development computer to simulate the front-facing camera on the emulated device, this value must be set to webcamn, where n selects the webcam (if you have only one webcam, choose webcam0). If set to emulated, the emulator simulates a camera in software. To disable the front-facing camera, set this value to none. If you enable the front-facing camera, be sure to also enable hw.camera. emulated, none, webcam0
hw.camera.maxHorizontalPixels Maximum horizontal camera pixels – Configures the maximum horizontal resolution of the emulated device's camera (in pixels).
hw.camera.maxVerticalPixels Maximum vertical camera pixels – Configures the maximum vertical resolution of the emulated device's camera (in pixels).
hw.cpu.arch CPU architecture – The CPU architecture to be emulated by the virtual device. If you are using Intel HAXM for hardware acceleration, select x86 for a 32-bit CPU. Select x86_64 for a 64-bit HAXM-accelerated device. (Be sure to install the corresponding Intel x86 system image in the SDK Manager: for example, Intel x86 Atom or Intel x86 Atom_64.) To simulate an ARM CPU, select arm for 32-bit or select arm64 for a 64-bit ARM CPU. Keep in mind that ARM-based virtual devices will run much slower than those that are x86-based because hardware acceleration is not available for ARM. x86, x86_64, arm, arm64
hw.cpu.model CPU model – This value is normally left unset (it will be set to a value that is derived from hw.cpu.arch if it is not explicitly set). However, it can be set to an emulator-specific string for experimental use.
hw.dPad DPad keys – Determines whether the emulated device supports directional pad (DPad) keys. A DPad typically has four keys to indicate directional control. yes, no
hw.gps GPS support – Determines whether the emulated device has a GPS (Global Positioning System) receiver. yes, no
hw.gpu.enabled GPU emulation – Determines whether the emulated device supports GPU emulation. When enabled, GPU emulation uses Open GL for Embedded Systems (OpenGL ES) for rendering both 2D and 3D graphics on the screen, and the associated GPU Emulation Mode setting determines how the GPU emulation is implemented. yes, no
hw.gpu.mode GPU emulation mode – Determines how GPU emulation is implemented by the emulator. If you select auto, the emulator will choose hardware and software acceleration based on your development computer setup. If you select host, the emulator will use your development computer's graphics processor to perform GPU emulation for faster rendering. If your GPU is not compatible with the emulator and you are on Windows, you can try angle instead of host. The angle mode uses DirectX to provide performance similar to host. If you select mesa, the emulator will use the Mesa 3D software library to render graphics. Select mesa if you have problems rendering via your development computer's graphics processor. The swiftshader mode can be used to render graphics in software with slightly less performance than using your computer's GPU. The off option (disable graphics hardware emulation) is a deprecated option that can cause improper rendering for some items and is therefore not recommended. auto, host, mesa, angle, swiftshader, off
hw.gsmModem GSM modem support – Determines whether the emulated device includes a modem that supports the GSM (Global System for Mobile Communications) telephony radio system. yes, no
hw.initialOrientation Initial screen orientation – Configures the initial orientation of the screen on the emulated device (portrait or landscape mode). In portrait mode, the screen is taller than it is wide. In landscape mode, the screen is wider than it is tall. When running the emulated device, you can change the orientation if both portrait and landscape are supported in the device profile. portrait, landscape
hw.keyboard Keyboard support – Determines whether the emulated device supports a QWERTY keyboard. yes, no
hw.keyboard.charmap Keyboard charmap name – The name of the hardware charmap for this device. NOTE: This should always be the default qwerty2 unless you have modified the system image accordingly. This name is sent to the kernel at boot time. Using an incorrect name will result in an unusable virtual device.
hw.keyboard.lid Keyboard lid support – If keyboard support is enabled, this setting determines whether the QWERTY keyboard can be closed/hidden or opened/visible. This setting will be ignored if hw.keyboard is set to false. NOTE: the default value is false if the emulated device targets API level 12 or higher. yes, no
hw.lcd.backlight LCD backlight – Determines whether an LCD backlight is simulated by the emulated device. yes, no
hw.lcd.density LCD density – The density of the emulated LCD display, measured in density-independent pixels, or dp (dp is a virtual pixel unit). When the setting is 160 dp, each dp corresponds to one physical pixel. At runtime, Android uses this value to select and scale the appropriate resources/assets for correct display rendering. 120, 160, 240, 213, 320
hw.lcd.depth LCD color depth – The color bit-depth of the emulated framebuffer that holds the bitmap for driving the LCD display. This value can be 16 bits (65,536 possible colors) or 32 bits (16,777,216 colors plus transparency). The 32-bit setting can make the emulator run slightly slower but with better color accuracy. 16, 32
hw.lcd.height LCD pixel height – The number of pixels that make up the vertical dimension of the emulated LCD display.
hw.lcd.width LCD pixel width – The number of pixels that make up the horizontal dimension of the emulated LCD display.
hw.mainKeys Hardware Back/Home keys – Determines whether the emulated device supports hardware Back and Home navigation buttons. You can set this value to yes if the buttons are implemented only in software. If hw.mainKeys is set to yes, the emulator will not display navigation buttons on the screen, but you can use the emulator side panel to "press" these buttons. yes, no
hw.ramSize Device RAM Size – The amount of physical RAM on the emulated device, in megabytes. The default value will be computed from the screen size or the skin version. Increasing the size can provide faster emulator operation, but at the expense of demanding more resources from your development computer.
hw.screen Touch screen type – Defines the type of screen on the emulated device. A multi-touch screen can track two or more fingers on the touch interface. A touch screen can detect only single-finger touch events. A no-touch screen does not detect touch events. touch, multi-touch, no-touch
hw.sdCard SDCard support – Determines whether the emulated device supports insertion and removal of virtual SD (Secure Digital) cards. The emulator uses mountable disk images stored on your development computer to simulate the partitions of actual SD card devices (see hw.sdCard.path). yes, no
sdcard.size SDCard size – Specifies the size of the virtual SD card file at the location specified by hw.sdCard.path. available on the device (in bytes). If the size is a simple integer, it specifies the size in bytes. You can also specify the size in kilobytes, megabytes, and gigabytes by appending K, M, or G to the size. The minimum size is 9M and the maximum size is 1023G.
hw.sdCard.path SDCard Image Path – Specifies the filename and path to an SD card partition image file on your development computer. For example, this path could be set to C:\sd\sdcard.img on Windows.
hw.sensors.magnetic_field Magnetic Field Sensor – Determines whether the emulated device supports a magnetic field sensor. The magnetic field sensor (also known as magnetometer) reports the ambient geomagnetic field as measured along three sensor axes. Enable this setting for apps that need access to a compass reading. For example, a navigation app might use this sensor to detect which direction the user faces. yes, no
hw.sensors.orientation Orientation Sensor – Determines whether the emulated device provides orientation sensor values. The orientation sensor measures degrees of rotation that a device makes around all three physical axes (x, y, z). Note that the orientation sensor was deprecated as of Android 2.2 (API level 8). yes, no
hw.sensors.proximity Proximity Sensor – Determines whether the emulated device supports a proximity sensor. This sensor measures the proximity of an object relative to the view screen of a device. This sensor is typically used to determine whether a handset is being held up to a person's ear. yes, no
hw.sensors.temperature Temperature Sensor – Determines whether the emulated device supports a temperature sensor. This sensor measures the temperature of the device in degrees Celsius (°C). yes, no
hw.touchScreen Touch-screen support – Determines whether the emulated device supports a touch screen. The touch screen is used for direct manipulation of objects on the screen. yes, no
hw.trackBall Trackball support – Determines whether the emulated device supports a trackball. yes, no
hw.useext4 EXT4 file system support – Determines whether the emulated device uses the Linux EXT4 file system for partitions. Because the file system type is now auto-detected, this option is deprecated and ignored. no
kernel.newDeviceNaming Kernel new device naming – Used to specify whether the kernel requires a new device naming scheme. This is typically used with Linux 3.10 kernels and later. If set to autodetect, the emulator will automatically detect whether the kernel requires a new device naming scheme. autodetect, yes, no
kernel.parameters Kernel parameters – Specifies the string of Linux kernel boot parameters. By default, this setting is left blank.
kernel.path Kernel path – Specifies the path to the Linux kernel. If this path is not specified, the emulator looks in the emulator system directory for kernel-ranchu.
kernel.supportsYaffs2 YAFFS2 partition support – Determines whether the kernel supports YAFFS2 (Yet Another Flash File System 2) partitions. Typically, this applies only to kernels before Linux 3.10. If set to autodetect the emulator will automatically detect whether the kernel can mount YAFFS2 file systems. autodetect, yes, no
skin.name Skin name – The name for an Android emulator skin. A skin is a collection of files that defines the visual and control elements of an emulator display; it describes what the window of the AVD will look like on your development computer. A skin describes screen size, buttons, and the overall design, but it does not affect the operation of your app.
skin.path Skin path – Path to the directory that contains the emulator skin files specified in skin.name This directory contains hardware.ini layout files, and image files for the display elements of the skin.
skin.dynamic Skin dynamic – Whether or not the skin is dynamic. The emulator skin is a dynamic skin if the emulator is to construct a skin of a given size based on a specified width and height. no

For more information about these properties, see Hardware Profile Properties.

Troubleshooting

The following describes common Xamarin Android Device Manager problems and workarounds:

Android SDK in Non-Standard Location

Typically, the Android SDK is installed at the following location:

C:\Program Files (x86)\Android\android-sdk

If the SDK is not installed at this location, you may get this error on launch:

Android SDK instance error

To workaround this problem, do the following:

  1. From the Windows desktop, navigate to C:\Users\username\AppData\Roaming\XamarinDeviceManager:

    Xamarin Device Manager log file location

  2. Double-click to open one of the log files and locate the Config file path. For example:

    Config file path in log file

  3. Navigate to this location and double-click user.config to open it.

  4. In user.config, locate the <UserSettings> element and add an AndroidSdkPath attribute to it. Set this attribute to the path where the Android SDK is installed on your computer and save the file. For example, <UserSettings> would look like the following if the Android SDK was installed at C:\Programs\Android\SDK:

    <UserSettings SdkLibLastWriteTimeUtcTicks="636409365200000000" AndroidSdkPath="C:\Programs\Android\SDK" />
    

After making this change to user.config, you should be able to launch the Xamarin Android Device Manager.

Snapshot disables WiFi on Android Oreo

If you have an AVD configured for Android Oreo with simulated Wi-Fi access, restarting the AVD after a snapshot may cause Wi-Fi access to become disabled.

To work around this problem,

  1. Select the AVD in the Xamarin Device Manager.

  2. From the additional options menu, click Reveal in Explorer.

  3. Navigate to snapshots > default_boot.

  4. Delete the snapshot.pb file:

    Location of the snapshot.pb file

  5. Restart the AVD.

After these changes are made, the AVD will restart in a state that allows Wi-Fi to work again.

Generating a Bug Report

If you find a problem with the Xamarin Android Device Manager that cannot be resolved using the above troubleshooting tips, please file a bug report by right-clicking the title bar and selecting Generate Bug Report:

Location of menu item for filing a bug report

Summary

This guide introduced the Xamarin Android Device Manager available in Visual Studio for Mac and Xamarin for Visual Studio. It explained essential features such as starting and stopping the Android emulator, selecting an Android virtual device (AVD) to run, creating new virtual devices, and how to edit a virtual device. It also explained how to edit profile hardware properties for further customization.