Build your Xamarin app

Last Update: 7/12/2017

Team Services | TFS 2017 | TFS 2015 | Previous versions: XAML Build, Release

Xamarin enables you to develop a single solution and deploy it to Android, iOS, and Windows devices. After you define three CI builds, you can build the app whenever your team checks in code.

You no longer need a Xamarin license to build your Xamarin app. We're deprecating the Utility: Xamarin license task. We recommend that you remove this task from your build to avoid disruption when we remove the task from the product.

Prerequisites

  • Install Xamarin The Xamarin version on your dev machine and build agent machines must be at least 4.0.3 on your PC and 5.10.3. on your Mac.

Upload your code

Upload your Xamarin solution to Visual Studio Team Services or your on-premises Team Foundation Server. Either push your code to Git or check in your code to TFVC.

I don't have a Xamarin solution yet but I'd like to try this out.

Deploy your build agents

You'll need some agents to run your builds.

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

Define your Xamarin.Android build

  1. Open your team project in your web browser ▼

    Browse to team project
    • On-premises http://{your_server}:8080/tfs/DefaultCollection/{your_team_project}
    • Visual Studio Team Services https://{your_account}.visualstudio.com/DefaultCollection/{your_team_project}
  2. Create a build definition ▼

    Build tab
  3. On the Create new build definition dialog box, select Xamarin.Android and click Next.
  4. Select the repo, branch, and continuous integration.
  5. Select a default queue that includes a build agent that can build Xamarin.Android apps.

Variables

On the Variables tab:

Name Value
BuildConfiguration Release

Build steps

On the build tab:

Xamarin component restore
Package: Xamarin component restore

Restore Xamarin components for the specified solution.

  • Path to Solution: **/*.sln
    Note: Check the Enabled check box if your project uses Xamarin components.
Package: NuGet Installer
Package: NuGet Installer

Install your NuGet package dependencies.

  • Path to Solution: **/*.sln
icon
Build: Xamarin.Android

Build your Android project.

  • Project: **/*Droid*.csproj
    Note: In this example the name of the Android project ends with Droid.csproj. You can either follow a convention like this, or if you prefer, select the specific Android project you want to build.
  • Output directory: $(build.binariesdirectory)/$(BuildConfiguration)
  • Configuration: $(BuildConfiguration)
icon
Build: MSBuild

Build your tests.

Note: If you don't have tests yet, then clear the Enabled check box.
  • Project: **/*test*.csproj
  • Configuration: $(BuildConfiguration)
  • MSBuild Arguments: /p:OutputPath="$(build.binariesdirectory)\$(BuildConfiguration)\test-assembly\\"
icon
Test: Xamarin Test Cloud

Publish your test results to the Xamarin Test Cloud.

Note: If you have Xamarin UI tests to run in your Xamarin test cloud account, then check the Enabled check box.
  • App File: $(build.binariesdirectory)/$(BuildConfiguration)/*.apk
  • Test Assembly Directory: $(build.binariesdirectory)/$(BuildConfiguration)/test-assembly
  • For the other arguments, see Test: Xamarin Test Cloud.
icon
Android Signing

Sign and align your APK files.

  • APK Files: $(build.binariesdirectory)/$(BuildConfiguration)/*.apk
icon
Utility: Publish Build Artifacts

Publish your build artifacts.

  • Path to publish: $(build.binariesdirectory)/$(BuildConfiguration)
  • Artifact name: drop
  • Artifact type: Server

Define your Xamarin.iOS build

Configure the solution for iOS Release

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.

Fix portable class library (PCL) references in your solution

There's 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 step 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.

Create the definition

  1. Open your team project in your web browser ▼

    Browse to team project
    • On-premises http://{your_server}:8080/tfs/DefaultCollection/{your_team_project}
    • Visual Studio Team Services https://{your_account}.visualstudio.com/DefaultCollection/{your_team_project}
  2. Create a build definition ▼

    Build tab
  3. On the Create new build definition dialog box, select Xamarin.iOS and click Next.
  4. Select the repo, branch, and continuous integration.
  5. Select a default queue that includes build agent that can build Xamarin.iOS apps.

Variables

On the Variables tab:

Name Value
BuildConfiguration iOS Release

Build steps

On the build tab:

Xamarin component restore
Package: Xamarin component restore

Restore Xamarin components for the specified solution.

  • Path to Solution: **/*.sln
    Note: Check the Enabled check box if your project uses Xamarin components.
icon
Build: Xamarin.iOS

Build your Xamarin.iOS project.

  • Solution: Click the ... button and select your solution.
  • Configuration: $(BuildConfiguration)
  • Select either Create app package or Build for iOS simulator.

If you want to sign and provision, specify the arguments. See Build: Xamarin.iOS.

icon
Test: Xamarin Test Cloud

Publish your test results to the Xamarin Test Cloud.

Note: If you have Xamarin UI tests to run in your Xamarin test cloud account, then check the Enabled check box.
  • App File: **/*.ipa
  • Test Assembly Directory: your-solution-folder/your-xamarin-ui-test-folder/bin/$(BuildConfiguration)
  • For the other arguments, see Test: Xamarin Test Cloud.

Copy Files
  • Contents: **/*.ipa
  • Target folder: $(Build.ArtifactStagingDirectory)
