A great way to explore Xamarin.Forms (and grow comfortable working in the code) is to clone the repository and run it, especially any of the ControlGallery projects. We know that many of you have done just that, so the next step you can take is to make your own customizations to Xamarin.Forms to build and distribute your very own NuGet package within your organization. In this post, let’s walk through doing that locally, and then discuss how you can configure the same on Visual Studio Team Services (VSTS).

The Local Setup

Windows to Build it All

Building a Xamarin.Forms Nuget locally is most easily done on a Windows machine. You’ll want to use Visual Studio 2015 if you’re including the soon-to-be-deprecated Windows Phone 8 and 8.1, or you can use Visual Studio 2017. The build is quite straight forward:

  1. Select Debug or Release
  2. Right click the solution and select Build.

I can hear you asking, “But what about a Mac build host, do I need one?” because I asked the very same question my first time. Because we’re generating a NuGet and not an iOS or Mac application, we don’t need the Mac build host. We’re building against the Xamarin and Windows framework SDKs.

Once the solution is done building successfully, you should generate the xml used for displaying documentation within the IDE. Now you’re ready to package the freshly made assemblies into a NuGet package. To accomplish this, we have a handy create-nuget.bat script that you execute from the command line by name.

You can update this directly to use the version and build configuration of your choice. Note, the current script is set to expect the debug configuration. Also, notice the docs are being updated first and then the NuGet is being generated.

The NuGet package will be in your root directory when it’s complete.

Building on OS X

While you can build Xamarin.Forms on a Mac, I don’t recommend it. You immediately have to trim out all the Windows targets, meaning any NuGet you create will only work on iOS, Android, and Mac. If you are on a Mac and cannot build on a Windows machine, then building on VSTS is for you!

Cloud Building on VSTS

Visual Studio Team Services provides a wealth of tasks to create a very flexible build solution, and for our needs it will:

  • Get Xamarin.Forms Source
  • Restore NuGet packages
  • Build the solution
  • Generate the documentation
  • Package the NuGet
  • Publish it

Sounds easy enough, right?

First things first, we need a project on VSTS. Click New Project from your VSTS landing page and fill in your preferences. Once that’s created, go to the Build & Release tab for the project. Create a new Build definition and start adding those tasks!

Get Xamarin.Form Source

VSTS provides templates for a variety of common scenarios, but we’ll start with an Empty process. For the “Default agent queue” select Hosted.

There’s one task provided for us, and that’s Get Sources. Choose that task and configure from where you want to pull your Xamarin.Forms code.

  • This project
  • Github
  • Remote repo
  • Subversion

Restore NuGet Packages

As usual, before we can build any solution including Xamarin.Forms, you want to make sure any NuGet dependencies have been restored. Visual Studio kindly does this for you by default when running a build locally.

Click Add Task and add the “NuGet” task. Change to 0.* in the Version drop down for the task. This provides the ability to customize NuGet arguments more easily. For the “Path to Solution” enter “Xamarin.Forms.sln” since it’s in the root of the repository.

Make sure the “Installation type” is set to Restore.

Include these arguments:

Build The Solution

Now we’re ready to build the solution. Add another task and this time choose “Visual Studio Build”. Again, point to the “Xamarin.Forms.sln”. Add variables you can change depending on what you want to build in the Platform and Configuration fields.

Platform: $(BuildPlatform)
Configuration: $(BuildConfiguration)

When you kick off the build later, these will be options you can set.

Check the Clean box.

Generate The Documentation

Build all the appropriate xml files needed by the IDEs to display documentation. To do this you’ll need one Batch Script and three Command Line tasks. You’ve already mastered finding tasks and adding them to the process, so let’s forgo repeating that. Here are the settings for those tasks.

Batch Script
Display Name: Update XML Documentation
Path: update-docs-windows.bat

Command Line
Display Name: Generate XML Documentation (Core)
Tool: $(Build.SourcesDirectory)\tools\mdoc\mdoc.exe
Arguments: export-msxdoc -o Xamarin.Forms.Core.xml Xamarin.Forms.Core
Working Folder: docs

Command Line
Display Name: Generate XML Documentation (XAML)
Tool: $(Build.SourcesDirectory)\tools\mdoc\mdoc.exe
Arguments: export-msxdoc -o Xamarin.Forms.Xaml.xml Xamarin.Forms.Xaml
Working Folder: docs

Command Line
Display Name: Generate XML Documentation (XAML)
Tool: $(Build.SourcesDirectory)\tools\mdoc\mdoc.exe
Arguments: export-msxdoc -o Xamarin.Forms.Maps.xml Xamarin.Forms.Maps
Working Folder: docs

Package The NuGet

Finally, the step you’ve been waiting so patiently for! Add a “NuGet Packager” task and configure it.

Version 0.*
Patch to the nuspec: .nuspec/Xamarin.Forms.nuspec
Configuration to Package: $(BuildConfiguration)
Addition build properties: IdAppend=.Custom

Publish the NuGet

Perhaps you want to publish to a MyGet feed you control. You can do that here. For simplicity, let’s just put the package in a folder in the VSTS project. Add a task for Publish Build Artifacts.

Get Building

Save and queue your build. From the Builds tab you can access the build history and see your job’s status, any errors, etc.

Ready. Set. Build.

Now you’re all set to build Xamarin.Forms and distribute within your own organization! If you don’t already have a VSTS account, sign up to get started for free. Of course, if you’re making fixes or customizations that everyone can benefit from, please open a pull request on GitHub and share the love.