Walkthrough: Including a Component in your project

How to include a Component in a Xamarin Project

This document covers how to include a component from the Xamarin Component Store in a project. It walks through connecting Xamarin Studio or Visual Studio to a Xamarin account, as well as downloading and including a component using the IDE integration features.

Overview

Xamarin Components provide a variety of different components to use in Xamarin.iOS and Xamarin.Android applications. Components range from user interface controls to code libraries, as well as user interface themes. They allow applications built on Xamarin to create rich user experiences and integrate with many different third party services with very little work.

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

Walkthrough

Let’s walk through the process to incorporate a component from the Xamarin Components Store. For this walkthrough, we’ll work with a project named HelloComponents, created from the Xamarin.iOS Single View Application template in Xamarin Studio or the HelloWorld Application template in Visual Studio respectively. However, the steps to include a component are the same irrespective of the project template used.

Using the Component Store from Xamarin Studio

Creating a New Project

First, create a project named HelloComponents as shown below for Xamarin Studio. The project below is a Xamarin.iOS project, but you can use a Xamarin.Android project if you wish:

Launching the Component Manager

With the project loaded in Xamarin Studio, launch the Xamarin Components Manager by either double-clicking on the Components folder in the Solution Pad, or by right-clicking on the Components folder and selecting Get More Components:

The Component Manager is where all previously downloaded components are displayed. The first time the Component Manager opens, no components will have yet been added, so it shows default screen below:

Logging into the Component Store

Accessing the Components Store requires a Xamarin Store account. To log in from the Component Manager, click the Login to your Xamarin Account button in the upper right. This will launch the account dialog, allowing you to log in:

Using the Component Store from Visual Studio

Login to Xamarin Account

To use Xamarin.iOS from Visual Studio, the workflow is a bit different than from Xamarin Studio, as it requires being connected to a Xamarin Account before creating an iOS project. To log in to a Xamarin account, select Tools > Xamarin Account from the main menu in Visual Studio, and then enter your credentials in the Xamarin Account dialog.

After logging in, the browser shows the following message indicating the account is successfully connected and Xamarin.iOS is ready to use from Visual Studio:

Create New Project

After logging in to a Xamarin account, create a new iOS project by selecting File > New > Project. Select the HelloWorld Application template under the iOS > iPhone section and name the project HelloComponents, as shown below:

Launching the Component Manager

With the project created, right-click on the Components folder in the Solution Explorer and select Get More Components:

This loads the Components List shown below:

Xamarin Components List

After connecting to the Component Store in either Xamarin Studio or Visual Studio, a window, similar to the one below, opens to show all the components available in the Component Store:

From this window we can:

  • Search for components by name.
  • Filter components by category and tag.
  • Sort components by whether they are featured, number of downloads and name.
  • Make suggestions for components.
  • Submit components.
  • Select a component to include in a project.

Including a Component

Let’s include the Alert Center Component. Use the search box to locate it, and double-click on the Alert Center component in the list to open the component’s page:

From the component page, select the Add to App button to download the component and add it to the current project. When the download completes, the component will be displayed under the Components folder in the Solution Pad, with a screen showing details about the component loaded in the tabbed section of Xamarin Studio.

In Visual Studio, double-click the component in the Solution Explorer in Visual Studio to show the detail screen:

Component Detail Screen

The detail screen under the tab includes the following sections:

  • Getting Started – Code snippets to get started using the component.

  • Samples – Sample projects that use the component, which can be added to the current solution.

  • Assemblies – Assemblies included with the component.

Adding Component Code

Let’s use the code sample from the Getting Started tab to add the Alert Center component to our project.

In the ViewController class, first add the following using directive:

using Xamarin.Controls;

Then, add the following code to the ViewDidLoad method:

public override void ViewDidLoad ()
{
    base.ViewDidLoad ();

    AlertCenter.Default.PostMessage ("Knock knock!", "Who's there?");
    AlertCenter.Default.PostMessage ("Interrupting cow.", "Interrupting cow who?",
                                UIImage.FromFile ("cow.png"), delegate {
        Console.WriteLine ("Moo!");
    });
}

Also add an image named cow.png, which the AlertCenter code above will display in the alert. In lieu of creating an image, there is a cow.png in the sample code that accompanies this article that can be used.

With the code and images above added, running the application now displays an alert as shown below:

Images/demo.png

Configuring the Components Directory

It is possible to configure the directory where Xamarin components will be extracted to before being referenced by a project, within your solution. This allows multiple solutions to use the same directory and prevents the assembly references from being modified within the context of different solutions.

To configure the components directory, a components.config file will need to be created if it doesn't already exist. This file should contain the following information:

<components>
     <config>
        <add key="cachePath" value="..\Components"></add>
    </config>
 </components>

Where value is the path to the components directory you wish to point to.

When a solution is opened Xamarin Studio will check for a components.config file in several locations based on the solution's directory. Consider if the solution is in the directory /Users/myusername/Projects/AwesomeApp/, then the full list of locations checked is as follows, in order:

  1. /Users/myusername/Projects/AwesomeApp/.components/components.config
  2. /Users/myusername/Projects/AwesomeApp/components.config
  3. /Users/myusername/Projects/components.config
  4. /Users/myusername/components.config
  5. /Users/components.config
  6. /components.config
  7. ~/Library/Preferences/Xamarin/Components/components.config [Mac]
    • %AppData%\Xamarin\Components\components.config [Windows]

If the components.config file is placed in a directory with a number of solutions, all solutions will be able to access and use this common file. If no file is available, then the default components directory will be used.

For more detailed information on this topic, please refer to Matt Ward's blog post detailing Xamarin components directory configuration.

Summary

This document covered how to use the Xamarin Component Store to incorporate a component into an application. It showed the IDE integration with the Component Store as well as features of the store itself, such as searching and filtering, which make finding the right component a breeze. It also showed how to download and include a component with a single click, as well as using the code provided with a component to get up and running quickly. Finally, it touched on how to confiure the components directory in Xamarin Studio.