Walkthrough: Including a NuGet in your project

How to include a NuGet package in a Xamarin Project

PDF for offline use:
Related Articles:
Related Links:

Let us know how you feel about this.


0/250
Thanks for the feedback!

last updated: 2016-09

This document covers how to include a NuGet package in a Xamarin project. It walks through finding and downloading a package, as well as introducing the IDE integration features.

Overview

NuGet is the most popular package manager for .NET development. It is built in to Xamarin Studio 5 and Visual Studio. You can easily search for and add packages to your project to Xamarin.iOS and Xamarin.Android using either IDE.

In this article, we’ll look at how to include a NuGet package in a project and demonstrate the tool chain that makes the process seamless.

Walkthrough

To demonstrate the NuGet functionality this article will walk-through the process of incorporating a package from NuGet into a Xamarin app. We’ll work with a project named HelloNuget, created from the Xamarin.iOS Single View Application template in Xamarin Studio or the HelloWorld Application template in Visual Studio respectively. The steps to include a NuGet package are the same irrespective of the project template used.

NuGet in Xamarin Studio

To demonstrate the NuGet package functionality we'll first walk through creating a new application and adding a package to it. Then we'll discuss the IDE features that help manage packages.

Create a New Project

First, create a project named HelloNuget as shown below (we're using the iOS Single View Application template, but any iOS or Android application project type would work):

Adding a Package

With the project loaded in Xamarin Studio, right-click on the Project in the Solution Pad and select Add Packages...:

This launches the Add Packages... window. When the window opens it will load a list of packages from the default package source: nuget.org. The initial results look like this:

List NuGet Packages

Use the search box in the top-right corner to find a specific package, for example ModernHttpClient. When you've found a package you wish to use, click the Add Package button to begin installation.

Add ModernHttpClient NuGet Package

Once the package has been download it will be added to your project. The solution will change in a few ways:

  • The References node will contain a From Packages section which can be expanded to see the assemblies that are part of a NuGet package.
  • A Packages node is added which lists each package you have downloaded. You can update or remove a package from this list (which will affect the project references as well).
  • A packages.config file will be added to the project. This XML file is used by the IDE to track which package version are referenced in this project. This file should not be hand-edited, but you should keep it in version control. Note that a project.json file can be used instead of a packages.config file. The project.json file is a new package file format introduced with NuGet 3 which supports transitive restore. More detailed information on project.json can be found in the [NuGet documentation](http://docs.nuget.org/consume/ProjectJson-Intro). The project.json file needs to be added manually and the project closed and re-opened before the project.json file is used in Xamarin Studio.

These changes are shown in the screenshot below:

Project References

Once the NuGet package has been added and the project references updated you can program against the APIs as you would with any project reference. In this example using ModernHttpClient I can simply add the required using statements:

using ModernHttpClient;
using System.Net.Http;

and then include a few lines in the view controller's ViewWillAppear override to demonstrate that the package works:

var httpClient = new HttpClient(new NSUrlSessionHandler());
var response = await httpClient.GetAsync ("http://xamarin.com/");
Console.WriteLine ("status: " + response.StatusCode);
Console.WriteLine (await response.Content.ReadAsStringAsync ());

This code is shown as an example - it doesn't do much except output an HTML string to the Console - however it shows how easy it is to install and then use a NuGet package in your apps.

Package Updates

Once one-or-more packages are added to a project, the Packages node will appear in the Solution pad. Right-click on Packages to access the context-sensitive menu:

Packages menu

  • Add Packages - Opens the window to add more packages to the project.
  • Update - Checks the source server for each package and downloads any newer versions.
  • Restore - Downloads any missing packages (without updating existing packages to newer versions).

Update and Restore options are also available at the Solution level, and affect all the projects in the solution. Individual packages can also be right-clicked to access a context menu:

Packages menu

  • Version Number - The version number is a disabled menuitem - it is not selectable, just provided for informational purposes.
  • Update - Checks the source server and downloads a newer version (if it exists).
  • Remove - Removes the package from this project and removes the relevant assemblies from the project's References.

NuGet in Visual Studio

NuGet package support is built-in to Visual Studio, and documentation for how to use it is available at docs.nuget.org.

To demonstrate the NuGet package functionality we'll first walk through creating a new application and adding a package to it. Then we'll discuss the IDE features that help manage packages.

Create a New Project

First, create a project named HelloNuget as shown below (we're using the Android Application template, but any iOS or Android application project type would work):

New Android Project

Adding a Package

With the project loaded in Visual Studio, right-click on the Project in the Solution Pad and select Manage NuGet Packages...:

Manage Nuget Packages

This launches the Manage Nuget Packages... window. When the window opens it will load a list of packages from the default package source: nuget.org. The initial results look like this:

List NuGet Packages

Use the search box in the top-right corner to find a specific package, for example ModernHttpClient. When you've found a package you wish to use, click the Install button to begin installation.

Add ModernHttpClient NuGet Package

Once the package has been download it will be added to your project. The solution will change in a few ways:

  • The References node will contain the assemblies that were added as part of the NuGet package.
  • A packages.config file will be added to the project. This XML file is used by the IDE to track which package version are referenced in this project. This file should not be hand-edited, but you should keep it in version control.

These changes are shown in the screenshot below:

Project References after adding NuGet

Once the NuGet package has been added and the project references updated you can program against the APIs as you would with any project reference. In this example using ModernHttpClient I can simply add the required using statements:

using ModernHttpClient;
using System.Net.Http; // don't forget to add assembly reference to Android project

and then include a few lines in the Activity's OnCreate override to demonstrate that the package works:

var httpClient = new HttpClient(new OkHttpNetworkHandler());
var response = await httpClient.GetAsync ("http://xamarin.com/");
Console.WriteLine ("status: " + response.StatusCode);
Console.WriteLine (await response.Content.ReadAsStringAsync ());

This code is shown as an example - it doesn't do much except output an HTML string to the Console - however it shows how easy it is to install and then use a NuGet package in your apps.

Package Updates

To check what version of a package is loaded, or to update to a newer version, right-click on a project to open the Manage NuGet Packages window.

Installed Packages

Select the Installed Packages node in the left column to see the list of packages used by the project. Clicking each package will display more information (including the version number) in the right column.

View NuGet Package Version

Updates

Select the Updates node in the left column to see the list of packages used by the project for which updates are available. Press the Update button next to each package to install the latest version.

Update NuGet Package to Latest Version

Adding Package Sources

Packages available for installation are initially retrieved from nuget.org, however you can add other package locations to the IDE. This can be useful for testing your own NuGet packages under development, or to use a private NuGet server inside your company or organization.

In Xamarin Studio, navigate to Xamarin Studio > Preferences > Packages > Sources to view and edit the list of package sources. Note that sources can be a remote server (specified by a URL) or a local directory. Click Add to set-up a new source.

Package Sources

Enter a friendly name and the URL (or file path) to the package source. If the source is a secure web server, enter the username and password as well.

Add a new source

Different sources can then be selected when searching for packages:

Choose a source

In Visual Studio, navigate to Tools > Options > NuGet Package Manager > Package Sources to view and edit the list of package sources. Note that sources can be a remote server (specified by a URL) or a local directory. Click the + (plus) button to set-up a new source.

Package Sources

Enter a friendly name and the URL (or file path) to the package source and press the Update button to save the changes. If the source is a secure web server, enter the username and password as well.

Add a new source

Different sources can then be selected when searching for packages:

Choose a source

Version Control

The NuGet documentation discusses using NuGet without committing packages to source control. If you prefer not to store binaries and unused information in source control, you can configure the IDE to automatically restore packages from the server. This means that when a developer retrieves the project from source control for the first time, the IDE will automatically download and install the required packages.

Automatically restore packages

Automatically restore packages

Refer to your particular source control documentation for details on how to exclude the packages directory from being tracked.

Summary

This document covered how to incorporate NuGet packages into a Xamarin application. It showed the IDE integration with NuGet, including searching and adding packages to a project.

It also discussed updating and restoring packages, and adding addition sources for package installation.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.