Hello, iOS – Quickstart

This guide describes how to create an application that translates an alphanumeric phone number entered by the user into a numeric phone number, and then calls that number. The final application looks like this:


iOS development with Xamarin requires:

  • A Mac running macOS Sierra (10.12) or above.
  • Latest version of Xcode and iOS SDK installed from the App Store .

Xamarin.iOS works with the following setups:

  • Latest version of Visual Studio for Mac that fits the above specifications.

The Xamarin.iOS Mac Installation guide is available for step-by-step installation instructions

Before getting started, download the Xamarin App Icons set.

Visual Studio for Mac Walkthrough

This walkthrough describes how to create an application called Phoneword that translates an alphanumeric phone number into a numeric phone number.

  1. Launch Visual Studio for Mac from the Applications folder or Spotlight to bring up the Launch screen:

On the Launch Screen, click New Project... to create a new Xamarin.iOS solution:

  1. From the New Solution dialog, choose the iOS > App > Single View Application template, ensuring that C# is selected. Click Next:

  1. Configure the app. Give it the Name Phoneword_iOS, and leave everything else as default. Click Next:

  1. Leave the Project and Solution Name as is. Choose the location of the project here, or keep it as the default:

  1. Click Create to make the Solution.

  2. Open the Main.storyboard file by double-clicking on it in the Solution Pad. This provides a way to visually to create a UI:

Note that size classes are enabled by default. Refer to the Unified Storyboards guide to learn more about them.

  1. In the Toolbox Pad, type "label" into the search bar and drag a Label onto the design surface (the area in the center):


You can bring up the Properties Pad or Toolbox at any time by navigating to View > Pads.

  1. Grab the handles of the Dragging Controls (the circles around the control) and make the label wider:

  1. With the Label selected on the design surface, use the Properties Pad to change the Text property of the Label to "Enter a Phoneword:"

  1. Search for “text field” inside the Toolbox and drag a Text Field from the Toolbox onto the design surface and place it under the Label. Adjust the width until the Text Field is the same width as the Label:

  1. With the Text Field selected on the design surface, change the Text Field’s Name property in the Identity section of the Properties Pad to PhoneNumberText, and change the Text property to "1-855-XAMARIN":

  1. Drag a Button from the Toolbox onto the design surface and place it under the Text Field. Adjust the width so the Button is as wide as the Text Field and Label:

  1. With the Button selected on the design surface, change the Name property in the Identity section of the Properties Pad to TranslateButton. Change the Title property to "Translate":

  1. Repeat the two steps above and drag a Button from the Toolbox onto the design surface and place it under the first Button. Adjust the width so the Button is as wide as the first Button:

  1. With the second Button selected on the design surface, change the Name property in the Identity section of the Properties Pad to CallButton. Change the Title property to "Call":

Save the changes by navigating to File > Save or by pressing ⌘ + s.

  1. Some logic needs to be added to the app to translate phone numbers from alphanumeric to numeric. Add a new file to the Project by right clicking on the Phoneword_iOS Project in the Solution Pad and choosing Add > New File... or pressing ⌘ + n:

  1. In the New File dialog, select General > Empty Class and name the new file PhoneTranslator:

  1. This creates a new, empty C# class for us. Remove all the template code and replace it with the following code:

    using System.Text;
    using System;
    namespace Phoneword_iOS
    	public static class PhoneTranslator
    		public static string ToNumber(string raw)
    			if (string.IsNullOrWhiteSpace(raw)) {
    				return "";
    			} else {
    				raw = raw.ToUpperInvariant();
    			var newNumber = new StringBuilder();
    			foreach (var c in raw)
    				if (" -0123456789".Contains(c)) {
    				} else {
    					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 PhoneTranslator.cs file and close it.

  2. Add code to wire up the user interface. To do this double-click on ViewController.cs in the Solution Pad to open it:

  1. Begin by wiring up the TranslateButton. In the ViewController class, find the ViewDidLoad method and add the following code beneath the base.ViewDidLoad() call:

    string translatedNumber = "";
    TranslateButton.TouchUpInside += (object sender, EventArgs e) => {
    	// Convert the phone number with text to a number
    	// using PhoneTranslator.cs
    	translatedNumber = PhoneTranslator.ToNumber(
    	// Dismiss the keyboard if text field was tapped
    	PhoneNumberText.ResignFirstResponder ();
    	if (translatedNumber == "") {
    		CallButton.SetTitle ("Call ", UIControlState.Normal);
    		CallButton.Enabled = false;
    	} else {
    		CallButton.SetTitle ("Call " + translatedNumber,
    		CallButton.Enabled = true;

    Include using Phoneword_iOS; if the file's namespace is different.

  2. Add code to respond to the user pressing the second button, which is named CallButton. Place the following code below the code for the TranslateButton and add using Foundation; to the top of the file:

    	CallButton.TouchUpInside += (object sender, EventArgs e) => {
    		// Use URL handler with tel: prefix to invoke Apple's Phone app...
    		var url = new NSUrl ("tel:" + translatedNumber);
    		// ...otherwise show an alert dialog
    		if (!UIApplication.SharedApplication.OpenUrl (url)) {
    			var alert = UIAlertController.Create ("Not supported", "Scheme 'tel:' is not supported on this device", UIAlertControllerStyle.Alert);
    			alert.AddAction (UIAlertAction.Create ("Ok", UIAlertActionStyle.Default, null));
    			PresentViewController (alert, true, null);
  3. Save the changes and then build the application by choosing Build > Build All or pressing ⌘ + B. If the application compiles, a success message will appear at the top of the IDE:

If there are errors, go through the previous steps and correct any mistakes until the application builds successfully.

  1. Finally, test the application in the iOS Simulator. In the top left of the IDE, choose Debug from the first dropdown, and iPhone 8 Plus iOS x.x from the second dropdown, and press Start (the triangular button that resembles a Play button):


At present, due to a requirement from Apple, it may be necessary to have a a development certificate or signing identity to build you code for device or simulator. Follow the steps in the Device Provisioning guide to set this up.

  1. This will launch the application inside the iOS Simulator:

Phone calls are not supported in the iOS Simulator; instead, you will see an alert dialog when trying to place a call:

Congratulations on completing your first Xamarin.iOS application!

Now it’s time to dissect the tools and skills shown in this guide in the Hello, iOS Deep Dive.