How to Create a Simple App with Xamarin.Forms
Learn how to create a simple three-page app with Xamarin.Forms in this tutorial by Ed Snider, the author of Mastering Xamarin.Forms – Second Edition.
Discover how to extend and build upon the components of the Xamarin.Forms toolkit to develop effective, robust mobile app architecture. Starting with an app built with the basics of the Xamarin.Forms toolkit, you’ll go step by step through several advanced topics to create solution architecture rich with the benefits of good design patterns and best practices.
Ed Snider, the author of Mastering Xamarin.Forms – Second Edition, is a senior software developer, speaker, author, and Microsoft MVP based in the Washington D.C./Northern Virginia area. He has a passion for mobile design and development and regularly speaks about Xamarin and Windows app development in the community.
This article will show you how to build a simple app with static data, leveraging the most basic concepts of the Xamarin.Forms toolkit. You will create a travel app named TripLog and, like the name suggests, it will be an app that will allow its users to log their travel adventures.
To start off the new TripLog mobile app project, you will need to create the initial solution architecture. You can also create the core shell of your app’s user interface by creating the initial screens based on the basic features. You can find all the necessary files for this article here.
Setting up the Xamarin.Forms solution
You can kick things off by creating a brand new, blank Xamarin.Forms solution within Visual Studio by performing the following steps:
- In Visual Studio, click on File| New Solution. This will bring up a series of dialog screens that will walk you through creating a new Xamarin.Forms solution. On the first dialog, click on App on the left-hand side, under the Multiplatform section and then select Blank Forms App:
- On the next dialog screen, enter the name of the app, TripLog; ensure that Use Portable Class Libraryis selected for the Shared Code option and that Use XAML for user interface files option is checked:
Note that the Xamarin.Forms project template in Visual Studio for Windows will use a .NET Standard library instead of a Portable Class Library for its core library project.
- On the final dialog screen, simply click on the Createbutton:
After creating the new Xamarin.Forms solution, you will have several projects created within it, as shown in the following screenshot:
There will be a single portable class library project and two platform-specific projects, as follows:
- TripLog: This is a portable class library project that will serve as the corelayer of the solution architecture. This is the layer that will include all your business logic, data objects, Xamarin.Forms pages, and other non-platform-specific code. The code in this project is common and not specific to a platform and can therefore, be shared across the platform projects.
- iOS: This is the iOS platform-specific project containing all the code and assets required to build and deploy the iOS app from this solution. By default, it will have a reference to the TripLog core project.
- Droid: This is the Android platform-specific project containing all the code and assets required to build and deploy the Android app from this solution. By default, it will have a reference to the TripLog core project.
Note that if you are using Visual Studio for Mac, you will only get an iOS and an Android project when you create a new Xamarin.Forms solution. To include a Windows (UWP) app in your Xamarin.Forms solution, you will need to use Visual Studio for Windows. Although the screenshots and samples used here are demonstrated using Visual Studio for Mac, the code and concepts will also work in Visual Studio for Windows.
You’ll notice a file in the core library named App.xaml, which includes a code-behind class in App.xaml.cs named App that inherits from Xamarin.Forms.Application. Initially, the App constructor sets the MainPage property to a new instance of a ContentPage named TripLogPage that simply displays some default text.
The first thing you to do in your TripLog app is build the initial views or screens required for your UI and then update that MainPage property of the App class in App.xaml.cs.
Creating the app’s main page
The main page of the app will serve as the entry point into the app and display a list of existing trip log entries. Your trip log entries will be represented by a data model named TripLogEntry and you will have to create a simple class that will represent the TripLogEntry model.
Now you can start creating the main page by performing the following steps:
- First, add a new Xamarin.Forms XAML ContentPageto the core project and name it MainPage.
- Next, update the MainPageproperty of the App class in xaml.cs to a new instance of Xamarin.Forms.NavigationPage whose root is a new instance of TripLog.MainPage that you just created:
- Delete xamlfrom the core project as it is no longer needed.
- Create a new folder in the core project named Models.
- Create a new empty class file in the Modelsfolder named TripLogEntry.
- Update the TripLogEntryclass with auto-implemented properties representing the attributes of an entry:
- Now that you have a model to represent your trip log entries, you can use it to display some trips on the main page using a ListView You will use DataTemplateto describe how the model data should be displayed in each of the rows in the ListView using the following XAML in the ContentPage.Content tag in MainPage.xaml:
- In the main page’s code-behind, xaml.cs, you can populate ListViewItemsSourcewith a hard-coded collection of the TripLogEntry objects:
At this point, you have a single page that is displayed as the app’s main page. If you debug the app and run it in a simulator, emulator, or on a physical device, you should see the main page showing the list of log entries you hard-coded into the view, as shown in the following screenshot.
Creating the new entry page
The new entry page of the app will give the user a way to add a new log entry by presenting a series of fields to collect the log entry details. There are several ways to build a form to collect data in Xamarin.Forms. You can simply use a StackLayout and present a stack of Label and Entry controls on the screen, or you can also use a TableView with various types of ViewCell elements. In most cases, a TableView will give you a very nice default, platform-specific look and feel. However, if your design calls for a more customized aesthetic, you might be better off leveraging the other layout options available in Xamarin.Forms. For the purpose of this app, you can use TableView.
There are some key data points you need to collect when your users log new entries with the app, such as title, location, date, rating, and notes. For now, you can use a regular EntryCell element for each of these fields. You can update, customize, and add things to these fields later.
In order to create the new entry page that contains a TableView, perform the following steps:
- First, add a new Xamarin.Forms XAML ContentPageto the core project and name it NewEntryPage.
- Update the new entry page using the following XAML to build TableViewthat will represent the data entry form on the page:
Now that you have created the new entry page, you’ll need to add a way for users to get to this new screen from the main page. You can do this by adding a New button to the main page’s toolbar. In Xamarin.Forms, this is accomplished by adding a ToolbarItem to the ContentPage.ToolbarItems collection and wiring up the ToolbarItem.Clicked event to navigate to the new entry page, as shown in the following XAML:
For now, you can use the default Xamarin.Forms navigation mechanism.
When you run the app, you will see a New button on the toolbar of the main page. Clicking on the New button should bring you to the new entry page, as shown in the following screenshot:
You’ll need to add a save button to the new entry page toolbar so that you can save new items. For now, this button will just be a placeholder in the UI. The save button will be added to the new entry page toolbar in the same way the New button was added to the main page toolbar. Update the XAML in NewEntryPage.xaml to include a new ToolbarItem, as shown in the following code:
When you run the app again and navigate to the new entry page, you should now see the Save button on the toolbar, as shown in the following screenshot:
Creating the entry detail page
When a user clicks on one of the log entry items on the main page, you want to take them to a page that displays more details about that particular item, including a map that plots the item’s location. Along with additional details and a more in-depth view of the item, a detail page is also a common area where actions on that item might take place, such as, editing the item or sharing the item on social media. The detail page will take an instance of a TripLogEntry model as a constructor parameter, which you can use in the rest of the page to display the entry details to the user.
In order to create the entry detail page, perform the following steps:
- First, add a new Xamarin.Forms XAML ContentPageto the project and name it DetailPage.
- Update the constructor of the DetailPageclass in xaml.cs to take a TripLogEntry parameter named entry, as shown in the following code:
- Add the Forms.MapsNuGet package to the core project and to each of the platform-specific projects. This separate NuGet package is required in order to use the Xamarin.Forms Map control in the next step.
- Update the XAML in xamlto include a Grid layout to display a Map control and some Label controls to display the trip’s details, as shown in the following code:
- Update the detail page’s code-behind, xaml.cs, to center the map and plot the trip’s location. You’ll also need to update the Labelcontrols on the detail page with the properties of the entry constructor parameter:
- Next, you’ll need to wire up the ItemTappedevent of the ListView on the main page to pass the tapped item over to the entry detail page that you have just created, as shown in the following code:
- Finally, you’ll need to initialize the Xamarin.Forms.Maps library in each platform-specific startup class (AppDelegate for iOS and MainActivity for Android) using the following code:
Now, when you run the app and tap on one of the log entries on the main page, it will navigate you to the details page to see more detail about that particular log entry, as shown in the following screenshot:
You’ve successfully created a simple three-page app (with static data) with Xamarin.Forms. If you found this article interesting, you can explore Ed Snider’s Mastering Xamarin.Forms – Second Edition to create high-quality multi-platform native apps with Xamarin.Forms.