Edit

Build a Xamarin.Forms app with Azure Mobile Apps

  • Article

This tutorial shows you how to add a cloud-based backend service to a cross-platform mobile app by using Xamarin.Forms and an Azure mobile app backend. You'll create both a new mobile app backend and a simple Todo list app that stores app data in Azure.

You must complete this tutorial before other Xamarin Forms tutorials using the Mobile Apps feature in Azure App Service.

Prerequisites

You can complete this tutorial on Mac or Windows. To complete this tutorial, you need:

  • Visual Studio 2022 with the following workloads.
    • ASP.NET and web development
    • Azure development
    • Mobile development with .NET
  • An Azure account.
  • The Azure CLI.
    • Sign in with az login and select an appropriate subscription before starting.
  • An Android Virtual Device, with the following settings:
    • Phone: Any phone image - we use the Pixel 5 for testing.
    • System Image: Android 11 (API 30 with Google APIs)

If compiling the iOS edition of the app, you must have an available Mac:

  • Install XCode
  • Open Xcode after installing so that it can add any extra required components.
  • Once open, select XCode Preferences... > Components, and install an iOS simulator.
  • If completing the tutorial on Windows, follow the guide to Pair to Mac.
  • Visual Studio 2022 for Mac
  • An Azure account.
  • The Azure CLI.
    • Sign in with az login and select an appropriate subscription before starting.
  • An Android Virtual Device, with the following settings:
    • Phone: Any phone image - we use the Pixel 5 for testing.
    • System Image: Android 11 (API 30 with Google APIs)
  • Install XCode
    • Open Xcode after installing so that it can add any extra required components.
    • Once open, select XCode Preferences... > Components, and install an iOS simulator.

Download the sample app

  1. Open the azure-mobile-apps repository in your browser.

  2. Open the Code drop-down, then select Download ZIP.

    Screenshot of the Code menu on GitHub.

  3. Once the download is complete, open your Downloads folder and locate the azure-mobile-apps-main.zip file.

  4. Right-click the downloaded file, and select Extract All....

    If you prefer, you can use PowerShell to expand the archive:

    C:\Temp> Expand-Archive azure-mobile-apps-main.zip

The samples are located in the samples folder within the extracted files. The sample for the quick start is named TodoApp. You can open the sample in Visual Studio by double-clicking the TodoApp.sln file.

Screenshot of the file explorer for the solution.

  1. Open the azure-mobile-apps repository in your browser.

  2. Open the Code drop-down, then select Download ZIP.

    Screenshot of the Code menu on GitHub.

  3. Once the download is complete, open your Downloads folder.

  4. The package will already be unpacked in the azure-mobile-apps-main folder. You can move this folder to a more appropriate location if you like.

The samples are located in the samples folder within the extracted files. The sample for the quick start is named TodoApp. You can open the sample in Visual Studio 2022 for Mac by double-clicking the TodoApp.sln file.

Screenshot of the file explorer for the solution.

When you open the sample for the first time, notice that certain projects aren't available. For example, Windows-specific projects (such as WPF and UWP) can't be compiled with Visual Studio 2022 for Mac.

You can unload any project you aren't working with. Expand the windows folder in the solution explorer.

Screenshot of the solution explorer with disabled projects.

For each disabled project, right-click on the project, then select Unload project.

Deploy the backend to Azure

Note

If you have already deployed the backend from another quick start, you can use the same backend and skip this step.

To deploy the backend service, we will:

  • Use Azure Resource Manager and the Azure CLI to deploy an Azure App Service and Azure SQL Database to Azure.
  • Use Visual Studio to publish the service code to the newly created Azure App Service.

Create resources on Azure.

  1. Open a terminal and change directory to the folder containing the TodoApp.sln file. This directory also contains azuredeploy.json.

  2. Ensure you've signed in and selected a subscription using the Azure CLI.

  3. Create a new resource group:

    az group create -l westus -g quickstart

    This command will create the quickstart resource group in the West US region. You can select any region that you wish, providing you can create resources there. Ensure you use the same name and region wherever they're mentioned in this tutorial.

  4. Create the resources using a group deployment:

    az deployment group create -g quickstart --template-file azuredeploy.json --parameters sqlPassword=MyPassword1234

    Pick a strong password for your SQL Administrator password. You'll need it later on when accessing the database.

  5. Once the deployment is complete, get the output variables as these hold important information you'll need later on:

    az deployment group show -g quickstart -n azuredeploy --query properties.outputs

    An example output will be:

    Screenshot of command line results.

  6. Make a note of each of the values in the outputs for later use.

Publish the service code.

