Hello, Android: Quickstart

In this two-part guide, you will build your first Xamarin.Android application (using Visual Studio or Visual Studio for Mac) and develop an understanding of the fundamentals of Android application development with Xamarin. Along the way, you will be introduced to the tools, concepts, and steps required to build and deploy a Xamarin.Android application.

Hello, Android Quickstart

In this walkthrough, you will create an application that translates an alphanumeric phone number (entered by the user) into a numeric phone number and display the numeric phone number to the user. The final application looks like this:

Screenshot of app when it is complete


To follow along with this walkthrough, you will need the following:

  • Windows 7 or later (Windows 10 is recommended).

  • Visual Studio 2017 Community, Professional, or Enterprise (version 15.8 or later).

This walkthrough assumes that the latest version of Xamarin.Android is installed and running on your platform of choice. For a guide to installing Xamarin.Android, refer to the Xamarin.Android Installation guides.

Configuring Emulators

If you are using the Android emulator, we recommend that you configure the emulator to use hardware acceleration. Instructions for configuring hardware acceleration are available in Hardware Acceleration for Emulator Performance.


Start Visual Studio. Click File > New > Project to create a new project.

In the New Project dialog, click the Android App template. Name the new project Phoneword and click OK:

New project is Phoneword

In the New Android App dialog, click Blank App and click OK to create the new project:

Select the Blank App template

Creating the Layout

After the new project is created, expand the Resources folder and then the layout folder in the Solution Explorer. Double-click activity_main.axml to open it in the Android Designer. This is the layout file for the app's screen:

Open activity main.axml

From the Toolbox (the area on the left), enter text into the search field and drag a Text (Large) widget onto the design surface (the area in the center):

Add large text widget

With the Text (Large) control selected on the design surface, use the Properties pane to change the Text property of the Text (Large) widget to Enter a Phoneword::

Set large text properties

Drag a Plain Text widget from the Toolbox to the design surface and place it underneath the Text (Large) widget. Placement of the widget will not occur until you move the mouse pointer to a place in the layout that can accept the widget. In the screenshots below, the widget cannot be placed (as seen on the left) until the mouse pointer is moved just below the previous TextView (as shown on the right):

Mouse indicates where widget can be placed

When the Plain Text (an EditText widget) is placed correctly, it will appear as illustrated in the following screenshot:

Add plain text widget

With the Plain Text widget selected on the design surface, use the Properties pane to change the Id property of the Plain Text widget to @+id/PhoneNumberText and change the Text property to 1-855-XAMARIN:

Set plain text properties

Drag a Button from the Toolbox to the design surface and place it underneath the Plain Text widget:

Drag translate button to the design

With the Button selected on the design surface, use the Properties pane to change its Text property to Translate and its Id property to @+id/TranslateButton:

Set translate button properties

Drag a TextView from the Toolbox to the design surface and place it under the Button widget. Change the Text property of the TextView to an empty string and set its Id property to @+id/TranslatedPhoneword:

Set the properties on the text view.

Save your work by pressing CTRL+S.

Writing Translation Code

The next step is to add some code to translate phone numbers from alphanumeric to numeric. Add a new file to the project by right-clicking the Phoneword project in the Solution Explorer pane and choosing Add > New Item... as shown below:

Add new item

In the Add New Item dialog, select Visual C# > Code > Code File and name the new code file PhoneTranslator.cs:

Add PhoneTranslator.cs

This creates a new empty C# class. Insert the following code into this file:

using System.Text;
using System;
namespace Core
    public static class PhonewordTranslator
        public static string ToNumber(string raw)
            if (string.IsNullOrWhiteSpace(raw))
                return "";
                raw = raw.ToUpperInvariant();

            var newNumber = new StringBuilder();
            foreach (var c in raw)
                if (" -0123456789".Contains(c))
                    var result = TranslateToNumber(c);
                    if (result != null)
                // otherwise we've skipped a non-numeric char
            return newNumber.ToString();
        static bool Contains (this string keyString, char c)
            return keyString.IndexOf(c) >= 0;
        static int? TranslateToNumber(char c)
            if ("ABC".Contains(c))
                return 2;
            else if ("DEF".Contains(c))
                return 3;
            else if ("GHI".Contains(c))
                return 4;
            else if ("JKL".Contains(c))
                return 5;
            else if ("MNO".Contains(c))
                return 6;
            else if ("PQRS".Contains(c))
                return 7;
            else if ("TUV".Contains(c))
                return 8;
            else if ("WXYZ".Contains(c))
                return 9;
            return null;

Save the changes to the PhoneTranslator.cs file by clicking File > Save (or by pressing CTRL+S), then close the file.

Wiring up the Interface

The next step is to add code to wire up the user interface by inserting backing code into the MainActivity class. Begin by wiring up the Translate button. In the MainActivity class, find the OnCreate method. The next step is to add the button code inside OnCreate, below the base.OnCreate(savedInstanceState) and SetContentView(Resource.Layout.Main) calls. First, modify the template code so that the OnCreate method resembles the following:

using Android.App;
using Android.OS;
using Android.Support.V7.App;
using Android.Runtime;
using Android.Widget;

namespace Phoneword
    [Activity(Label = "@string/app_name", Theme = "@style/AppTheme", MainLauncher = true)]
    public class MainActivity : AppCompatActivity
        protected override void OnCreate(Bundle savedInstanceState)

            // Set our view from the "main" layout resource

            // New code will go here

Get a reference to the controls that were created in the layout file via the Android Designer. Add the following code inside the OnCreate method, after the call to SetContentView:

// Get our UI controls from the loaded layout
EditText phoneNumberText = FindViewById<EditText>(Resource.Id.PhoneNumberText);
TextView translatedPhoneWord = FindViewById<TextView>(Resource.Id.TranslatedPhoneword);
Button translateButton = FindViewById<Button>(Resource.Id.TranslateButton);

Add code that responds to user presses of the Translate button. Add the following code to the OnCreate method (after the lines added in the previous step):

// Add code to translate number
translateButton.Click += (sender, e) =>
    // Translate user's alphanumeric phone number to numeric
    string translatedNumber = Core.PhonewordTranslator.ToNumber(phoneNumberText.Text);
    if (string.IsNullOrWhiteSpace(translatedNumber))
        translatedPhoneWord.Text = string.Empty;
        translatedPhoneWord.Text = translatedNumber;

Save your work by selecting File > Save All (or by pressing CTRL-SHIFT-S) and build the application by selecting Build > Rebuild Solution (or by pressing CTRL-SHIFT-B).

If there are errors, go through the previous steps and correct any mistakes until the application builds successfully. If you get a build error such as, Resource does not exist in the current context, verify that the namespace name in MainActivity.cs matches the project name (Phoneword) and then completely rebuild the solution. If you still get build errors, verify that you have installed the latest Visual Studio updates.

Setting the App Name

You should now have a working application – it's time to set the name of the app. Expand the values folder (inside the Resources folder) and open the file strings.xml. Change the app name string to Phone Word as shown here:

    <string name="app_name">Phone Word</string>
    <string name="action_settings">Settings</string>

Running the App

Test the application by running it on an Android device or emulator. Tap the TRANSLATE button to translate 1-855-XAMARIN into a phone number:

Screenshot of app running

To run the app on an Android device, see how to set up your device for development.

Congratulations on completing your first Xamarin.Android application! Now it's time to dissect the tools and skills you have just learned. Next up is the Hello, Android Deep Dive.