Build your Xamarin app

VSTS | TFS 2018 | TFS 2017.2

Xamarin enables you to develop a single solution and deploy it to Android, iOS, and Windows devices. Visual Studio Team Services (VSTS) and Team Foundation Server (TFS) provide a highly customizable continuous integration (CI) process to automatically build and package your Xamarin app whenever your team pushes or checks in code. In this quickstart you learn how to define your CI process.


  • A VSTS account. If you don't have one, you can create one for free. If your team already has one, then make sure you are an administrator of the team project you want to use.
  • While the simplest way to try this quickstart is to use a VSTS account, you can also use a TFS server instead of a VSTS account.

  • You will build the sample app for Android and iOS using two build definitions in this quickstart. If you use VSTS, you can use a Microsoft-hosted agent for both. If you use TFS, you will need a self-hosted agent to build Xamarin.Android and Xamarin.iOS. Xamarin.iOS requires an agent running on macOS. Set up a self-hosted agent and install Xamarin on the agent machine. The Xamarin version on your development machine and build agent machine must be at least 4.0.3 for Windows and 5.10.3 for macOS.

    Build Microsoft-hosted agents On-premises Windows agent On-premises macOS or Linux agent
    Xamarin.Android Yes Yes (with Xamarin installed) Yes (with Xamarin installed)
    Xamarin.iOS Yes No Yes (with Xamarin installed)
    UWP Yes Yes (Windows 10) No

Get the sample code

You can copy this sample app code directly into your version control system so that it can be accessed by your CI build process. To get started, copy this URL to your clipboard:

To import the sample app into a Git repo in VSTS or TFS:

  1. On the Code hub for your team project in VSTS/TFS, select the option to Import repository.

  2. In the Import a Git repository dialog box, paste the above URL into the Clone URL text box.

  3. Click Import to copy the sample code into your Git repo.

Set up continuous integration

A continuous integration (CI) process automatically builds and tests code every time a team member commits changes to version control. Here you'll create a CI build definition that helps your team keep the master branch clean.

You need to create two build definitions - one for Xamarin.Android and one for Xamarin.iOS.

Define your Xamarin.Android build

  1. Create a new build definition.

    Navigate to the Files tab of the Code hub, and then click Set up build.

    Screenshot showing button to set up build for a repository

    You are taken to the Build and Release hub and asked to Select a template for the new build definition.

  2. In the right panel, click Xamarin.Android, and then click Apply.

    You now see all the tasks that were automatically added to the build definition by the template. These are the tasks that will automatically run every time you push code changes.

  3. For the Agent queue:

    • VSTS: Select Hosted VS2017. This hosted pool of agents has the software needed to build your app.

    • TFS: Select a queue that includes a macOS or Windows build agent.

  4. Click Get sources and then:

    Observe that the new build definition is automatically linked to your repository.

  5. Select the Build Xamarin.Android Project task. In the properties for this task, select JDK 8 as the JDK Version, and x64 as the JDK Architecture.

  6. Select the Build solution */test.csproj task. In the properties for this task, uncheck Enabled under Control Options. There are no tests in the sample repository.

  7. Select the Xamarin Test Cloud task. Remove this task from the definition by right-clicking it and selecting Remove selected task(s).

  8. Click Save & queue to kick off your first build. On the Save build definition and queue dialog box, click Save & queue.

  9. A new build is started. You'll see a link to the new build on the top of the page. Click the link to watch the new build as it happens.

Define your Xamarin.iOS build

Navigate to the Builds tab of the Build and Release hub, and then click + New. You are asked to Select a template for the new build definition. This time, select the Xamarin.iOS template.

  1. For the Agent queue, select a hosted macOS queue such as Hosted macOS, or the private queue that includes your macOS agent.

  2. For the Solution to build, enter HelloXamarinFormsWorld.sln.

  3. Remove the Xamarin Test Cloud task by right-clicking it and selecting Remove selected task(s).

  4. Select the Build Xamarin.iOS solution task. In the properties for this task, enable the Build for iOS Simulator check box.

  5. Click Save & queue to kick off the Xamarin.iOS build. On the Save build definition and queue dialog box, click Save & queue.

  6. A new build is started. You will see a link to the new build on the top of the page. Click the link to watch the new build as it happens.

View the build summary

  1. Once the build completes, select the build number to view a summary of the build.

    Navigate to build summary

  2. Notice the various sections in the build summary - the source version of the commit in build details section, list of all associated changes, links to work items associated with commits, and test results. When the build is automatically triggered by a push to your Git repository, these sections are populated with all the relevant information.

Next steps

To be able to configure your own app for iOS release, you need to make the following changes in the solution in your development environment, since the Xamarin.iOS build requires a solution configuration that builds only the Xamarin.iOS project and its dependencies.

  1. In Visual Studio, open Solution Explorer (Keyboard: Ctrl + Alt + L).

  2. Right-click your solution and then click Configuration Manager.

  3. On the configuration manager dialog box open the active solution configuration drop-down menu and click New.

  4. On the new solution configuration dialog box:

    • For Name, enter iOS Release

    • Open Copy settings from drop-down menu and select Release.

    • Clear the Create new project configurations dialog box.

  5. Open the Active solution platform drop-down menu:

    1. Select iPhoneSimulator and clear the check boxes on all rows except your Xamarin.iOS project and any projects (for example, portable class libraries) it depends on.

    2. Repeat this step for iPhone.

  6. File -> Save All (Keyboard: Ctrl + Shift + S).

  7. Check in your changes.

There's also a known issue that might cause a problem with building your Xamarin.iOS project. For example, in the build log for a Xamarin.iOS build task you might see an errors such as error : Project reference '../App1/App1.csproj' has invalid or missing guid for metadata 'Project'.

To fix this issue:

  1. In Visual Studio, open Solution Explorer (Keyboard: Ctrl + Alt + L).

  2. Expand your .iOS project node, and then the References node.

  3. Right-click each reference to a portable class library and then click Remove.

  4. Right-click the References node and then click Add Reference.

  5. On the Reference Manager dialog box, expand Projects, and then click Solution.

  6. Select the portable class library projects you removed and click OK.

  7. File -> Save All (Keyboard: Ctrl + Shift + S).

  8. Check in your changes.