Tutorial: Get Started with Xamarin in Visual Studio

Xamarin is a cross-platform technology that makes it possible to build native mobile apps for Android, iOS, and Windows Phone using C# and a shared codebase. Like its younger siblings NativeScript and React Native, it allows development teams to build mobile applications using the skills they already have, and spend less time writing code for each platform.

If you haven’t tried Xamarin yet, now is a great time to get started! Earlier this year, Microsoft bought Xamarin and made it free (and open-source). You can build Xamarin projects on Windows (using Visual Studio), or Mac/Linux (using Xamarin Studio).

I’m excited to dig into Xamarin because mobile apps need authentication and authorization, which Stormpath makes easy. We already have rich SDKs for .NET and ASP.NET, as well as SDKs for iOS and Android separately, but a Xamarin-specific SDK could provide even more value and make it super simple to secure your apps. It’s something I’m currently digging into, so stay tuned!

In this tutorial, I’ll show you how to use Visual Studio and Xamarin to build a basic app for iOS and Android — even if you’ve never done any app development before!

Setting Up Visual Studio and Xamarin

If you don’t have Visual Studio 2015 installed, download the free Community Edition from Microsoft. If you already have Visual Studio, make sure you have the latest update (Update 3 at the time of writing).

You’ll also need to install some optional components for Visual Studio. If you’re setting up Visual Studio from scratch, make sure these items are selected:

C#/.NET (Xamarin 4.1.1)

Visual Studio Emulator for Android

Choosing Visual Studio options

If you have an existing installation, you can verify that these components are installed by opening the Control Panel, choosing Uninstall or change a program, and selecting Microsoft Visual Studio 2015. Follow the installation wizard to make sure the above items (at a minimum) are checked.

Once you have the tools set up, you’re ready to create a Xamarin project!

Xamarin vs. Xamarin.Forms

The Xamarin SDK provides bindings to the platform-specific APIs on each mobile platform, so you can call Android or iOS APIs from C# code. This allows you to build native apps using C#, but you still need to design the UI separately for each platform.

Xamarin.Forms is an additional layer on top of the Xamarin SDK that makes it possible to build your UI once (in XAML markup) and let Xamarin do the hard work of translating it into the appropriate UI elements on the target platform. You can drop down to the Xamarin SDK level and interact with the platform APIs if you need to.

Should you use “raw” Xamarin, or Xamarin.Forms? It depends on what you are building:

If you’re building an app that needs little platform-specific functionality or custom UI, go with Xamarin.Forms. This is a good choice for straightforward data-entry apps and prototypes.

If you’re building an app that needs UI customized for each platform, or includes a lot of complex interactions, you’re better off with straight Xamarin.

Since the goal of this tutorial is building a simple app, Xamarin.Forms is the fastest and easiest way to go!

Creating a New Xamarin.Forms Project

First, create a new project in Visual Studio. In the New Project window, choose the Cross-platform category, and the Blank App (Xamarin.Forms Portable) template. Name the project HelloWorldApp.

Creating a new Xamarin.Forms project

Scaffolding the project may take a minute. Dismiss any dialogs that pop up during the process. When the scaffolding is complete, right-click on the top-level solution and choose Manage NuGet Packages for Solution. Update the Xamarin.Forms package, if applicable.

Updating the Xamarin.Forms package

Leave the other packages alone, even if they have available updates. I ran into a few issues when I enthusiastically updated everything. Some of the available packages are newer than what Xamarin.Forms supports and shouldn’t be updated.

The Blank App template creates a number of projects in the solution:

Xamarin.Forms solution

HelloWorldApp (Portable) – Contains the XAML and shared code for each platform-specific project.

HelloWorldApp.Droid – Android-specific code. For a simple project, you won’t have to change much here.

HelloWorldApp.iOS – iOS-specific code. You won’t have to change much here, either.

The template also includes projects for UWP (Windows 10 and Windows 10 Mobile) apps, Windows 8.1 (Metro) apps, and Windows Phone 8.1 apps.

In this tutorial, you’ll only need to modify the shared (portable) library project.

Adding a View

To create a new UI view (called a “page” in Xamarin.Forms lingo), right-click on the HelloWorldApp (Portable) project, and choose New Item. Pick the Forms Xaml Page template and name the new page HelloWorldPage.

