Build and deploy Xamarin apps with a pipeline
Azure DevOps Services
Get started with Xamarin and Azure Pipelines by using a pipeline to deploy a Xamarin app. You can deploy Android and iOS apps in the same or separate pipelines.
Prerequisites
Have the following items:
- An Azure account with an active subscription. Create an account for free.
- An active Azure DevOps organization. Sign up for Azure Pipelines.
Get code
Fork the following repo at GitHub:
https://github.com/MicrosoftDocs/pipelines-xamarin
This sample is the FirstApp
sample from the https://github.com/xamarin/xamarin-forms-samples
repository. For more information on getting started with Xamarin, see Build your first Xamarin.Forms App.
Sign in to Azure Pipelines
Sign-in to Azure Pipelines. After you sign in, your browser goes to https://dev.azure.com/my-organization-name
and displays your Azure DevOps dashboard.
Within your selected organization, create a project. If you don't have any projects in your organization, you see a Create a project to get started screen. Otherwise, select the New Project button in the upper-right corner of the dashboard.
Create the pipeline
Sign-in to your Azure DevOps organization and go to your project.
Go to Pipelines, and then select New pipeline.
Do the steps of the wizard by first selecting GitHub as the location of your source code.
You might be redirected to GitHub to sign in. If so, enter your GitHub credentials.
When you see the list of repositories, select your repository.
You might be redirected to GitHub to install the Azure Pipelines app. If so, select Approve & install.
On the Configure tab, select Xamarin.Android to build an Android project or Xamarin.iOS to build an iOS project. If you want to use the included sample
.yml
files, choose Existing Azure Pipelines YAML file and choose from one of the included sample pipelines (Android, iOS, or a combined pipeline that builds both).When your new pipeline appears, take a look at the YAML to see what it does. When you're ready, select Save and run.
If you created a new YAML file, commit a new azure-pipelines.yml file to your repository. After you're happy with the message, select Save and run again.
If you want to watch your pipeline in action, select the build job. You now have a working YAML pipeline (
azure-pipelines.yml
) in your repository that's ready for you to customize!When you're ready to make changes to your pipeline, select it in the Pipelines page, and then Edit the
azure-pipelines.yml
file.
Read further to learn some of the more common ways to customize your pipeline.
Set up Xamarin tools
You can use Azure Pipelines to build your Xamarin apps without setting up your own infrastructure. Xamarin tools are preinstalled on Microsoft-hosted agents in Azure Pipelines. You can use macOS or Windows agents to run Xamarin.Android builds, and macOS agents to run Xamarin.iOS builds. If you're using a self-hosted agent, install either of the following tools:
- Visual Studio Tools for Xamarin for Windows agents
- Visual Studio for Mac for macOS agents
For the exact versions of Xamarin that are preinstalled, refer to Microsoft-hosted agents.
Create a file named azure-pipelines.yml in the root of your repository. Then, add the following snippet to your azure-pipelines.yml
file to select the appropriate agent pool:
# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xamarin
pool:
vmImage: 'macOS-10.15' # For Windows, use 'windows-2019'
Build a Xamarin.Android app
To build a Xamarin.Android app, add the following snippet to your azure-pipelines.yml
file. Change values to match your project configuration. For more information about options, see the Xamarin.Android task.
variables:
buildConfiguration: 'Release'
outputDirectory: '$(build.binariesDirectory)/$(buildConfiguration)'
steps:
- task: NuGetToolInstaller@1
- task: NuGetCommand@2
inputs:
restoreSolution: '**/*.sln'
- task: XamarinAndroid@1
inputs:
projectFile: '**/*Droid*.csproj'
outputDirectory: '$(outputDirectory)'
configuration: '$(buildConfiguration)'
msbuildVersionOption: '16.0'
Sign a Xamarin.Android app
For information about signing your app, see Sign your mobile Android app during CI.
Build a Xamarin.iOS app
To build a Xamarin.iOS app, add the following snippet to your azure-pipelines.yml
file. Change values to match your project configuration. For more information about options, see the Xamarin.iOS task.
variables:
buildConfiguration: 'Release'
steps:
- task: XamariniOS@2
inputs:
solutionFile: '**/*iOS.csproj'
configuration: '$(buildConfiguration)'
packageApp: false
buildForSimulator: true
Sign and provision a Xamarin.iOS app - The PackageApp option
To generate a signed and provisioned Xamarin.iOS app .ipa package, set packageApp
to true
. Make sure you already installed the right Apple Provisioning Profile and Apple Certificates that match your App Bundle ID into the agent running the job.
To fulfill these mandatory requisites, use the Microsoft Provided tasks for installing an Apple Provisioning Profile and installing Apple Certificates.
- task: XamariniOS@2
inputs:
solutionFile: '**/*iOS.csproj'
configuration: 'AppStore'
packageApp: true
Tip
The Xamarin.iOS build task only generates an .ipa package if the agent running the job has the appropriate provisioning profile and Apple certificate installed. If you enable the packageApp option and the agent doesn't have the appropriate apple provisioning profile(.mobileprovision) and apple certificate(.p12) the build may succeed, but the .ipa isn't generated.
For Microsoft Hosted agents, the .ipa package is by default located under the following path:
{iOS.csproj root}/bin/{Configuration}/{iPhone/iPhoneSimulator}/
You can configure the output path by adding an argument to the Xamarin.iOS task:
- task: XamariniOS@2
inputs:
solutionFile: '**/*iOS.csproj'
configuration: 'AppStore'
packageApp: true
args: /p:IpaPackageDir="/Users/vsts/agent/2.153.2/work/1/a"
This example locates the .ipa in the Build Artifact Staging Directory. It's ready to get pushed into Azure DevOps as an artifact to each build run. To push it into Azure DevOps, add a Publish Artifact task to the end of your pipeline.
For more information about signing and provisioning your iOS app, see Sign your mobile iOS app during CI.
Set the Xamarin SDK version on macOS
To set a specific Xamarin SDK version to use on the Microsoft-hosted macOS agent pool, add the following snippet before the XamariniOS
task in your azure-pipelines.yml
file. For details on properly formatting the version number (shown as 5_4_1 below), see How can I manually select versions of tools on the Hosted macOS agent?.
- script: sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1
displayName: 'Select Xamarin SDK version'
Build Xamarin.Android and Xamarin.iOS apps with one pipeline
You can build and test your Xamarin.Android app, Xamarin.iOS app, and related apps in the same pipeline by defining multiple jobs in azure-pipelines.yml
. These jobs can run in parallel to save time. The following complete example builds a Xamarin.Android app on Windows, and a Xamarin.iOS app on macOS, using two jobs.
# Xamarin.Android and Xamarin.iOS
# Build a Xamarin.Android and Xamarin.iOS app.
# Add steps that test, sign, and distribute the app, save build artifacts, and more:
# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xamarin
jobs:
- job: Android
pool:
vmImage: 'windows-2019'
variables:
buildConfiguration: 'Release'
outputDirectory: '$(build.binariesDirectory)/$(buildConfiguration)'
steps:
- task: NuGetToolInstaller@1
- task: NuGetCommand@2
inputs:
restoreSolution: '**/*.sln'
- task: XamarinAndroid@1
inputs:
projectFile: '**/*droid*.csproj'
outputDirectory: '$(outputDirectory)'
configuration: '$(buildConfiguration)'
msbuildVersionOption: '16.0'
- task: AndroidSigning@3
inputs:
apksign: false
zipalign: false
apkFiles: '$(outputDirectory)/*.apk'
- task: PublishBuildArtifacts@1
inputs:
pathtoPublish: '$(outputDirectory)'
- job: iOS
pool:
vmImage: 'macOS-10.15'
steps:
# To manually select a Xamarin SDK version on the Hosted macOS agent, enable this script with the SDK version you want to target
# https://go.microsoft.com/fwlink/?linkid=871629
- script: sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1
displayName: 'Select Xamarin SDK version'
enabled: false
- task: NuGetToolInstaller@1
- task: NuGetCommand@2
inputs:
restoreSolution: '**/*.sln'
- task: XamariniOS@2
inputs:
solutionFile: '**/*.sln'
configuration: 'Release'
buildForSimulator: true
packageApp: false
Clean up resources
If you don't need the example code, delete your GitHub repository and Azure Pipelines project.
Next steps
Feedback
Submit and view feedback for