Using NuGets in Xamarin Components
Including NuGet packages in a Xamarin Component
- PDF for offline use
- Related Articles:
Let us know how you feel about this
last updated: 2017-03
This article shows how to reference a NuGet package inside a Xamarin Component and have that package loaded when the component is installed in a Xamarin Project.
Xamarin Components can reference one or more NuGet packages as a dependency and can have those packages installed (along with the component) when added to a Xamarin Project from the Xamarin Component Store.
This means a component can rely on 3rd party libraries (such as a JSON parser) without having to directly include that library in the component's bundle. By using this technique, the component can use a 3rd party library without having to worry about it conflicting with another component using the same library.
This also allows for a Xamarin Component to be nothing but an empty wrapper around a NuGet package. If the developer installs a Shell Component from the Xamarin Component Store, the backing NuGet package or packages will be installed and actually provide the functionality of the component.
This article will cover the steps required to modify an existing Xamarin Component Solution and include a NuGet package as a dependency. It will also cover creating a Shell Component as a wrapper around one or more NuGet packages.
To follow the steps outlined in this article, the following is required:
- xamarin-component Command Line Tool - The latest version of the xamarin-component Command Line Tool will be required to create a component bundle that relies on a NuGet package.
- NuGet - You must have NuGet version 2.8.3 (or greater) installed in Visual Studio for Mac or Visual Studio to be able to reference NuGet packages from inside a component bundle.
- Visual Studio - The latest version of Visual Studio should be installed and configured on the development computer.
The latest version of the xamarin-component Command Line Tool can be downloaded from here and should be unzipped in the same directory as the
.yaml file used to bundle the component for delivery to the Xamarin Component Store.
Adding a NuGet Package Dependency
As a working example, this section will look at modifying an existing Xamarin Component that relies on an embedded JSON parser and adjust it to use a reference to a NuGet version of the parser instead. While this is a specific example, the same steps apply to any functionality that the developer wants to add to a component using NuGet.
In the case of this example, this allows the Xamarin Component to be decoupled from the JSON parser so that conflicts won't arise if the developer tries to add to their project another component that relies on the same parser. Again, the same applies to any library or functionality being replaced by a NuGet Package.
So given the example of a Xamarin Component that uses the Newtonsoft JSON parser to work with JSON, let’s take a look at referencing a NuGet package inside a component.
The Newtonsoft JSON parser can be included in the component by right clicking on the component's project in the Solution Explorer and selecting Add > Add Packages...:
In the Add Packages dialog box, enter
newtonsoft.json in the search box and press Enter:
The developer can then place a check by the
Json.NET entry and click the Add Package button to include the parser. One thing to note here is the version of the NuGet package, as it will be required when creating the dependency later. For the example given above, the Json.NET version is 6.0.6 (as shown in the top right-hand corner of the dialog box).
Given the information above, if the developer is using the
component.yaml file to bundle their component, they would need to add the following lines to the file to create a dependency for the Newtonsoft JSON Parser:
packages: "": Newtonsoft.Json, Version=6.0.6
If they are manually building the component by using command line options instead, the developer would include the following option when calling the
xamarin-component command line tool:
NOTE: The developer must specify the specific version of the NuGet package and it must match the version installed in the component from the Add Packages dialog box above.
Because no target project type has been specified (eg.
"":), this Component will install the Newtonsoft.Json NuGet package into any Android, iOS or Windows Phone project that it is added to. To limit a dependency to a given project type, one of the following keywords can be used:
- android - The NuGet package will only be included in Xamarin.Android projects.
- mobile or "" - The NuGet package will be included in any mobile project (Android, iOS or Windows Phone).
- ios - The NuGet package will only be included in Xamarin.iOS projects.
For example, the following is a
component.yaml file that defines a complex set of dependencies:
packages: android: - NUnit, Version=2.6.2 - Newtonsoft.Json, Version=6.0.6 mobile: Ninject, Version=3.2.0 ios: log4net, Version=2.0.0
- Unit and Newtonsoft.Json are only installed for Xamarin.Android projects.
- Ninject is installed for any mobile project.
- log4net is only installed for Xamarin.iOS projects.
The same thing can also be achieved when manually building the component bundle by including the following command line options:
--package="android":"NUnit, Version=2.6.2" --package="android":"Newtonsoft.Json, Version=6.0.6" --package="mobile":"Ninject, Version=3.2.0" --package="ios":"log4net, Version=2.0.0"
Creating a Shell Component
A Shell Component is a special type of Xamarin Component that is essentially a wrapper around one or more NuGet packages. Shell Components only install the NuGet packages into a project, and do not add references to any assemblies in the Component’s
If using a
component.yaml file to bundle the component, the developer would add the following line to specify that the component is a Shell Component and define the NuGet package dependencies as normal:
If manually building the component from the
xamarin-component.exe command line tool, the following option would be used:
Again, the developer would define the NuGet package dependencies as normal by including
-package command line options.
Backwards Compatibility and Shell Components
The developer should consider backwards compatibility when creating a Shell Component. If the component is required to work with older versions of Visual Studio that do not support NuGet package dependencies, assemblies should also be included from the components
If the component is then installed on an older version of Visual Studio that does not support NuGet packages, the assemblies from the
lib directory will be used.
If the component is installed on a newer version of Visual Studio that supports NuGet package dependencies, the NuGet packages will be installed and used instead.
Compatible NuGet package Sources
Only NuGet packages that are available from the official NuGet Gallery can be added as dependencies to a Xamarin Component's bundle. Those that are in private repositories or a non-official gallery and ineligible to use.
If the developer wishes to test a NuGet package that has not yet been made publicly available in the official NuGet Gallery, they can add it to the local machine’s NuGet Cache Directory. Visual Studio should be able to access the NuGet package in the local NuGet cache instead of trying to download it from the NuGet Gallery.
Bundling and Submitting the Component
With the dependencies added to the
component.yaml or ready to be added as command line options if manually building or building using a
Makefile, the developer is ready to bundle the component to be submitted to the Xamarin Component Store.
Before bundling the component, ensure that the latest version of the xamarin-component Command Line Tool has been downloaded from here and has been unzipped into the same directory as the
With all of these changes in place, the developer submits the component as normal by issuing either of the following commands in the Terminal:
- Windows -
xamarin-component.exe package <foldername>
- Mac -
mono xamarin-component.exe package <foldername>
If manually building the component package, the developer would use the command line tool
xamarin-component.exe with one or more of the options specified above and upload the resulting bundle to the Xamarin Component Store using the web based interface.
See the Component Store Submission Guide document for more information on submitting a component.
Installing the Component
When an end developer installs a Xamarin Component with NuGet dependencies into a project, the NuGet packages specified will be installed and a reference will be added to the assemblies in the
lib directory of the Component. In older versions of Visual Studio, the NuGet package will not be installed and instead the project will reference the .DLLs which are included with the Component.
From that point on, the component behaves as any other component that has been included in the Xamarin Project and is used as normal.
Working with Package Dependencies
The NuGet packages that a Component depends on are displayed in the Packages tab of the Component Details page. This page can be displayed by double clicking the Component in the Solution Explorer, or by right clicking the Component and selecting Details:
When the Component was added to the project, the NuGet package was also installed:
If the NuGet package is removed, or failed to install for some reason, the component will be displayed in red in the Solution Explorer and a warning will be shown by the package's version in the Packages tab of the Component Details page:
If the developer hovers the mouse over the warning icon, they will be given the option to install the missing NuGet package:
They can click the Add Package button to include the missing package in their Xamarin Project.
This article has shown how to take an existing Xamarin Component and include a NuGet package dependency that will be installed along side the component when it is included in a Xamarin Project. It has also show how to create a Shell Component that acts as a wrapper around one or more NuGet packages instead of including functionality directly in the Xamarin Component.