Adding a XAML page

Replace the generated XAML with this markup:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="HelloWorldApp.HelloWorldPage">
  <ContentPage.Padding>
    <OnPlatform x:TypeArguments="Thickness"
                iOS="20, 40, 20, 20"
                Android="20, 20, 20, 20"
                WinPhone="20, 20, 20, 20" />
  </ContentPage.Padding>
  <ContentPage.Content>
    <StackLayout VerticalOptions="FillAndExpand"
                 HorizontalOptions="FillAndExpand"
                 Orientation="Vertical"
                 Spacing="15">
      <Label Text="Enter your name:" />
      <Entry x:Name="NameEntry" Text="Jane Doe" />
      <Button x:Name="SayHelloButton" Text="Say Hello" Clicked="SayHelloButton_OnClicked" />
    </StackLayout>
  </ContentPage.Content>
</ContentPage>

<?xml version="1.0" encoding="UTF-8"?>

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"

xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"

x:Class="HelloWorldApp.HelloWorldPage">

<ContentPage.Padding>

<OnPlatform x:TypeArguments="Thickness"

iOS="20, 40, 20, 20"

Android="20, 20, 20, 20"

WinPhone="20, 20, 20, 20" />

</ContentPage.Padding>

<ContentPage.Content>

<StackLayout VerticalOptions="FillAndExpand"

HorizontalOptions="FillAndExpand"

Orientation="Vertical"

Spacing="15">

</StackLayout>

</ContentPage.Content>

</ContentPage>

This XAML code creates a basic layout containing Label, Entry (text box), and Button controls. The control names (specified with x:Name) will be used to refer to the controls in code.

The Clicked= attribute on the Button element wires up the button click event to a handler called SayHelloButton_OnClicked, which doesn’t exist yet (but it’s about to!)

Open up the code-behind for the XAML file by expanding it in the Solution Explorer and double-clicking on the HelloWorldPage.xaml.cs file.

Opening the code-behind

Replace the generated C# code with the following:

using System;
using Xamarin.Forms;

namespace HelloWorldApp
{
    public partial class HelloWorldPage : ContentPage
    {
        public HelloWorldPage()
        {
            InitializeComponent();
        }

        private async void SayHelloButton_OnClicked(object sender, EventArgs e)
        {
            var name = NameEntry.Text;
            await DisplayAlert("Greeting", $"Hello {name}!", "Howdy");
        }
    }
}

using System;

using Xamarin.Forms;

namespace HelloWorldApp

{

public partial class HelloWorldPage : ContentPage

{

public HelloWorldPage()

{

InitializeComponent();

}

private async void SayHelloButton_OnClicked(object sender, EventArgs e)

{

var name = NameEntry.Text;

await DisplayAlert("Greeting", $"Hello {name}!", "Howdy");

}

Looks familiar, doesn’t it? The SayHelloButton_OnClicked method will run when the SayHelloButton is clicked on the XAML page. First, the value of the textbox is assigned to the name variable, and then the DisplayName method is called to display a modal popup on the device.

There’s one more thing to do before you’re done: telling the app to use the new page. In App.cs, replace the constructor method with this:

public App()
{
    MainPage = new HelloWorldPage();
}

public App()

{

MainPage = new HelloWorldPage();

}

That’s it! Your new Xamarin app is ready to go.

Testing Your Xamarin App on Android

If you have the Visual Studio Android Emulator installed, testing the Android version of your Xamarin app is simple. In the Visual Studio toolbar, pick the HelloWorldApp.Droid project and choose an Android device to emulate. Then, click the green Play button to start the emulator.

Starting the Android emulator

The Android emulator can be slow to load, so give it some time. If everything builds properly, you should see your app running on Android.

Testing the app on Android

Testing Your Xamarin App on iOS

Testing your Xamarin app on iOS is a little trickier, because it requires a Mac to provide the emulator. If you have a Mac handy, follow the official instructions to set up the Mac agent and connect it to Visual Studio. Then, pick the HelloWorld.iOS project, and switch the architecture to iPhone Simulator. Choose a device version and click Play.

Starting the iOS emulator