Open the TodoApp.sln in Visual Studio.

  1. In the right-hand pane, select the Solutions Explorer.

  2. Right-click the TodoAppService.NET6 project, then select Set as Startup Project.

  3. On the top menu, select Build > Publish TodoAppService.NET6.

  4. In the Publish window, select Target: Azure, then press Next.

    Screenshot of the target selection window.

  5. Select Specific target: Azure App Service (Windows), then press Next.

    Screenshot of the specific target selection window.

  6. If necessary, sign in and select an appropriate Subscription name.

  7. Ensure View is set to Resource group.

  8. Expand the quickstart resource group, then select the App Service that was created earlier.

    Screenshot of the app service selection window.

  9. Select Finish.

  10. Once the publish profile creation process has completed, select Close.

  11. Locate the Service Dependencies and select the triple-dots next to the SQL Server Database, then select Connect.

    Screenshot showing the S Q L server configuration selection.

  12. Select Azure SQL Database, then select Next.

  13. Select the quickstart database, then select Next.

    Screenshot of the database selection window.

  14. Fill in the form using the SQL username and password that were in the outputs of the deployment, then select Next.

    Screenshot of the database settings window.

  15. Select Finish.

  16. Select Close when complete.

  17. Select Publish to publish your app to the Azure App Service you created earlier.

    Screenshot showing the publish button.

  18. Once the backend service is published, a browser will be opened. Add /tables/todoitem?ZUMO-API-VERSION=3.0.0 to the URL:

    Screenshot showing the browser output after the service is published.

To deploy the backend service, we will:

  • Use Azure Resource Manager and the Azure CLI to deploy an Azure App Service and Azure SQL Database to Azure.
  • Use Visual Studio 2022 for Mac to publish the service code to the newly created Azure App Service.

Create resources on Azure

  1. Open a terminal and change directory to the folder containing the TodoApp.sln file. This directory also contains azuredeploy.json.

  2. Ensure you've signed in and selected a subscription using the Azure CLI.

  3. Create a new resource group:

    az group create -l westus -g quickstart

    This command will create the quickstart resource group in the West US region. You can select any region that you wish, providing you can create resources there. Ensure you use the same name and region wherever they're mentioned in this tutorial.

  4. Create the resources using a group deployment:

    az deployment group create -g quickstart --template-file azuredeploy.json --parameters sqlPassword=MyPassword1234

    Pick a strong password for your SQL Administrator password. You'll need it later on when accessing the database.

  5. Once the deployment is complete, get the output variables as these hold important information you'll need later on:

    az deployment group show -g quickstart -n azuredeploy --query properties.outputs

    An example output will be:

    Screenshot of command line results.

  6. Make a note of each of the values in the outputs for later use.

Publish the service code

Open the TodoApp.sln in Visual Studio 2022 for Mac.

  1. Right-click the TodoApp solution, then select Restore NuGet Packages.

  2. Wait for the NuGet package restoration to complete.

  3. Right-click the TodoAppService.NET6 project, then Publish > Publish to Azure....

  4. Select the service you created above (in the quickstart resource group), then select Publish.

    Screenshot of the target selection window.

  5. Once the backend service is published, a browser will be opened. Add /tables/todoitem?ZUMO-API-VERSION=3.0.0 to the URL:

    Screenshot showing the browser output after the service is published.

Configure the sample app

Your client application needs to know the base URL of your backend so that it can communicate with it.

  1. Expand the TodoApp.Data project.

  2. Right-click on the TodoApp.Data project, then select Add > Class....

  3. Enter Constants.cs as the name, then select Add.

    Screenshot of adding the Constants.cs file to the project.

  4. Open the Constants.cs.example file and copy the contents (Ctrl-A, followed by Ctrl-C).

  5. Switch to Constants.cs, highlight all text (Ctrl-A), then paste the contents from the example file (Ctrl-V).

  6. Replace the https://APPSERVICENAME.azurewebsites.net with the backend URL of your service.

    namespace TodoApp.Data
{
    public static class Constants
    {
        /// <summary>
        /// The base URI for the Datasync service.
        /// </summary>
        public static string ServiceUri = "https://demo-datasync-quickstart.azurewebsites.net";
    }
}

    You can obtain the backend URL of your service from the Publish tab. Ensure you use a https URL.

  7. Save the file. (Ctrl-S).

Your client application needs to know the base URL of your backend so that it can communicate with it.

  1. Expand the TodoApp.Data project.

  2. Right-click on the TodoApp.Data project, then select Add > New Class....

  3. Select Empty Class, enter Constants.cs as the name, then select Create.

    Screenshot of adding the Constants.cs file to the project.

  4. Open the Constants.cs.example file and copy the contents (⌘-A, followed by ⌘-C).

  5. Switch to Constants.cs, highlight all text (⌘-A), then paste the contents from the example file (⌘-V).

  6. Replace the https://APPSERVICENAME.azurewebsites.net with the backend URL of your service.

    namespace TodoApp.Data
{
    public static class Constants
    {
        /// <summary>
        /// The base URI for the Datasync service.
        /// </summary>
        public static string ServiceUri = "https://demo-datasync-quickstart.azurewebsites.net";
    }
}

  7. Save the file. (⌘-S).

