HowToNuGetXA.md

This post is to explain how to setup and use NuGet in Xamarin Studio and use NuGet packages in your Xamarin.Android project. I'll also explain how to create NuGet packages for Xamarin.Android too.

NuGet, since version 2.5, supports Xamarin.Android and Xamarin.iOS as its "target framework", as well as other targets such as .NET 4.x, Silverlight, Windows Phone and so on.

The same should apply to Xamarin.iOS, so just replace "Android" part with "iOS".

Using NuGet Packages in Your Project

NuGet Package Manager Addin for MonoDevelop

This section only applies to Xamarin Studio. Those who only use Visual Studio can skip this section.

By default, Xamarin Studio cannot handle NuGet packages by itself. There is a NuGet support addin created by Matt Ward, which is available at GitHub

It is also explained at its README.md, but for convenience I copy the addin repository URL here too:

http://mrward.github.com/monodevelop-nuget-addin-repository/4.0/main.mrep

To install the addin from the repository, open Add-in Manager from the main menu, then go to Gallery tab, then open the dropdown list for Repository and select "Manage Repositories..." to open Addin Repository Management dialog.

There you can "Add" the URL above (click the button to show the "Add New Repository" dialog and enter the URL). Now you can see "NuGet Package Manager" under "IDE extensions" node on the Gallery tab.

Adding NuGet Packages to Your Project

Once the addin is successfully installed, you'll be able to add NuGet packages in your projects. Open your project's context menu, and select the menu item "Manage NuGet Packages..." to actually manage the packages. This is exactly the same workflow as Visual Studio 2012.

The default tabpage ("Available") will come up with a lot of available packages. You can search some specific packages to install.

Once you added some packages, all the packaged references will be added. You can remove the package and subsequently those references by removing the package from the same manager dialog.

You can also configure NuGet package sources from Xamarin Studio Options (if you have a working addin, it will add a new "NuGet" section), but you most likely don't have to check that so far.

Creating and Publishing a Package for Xamarin.Android

Now that we have done with "how to consuming NuGet packages" part, it's time to discover how to create a package. Basically you should go to NuGet documentation page and read the details.

Build and Run NuGet on Non-Windows platform

Here we are going to explain how to build and run NuGet on non-Windows platform (which means Mac OS X for Xamarin product, but common to Linux etc. if you want to use NuGet for desktop). If you are using Windows, you can simply use Visual Studio and create a NuGet package project, or download and use NuGet standalone tools. So here I skip explaining about them. Note that you still need NuGet 2.5 or higher, which is fairly up to date version as of 2013.

NuGet standalone executable is published at the CodePlex project so you can just go there and grab NuGet.exe instead of building it.

You can also build NuGet from source, but there is no source archive, so you will have to checkout sources from there. It uses Git. Also you are supposed to have a working Mono setup.

Once you successfully checked out sources, go to the checkout top directory and run:

./build.sh

It will result in some build errors, but the only thing you need is a working command line tool, so you can ignore them. In case you hate errors, try this patch.

Once it's done, try running NuGet.exe:

mono src/CommandLine/bin/Release/NuGet.exe

If it prints usage, then success! Now you can run it.

NuGet Version: 2.7.0.0
usage: NuGet <command> [args] [options] 
Type 'NuGet help <command>' for help on a specific command.

Available commands:

(snip...lengthy usage follows)

Writing Package.nuspec file

For ease of explanation, I simply write "nuget" to represent command invocation for NuGet.exe, which is simply "nuget" on Windows (PATH is supposed to be configured to include the directory), or "mono /path/to/NuGet.exe" on non-Windows.

Once you got a working NuGet, the next step you need to do is to create a package specification, which is an XML file and typically a file with ".nuspec" extension.

You can create a new simple .nuspec template by running:

nuget spec

It creates a file named Package.nuspec. The content of it looks like:

<?xml version="1.0" encoding="utf-8"?>
<package >
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>yourname</authors>
    <owners>yourname</owners>
    <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2013</copyright>
    <tags>Tag1 Tag2</tags>
    <dependencies>
      <dependency id="SampleDependency" version="1.0" />
    </dependencies>
  </metadata>
</package>

All you need to do to create the final package description is to alter the contents of those elements, and some additional tasks:

• Add a "frameworkAssemblies" element as a child of "metadata" element and list all depedencies, like this (note that all those "frameworkAssembly" elements have "targetFramework" attribute that specifies "MonoAndroid"):

    <frameworkAssemblies>
      <frameworkAssembly assemblyName="System.Core" targetFramework="MonoAndroid" />
      <frameworkAssembly assemblyName="Mono.Android" targetFramework="MonoAndroid" />
      <frameworkAssembly assemblyName="Mono.Android.Support.v4" targetFramework="MonoAndroid" />
    </frameworkAssemblies>
  

• Add a "files" element as a child of "package" element and list all files to package, like this (note that the "file" element contains "target" attribute which specifies "lib/MonoAndroid", which is the expected value for our profile):

  <files>
    <file target="lib/MonoAndroid" src="ActionBarSherlock/bin/Debug/ActionBarSherlock.dll" />
  </files>
  

For .nuspec description details, check Nuspec Reference on the NuGet website.

Creating and Publishing a NuGet Package

Once you created a valid .nuspec, you are mostly done with packaging it. To finish this step, just run:

nuget pack path/to/your.nuspec

If it is successfully done, NuGet will generate a ".nupkg" file, which is the NuGet package for you.

The final step is publishing it on nuget.org. The publishing procedure is exactly identical to ordinal NuGet packaging, so just go to NuGet.org and follow "Upload Package" link (you will be asked to log on or create an account).

We are not going to duplicate existing documentation. The web instruction is easy to follow.

Once you have finished uploading, your package will show up as an ordinal NuGet package. You should be able to search your own package on the NuGet Package Manager dialog we explained earlier.