icon
Utility: Publish Build Artifacts

Publish your build artifacts.

  • Path to publish: $(Build.ArtifactStagingDirectory)
  • Artifact name: drop
  • Artifact type: Server

Define your UWP build

Create a new UWP build definition.

Variables

On the variables tab:

Name Value
BuildConfiguration Release
BuildPlatform x86|x64|ARM

Build steps

On the build tab:

Package: NuGet Installer
Package: NuGet Installer

Install your NuGet package dependencies.

  • Path to Solution: **\*.sln
icon
Visual Studio Build

Build your app.

  • Solution: your-solution-folder/your-project-folder/your-project.csproj
  • MSBuild Arguments: Leave it set to the default:

    /p:AppxBundlePlatforms="$(BuildPlatform)" /p:AppxPackageDir="$(Build.BinariesDirectory)\AppxPackages\" /p:AppxBundle=Always
    

    Q: Why do I need these arguments? A:

    • /p:AppxBundlePlatforms="$(BuildPlatform)" The template is setup with BuildPlatform="x86|x64|ARM" so the bundle will include all three platforms.
    • /p:AppxPackageDir="$(Build.BinariesDirectory)\AppxPackages\\" Location where the bundle directories are created.
    • /p:AppxBundle=Always Always produce a bundle.
  • Platform: Leave it blank. (The bundle platforms are specified in the above MSBuild Arguments.)
  • Configuration: Leave it set to $(BuildConfiguration)

    Note: By default BuildConfiguration is set to release on the Variables tab. With the Universal Windows Platform, there is now a new native compiler that will improve the runtime performance of your app. With this change, it is highly recommended that you test your app in this compilation environment. By default, the Release build configuration enables the .NET native toolchain, so it is important to test your app with this Release configuration and check that your app behaves as expected.

  • Platform: Leave it blank.
  • Configuration: $(BuildConfiguration)
icon
Build: MSBuild

(Optional) Build your tests.

icon
Test: Visual Studio Test

(Optional) Run your tests.

Q&A

How do I create a Xamarin solution?

  1. In Visual Studio, File -> New Project -> Visual C# -> Cross-Platform -> Blank App (Xamarin.Forms Portable).

  2. Upload your code to Visual Studio Team Services or your on-premises Team Foundation Server. Either push your code to Git or check in your code to TFVC.

Where can I learn more to get started with Xamarin?

How do I discretely build my UWP app at the solution level?

If you want to build your UWP app at the solution level, you should first configure your solution so that you can restrict your CI process to building only the UWP project and its dependencies.

Configure the solution for UWP release

  1. In Visual Studio, right-click your solution and then click Configuration Manager.

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

  3. On the new solution configuration dialog box:

    • For Name, enter UWP Release

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

    • Clear the Create new project configurations dialog box.

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

    1. Select ARM and clear the check boxes on all rows except your UWP project and any portable class library (PCL) projects it depends on.

    2. Repeat this step for x64 and x86.

  5. Check in your changes.

Create the build definition

Create a new UWP build definition.

Add UWP Release to the variables

On the variables tab:

Name Value
BuildConfiguration UWP Release
BuildPlatform x86|x64|ARM

Modify the steps to build the solution

On the build tab:

Package: NuGet Installer
Package: NuGet Installer

Install your NuGet package dependencies.

  • Path to Solution: **\*.sln
icon
Visual Studio Build

Build your app.

  • Solution: **\*.sln
  • MSBuild Arguments: Leave it set to the default:

    /p:AppxBundlePlatforms="$(BuildPlatform)" /p:AppxPackageDir="$(Build.BinariesDirectory)\AppxPackages\" /p:AppxBundle=Always
    

    Q: Why do I need these arguments? A:

    • /p:AppxBundlePlatforms="$(BuildPlatform)" The template is setup with BuildPlatform="x86|x64|ARM" so the bundle will include all three platforms.
    • /p:AppxPackageDir="$(Build.BinariesDirectory)\AppxPackages\\" Location where the bundle directories are created.
    • /p:AppxBundle=Always Always produce a bundle.
  • Platform: Leave it blank. (The bundle platforms are specified in the above MSBuild Arguments.)
  • Configuration: Leave it set to $(BuildConfiguration)

    Note: By default BuildConfiguration is set to release on the Variables tab. With the Universal Windows Platform, there is now a new native compiler that will improve the runtime performance of your app. With this change, it is highly recommended that you test your app in this compilation environment. By default, the Release build configuration enables the .NET native toolchain, so it is important to test your app with this Release configuration and check that your app behaves as expected.

icon
Test: Visual Studio Test

(Optional) Run your tests.

What other kinds of apps can I build?

Build your app

What other kinds of build steps are available?

Specify your build steps

How do we protect our codebase from build breaks?

How do I modify other parts of my build definition?

I selected parallel multi-configuration, but only one build is running at a time.

If you're using Team Services, you might need more concurrent pipelines. See Concurrent build and release pipelines in Visual Studio Team Services.

How do I see what has changed in my build definition?

View the change history of your build definition

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.