Build and run the Android app

  1. In the solutions explorer, expand the xamarin-forms folder.

  2. Right-click the TodoApp.Forms.Android project and select Set as Startup Project.

  3. In the top bar, select Any CPU configuration and the TodoApp.Forms.Android target:

    Screenshot showing how to set the run configuration for a Xamarin Forms for Android app.

  4. If you see Android Emulator instead, you haven't created an Android emulator. For more information, see Android emulator setup. To create a new Android emulator:

    • Select Tools > Android > Android Device Manager.
    • Select + New.
    • Select the following options on the left-hand side:
      • Name: quickstart
      • Base Device: Pixel 5
      • Processor: x86_64
      • OS: Android 11.0 - API 30
      • Google APIs: Checked
    • Select Create.
    • If necessary, accept the license agreement. The image will then be downloaded.
    • Once the Start button appears, press Start.
    • If you're prompted about Hyper-V hardware acceleration, read the documentation to enable hardware acceleration before continuing. The emulator will be slow without enabling hardware acceleration.

    Tip

    Start your Android emulator before continuing. You can do this by opening the Android Device Manager and pressing Start next to your chosen emulator.

  5. Press F5 to build and run the project.

Once the app has started, you'll see an empty list and a text box to add items in the emulator. You can:

  • Enter some text in the box, then press Enter to insert a new item.
  • Select an item to set or clear the completed flag.
  • Press the refresh icon to reload data from the service.

Screenshot of the running Android app.

  1. In the solutions explorer, expand the xamarin-forms folder.

  2. Right-click the TodoApp.Forms.Android project and select Set as Startup Project.

  3. In the top bar, select an appropriate Android emulator:

    Screenshot showing how to select an Android emulator on a Mac.

  4. In the top menu, select Debug > Start Debugging.

Once the app has started, you'll see an empty list and a text box to add items in the emulator. You can:

  • Press the + button to add an item.
  • Select an item to set or clear the completed flag.
  • Press the refresh icon to reload data from the service.

Screenshot of the running Android app showing the to do list running on a Mac.

Build and run the iOS app

Note

You MUST follow the guide to Pair to Mac. You'll receive errors when compiling or running iOS applications without a paired Mac.

  1. In the solutions explorer, expand the xamarin-forms folder.

  2. Right-click the TodoApp.Forms.iOS project and select Set as Startup Project.

  3. In the top bar, select iPhone Simulator configuration and the TodoApp.Forms.iOS target:

    Screenshot showing how to set the run configuration for a Xamarin Forms for i O S app.

  4. Select the iPhone Simulator

  5. Press F5 to build and run the project.

Once the app has started, you'll see an empty list and a text box to add items in the emulator. You can:

  • Enter some text in the box, then press Enter to insert a new item.
  • Select an item to set or clear the completed flag.
  • Press the refresh icon to reload data from the service.

Screenshot of the running i O S app showing the to do list.

Troubleshooting

The remote simulator that ships with Visual Studio 2022 is incompatible with XCode 13.3. You'll receive the following error message:

Screenshot of the error message when launching the i O S simulator.

To work around this issue:

  • Disable the remote simulator (Tools / Options / iOS Settings / uncheck Remote Simulator to Windows). When unchecked, the simulator will run on the Mac instead of on Windows. You can then interact with the simulator directly on your Mac while using the debugger, etc. on Windows.
  • Disable the remote simulator as above, so that the simulator runs on the Mac. Then use a remote desktop app to connect to the Mac desktop from Windows. Remote desktop options include Devolutions Remote Desktop Manager (fast and there’s a free version available), and VNC clients (slower and free).
  • Use a physical device to test instead of the simulator. You can obtain a free provisioning profile to complete the authentication tutorial.

  1. In the solutions explorer, expand the xamarin-forms folder.

  2. Right-click the TodoApp.Forms.iOS project and select Set as Startup Project.

  3. In the top bar, select an appropriate iOS simulator:

    Screenshot showing how to select an i O S simulator on a Mac.

  4. In the top menu, select Debug > Start Debugging.

Once the app has started, you'll see an empty list and a text box to add items in the emulator. You can:

  • Press the + button to add an item.
  • Select an item to set or clear the completed flag.
  • Press the refresh icon to reload data from the service.

Screenshot of the running i O S app showing the to do list running on a Mac.

Troubleshooting

Some versions of Visual Studio 2022 for Mac do not work with some versions of XCode. If you receive a HE0042 error when running the app on a simulator, it's likely you need to update your version of Visual Studio 2022 for Mac. Use the latest preview version and ensure all available updates are applied. The app is deployed to the simulator. If you still have problems running via the debugger, start the app from the simulator instead.

Next steps

Continue the tutorial by adding authentication to the app.