Xamarin Component Submission Guide

PDF for offline use

Let us know how you feel about this


0/250

The Component Store was launched in March 2013, as part of the Xamarin 2.0 launch, with the aim of helping developers get their apps built faster and to add great features without a lot of work. The store has a catalog of stunning UI controls, charts and graphs, beautiful themes, cloud services, and other powerful features that you can add to your app in minutes. The Component Store is integrated into both Xamarin Studio and Visual Studio so that components can be added to your app with just a few clicks. This document gives you an in depth look at the process of creating a component and provides all the information needed to build, bundle and submit your components to the Xamarin Component store.

Overview

These guidelines are to assist you when submitting your component so that you are able to steer clear of any pitfalls and make sure that your submission will be approved as quickly as possible. We want you to be proud of your component, and hopefully following these guidelines will go some way in helping you achieve that. We want users of your component to be excited using it in their app. We want the Xamarin Component Store to build better relationships between the Xamarin/C# community.

This document is by no means exhaustive. As we review components, inevitably new questions will be presented, and these guidelines will be updated accordingly.

Always use your best judgement when submitting a component, but if you do have any questions, please email us!

Terms and Conditions

  • Xamarin pays 70% of net component revenue to vendors within 30 days of the end of each calendar month.
  • Vendors must provide 30-day notice on price changes and must honor Xamarin's 30-day return policy.
  • Vendor licenses must allow library distribution as part of end-user apps without hidden fees or royalties.
  • You can read the full agreement for complete details.

Legal Requirements

  • Your code must comply with all laws that apply to you in your location. It is up to you to know what they are, and whether your code complies or not.
  • You must own, or have full rights to, all of the intellectual property that you include in your component package.
  • We trust that your component does NOT misrepresent itself, or mislead people as to its purpose or its origin.
  • We won’t approve components that induce or entice other people to commit crimes or endanger themselves or others.

Platform Stores

Developers using your component should not have to worry about their apps getting rejected because of your code, therefore:

Component Creation and Preparation

A Xamarin component can be anything that could be usable or rather re-usable by a developer using Xamarin. This can be UI functionality, extension libraries or themes.

Structure

Your component is typically split into three separate elements.

  • Core Elements
    • Your core component code and libraries
  • Sample Applications
    • Sample applications for providing developer examples of how to use and integrate your component in to their projects
  • Component Package
    • The package that you will submit to Xamarin to show up on the component store. This will includes your core libraries, sample apps, screenshots and documentation.

xamarin-component.exe

This command line tool can be used for creating a base folder structure for your code and files for your component.

It will also create a Component.yaml file which will store details of your component, files to be included and allow you to package it all up nice and easily for submission to Xamarin.

Follow these steps to create a new folder with these template files and details.

  1. Download the xamarin-component.exe from Xamarin here: https://components.xamarin.com/submit/xpkg and extract it.
  2. Use the xamarin-component.exe to create the base structure by typing the following into the console/terminal where is the base folder for your component.
    Note that you will need to change path to the location where the xamarin-component.exe was extracted.
    Windows: xamarin-component.exe create <foldername>
    Mac: mono xamarin-component.exe create <foldername>
  3. You will be asked to answer some questions about your component, which will be used to pre-populate some of the values in the Component.yaml file. Answer each one and continue through to the end.
  4. A folder will be created with the name you selected, and within that you will find a “Component” folder with some template files.

Folder Structure

When preparing to build your component, getting the right structure of your files can make a big difference in making it easier it to maintain, update and submit.

Below is an example folder structure that allows the elements in your component to be clearly defined but also makes the packaging and submission process simpler. It will also allow you make use of some the special features of xamarin-component.exe when building the .xam file, which can make it easier to build and test the samples.

Having just used xamarin-component.exe to build the skeleton folder structure with the template files, you can now create the additional folders(src, samples and docs) alongside the main ‘component’ folder.

  • component
    • Component.Yaml
    • Details.md, GettingStarted.md, Icons, Screenshots etc
  • src
    • Source code of your component
  • samples
    • iOS
    • Android
    • WindowsPhone

The ‘src’ folder is where your main component code will go. By default it will not be included in your package, but you can do so if you wish by using the “source” tag.

The ‘samples’ folder will store your sample projects used to demonstrate the features of your component. When building your samples you should add the project files from the src folder and build against them when designing your sample. This will give you the benefit of being able to design and debug your component as you go, but also will allow xamarin-component.exe to relink the references during the packaging phase. This process is discussed in the Component Elements section below.

Creating the Component

Create a solution that will contain your component source code projects and save it to the 'src' folder. Move the projects that make up your component in to the same 'src' folder and add them in to the main solution.

By seting up your projects in this way you can get xamarin-component.exe to build the source as part of the packaging process, rather than requiring the DLLs to be build first.

If you have any dependencies that aren’t available in the component store or require specific versions then copy these into the relevant 'bin' folders. You can then reference them from your sample apps. You can also link your code and samples to other Components within the store, which will be automatically downloaded when the samples are run.

When you create your core code make sure you follow the review guidelines detailed in our Component Review Guidelines.
This will ensure you meet our review criteria first time and this will speed up the approval process, meaning we can get your component on the store as soon as possible.

Sample Applications

Once you have created your core code you must provide a sample application for each of your supported platforms.

There are several reasons to provide a sample application with your component, the main ones are listed below:

  • A sample application can be used to showcase the abilities of your component and let developers know what it can do.
  • It makes it easy for potential customers/developers to see examples of how to use your component and how easy it is for them to integrate your component in to their projects.
  • You can use the sample application as the basis for your videos and screenshots.

The best way to prepare a sample application is by creating a new app for each platform you wish to support, and then add your core code as a reference within it. This ensures that the correct build configurations are created and it will reduce the chances of something not working as expected when you package your component and submit it to Xamarin.

When linking your samples to your main component code, we recommend loading the source project files(.proj) in to your samples’ solution and referencing them in the sample project. This will allow xamarin-component.exe to reset the references during the packaging phase to point to the bundled DLL’s that will be included in the .xam file.

We have no specific requirements for what the sample applications should do or show, but they should provide a good use case for your core libraries. The idea is to demonstrate to potential customers how to use your component and what it’s capabilities are.

Creating a sample

Use Xamarin Studio or Visual Studio to create a new Solution for the sample application on each platform you wish to support. These should be created in the relevant sub-folder of the samples folder.

Once the solution is created, add the source project files and reference them from your sample application. As long as the output from the source projects are referenced in the component.yaml file, xamarin-component.exe will update your sample solution to point to the DLLs in the relevant 'libs' folder during the packaging process.

Guidelines for Samples Applications

Below are some things to look out for when preparing your sample applications.

General

  • Create the sample application on each platform first, then added links to your core component code.
    • Make sure they build for every build configuration. The most common reason submissions are rejected is due to one or more build configurations failing to build. We check.
  • In both Debug and Release configurations
    • Test on simulator AND device.
  • Make sure your library is using a Namespace
    • This should not be Xamarin.*
  • Ensure your Component includes a sample for every supported platform.
    • These should each be in their own separate folder as detailed above
    • Sample code contains useful, concise comments.
    • Sample code is well-written, demonstrating proper C# and mobile development principles.
    • Your sample application’s features should be both discoverable and fully functional.
    • Samples target the same platform API/SDK as the library in the component.
    • If your sample application requires any a key or access token, make sure instructuions are clearly documented in your GettingStarted.md

iOS Samples

  • In Xamarin.iOS we have switched to the new "Static" registrar when the sample is deployed to a real device, but not when deployed to the simulator. If you wish to apply this mode when using the Simulator place the --registrar:static option into the iOS Build > mtouch arguments field in Project OptionThis will not need to be included when you submit your component.
  • Ensure that Bundle signing is set to Developer (Automatic)
  • Ensure the Provisioning Profile is set to Automatic

iOS Unified Samples

  • Xamarin.iOS Unified API samples can be included with the component, alongside your Classic samples. Use the ios-unified tag to specify Unified libraries, and use the Unified projects for the samples

Android Samples

  • In the Release configuration under Android Build > Advanced, make sure that the ABI Settings are all checked.
    • This ensures that your sample will run as many devices out of the box as possible
  • Ensure that the minimum version of the Android API is appropriate to the needs of your component, not just lowest available version.
  • Ensure the Target Android Version is set to ‘Automatic’, unless you have a specific requirement to target a particular version of the Google API’s.

Component Elements

Once you have built and tested you core component code and sample applications you will need to produce the elements of the component package that will be needed before submission.

MarkDown should be used for formatting of the .md files, as used by GitHub. You can use markdown editors such as Mou for Mac and MarkdownPad for Windows to format and prepare the documents.

These are:

  • Component.yaml (See Component.yaml section below)
  • Details.md
  • Getting Started.md
  • License.md
  • Icons
  • Screenshots and Videos
  • Documentation

Component.yaml

This file is used to collate and combine all of the various elements of your xamarin component and package it up in the “xam” file that you will submit to Xamarin.

It is just a plain text file and can be opened in any text editor. It uses the YAML serialization format to describe the various elements that will make up your package. We have a full list of the available "tags" that we support at the end of this document.

If you used xamarin-component.exe to create to basic component structure, then you should already have a Component.yaml with some items pre-populated.

Below is an example of the yaml file created by the xamarin-component.exe

%YAML 1.2
---
name: samplecomponent
id: samplecomponent
publisher: Xamarin
license: License.md
icons:
  - icons/samplecomponent_128x128.png
  - icons/samplecomponent_512x512.png
publisher-url: http://www.xamarin.com
build:
  - src/samplecomponent.sln
libraries:
  ios-unified: ../src/samplecomponent/bin/release/Awesome.dll
summary: This is a sample component
details: Details.md
screenshots:
  - screenshots/screenshot1.png
  - screenshots/screenshot2.png
getting-started: GettingStarted.md
version: "1.0"
samples:
  - name: "iOS Sample"
    path: ../samples/AwesomeSample/AwesomeSample.sln
    configuration: "Release|iPhone"
    nobuild: true

This example represents the basic minimum requirements for a package to be created.

Note: When specifying the location of the component dll’s use the path to the output of source projects e.g Bin/Release/a.dll. This will allow xamarin-component.exe to update your samples to references the bundled libraries, instead of the source projects.

Tips

Here are some tips about updating the component.yaml file to fit your components

  • Use the `build` tag to get xamarin-component.exe to build you source code during the packaging process
    • This will help to automate the process and make sure the libraries are always upto date
  • The “id” for your component needs to be a unique identity with no spaces
    • Do not use 'Xamarin' in the component ID
    • The component ID will be used to build the Url of your component once it is published
    • It can be the same as the name of your component, minus spaces
  • Do not use tabs to indent content, use spaces
  • Paths are relative to the component.yaml file
  • We require two icons, as demonstrated in the example above. You can specify each on in the icons section
    • The icons must use a specific naming structure, based on the id of the component, or you will receive an error. See the “Icons” section below for more details.
  • You can specify libraries for each platform using the following specifiers, with the path to the dll as the value.
    • android: [path_to_dll]
    • ios-unified: [path_to_dll]
    • winphone-8.1: [path_to_dll]
    • mobile: [path_to_dll] (for PCL)
  • If you need to to specify multiple libraries for a particular platform you can use the following structure:
    • ios-unified:
      • ../src/samplecomponent/bin/release/Awesome2.dll
      • ../src/samplecomponent/bin/release/Awesome.dll
  • Samples can be provided for each platform by specifying a solution file for each one.
    • Specify a name for the same example iOS Sample, which must be unique within the “samples” section
    • Provide the path to the solution file of the sample

Note: The component ID will be used to generate the Url to your component, so keep that in mind when deciding what to use

For more tags and more detailed information on the tags above please refer to the Appendix 1: Component.yaml Tags section.

Details.md

Your Details.md document supplies the textual information displayed on your component's store landing page. This is the components elevator pitch, a should be used to excite developers about using your components.

Requirements

  • Details.md supplies the textual information displayed on your component's store page. Make sure that it displays properly within the IDE.
  • Give a short description of what your component does and why someone would want to put it in their apps.
  • Provide a list of headlines features within your component to highlight is capabilities
  • Try to include a succinct code snippet that demonstrates the library doing something interesting in an app.
  • Information is accurate and useful, with proper spelling and grammar.
  • Make sure that all links work when viewed from the Component Store website and within the IDE.

GettingStarted.md

The GettingStarted.md document supplies the information that users see when they view your component in their IDE, and is shown immediately after downloading your component from the store. It should be a guide for users, so that they can understand how to use the component.

Requirements

  • Re-describe your component, providing additional detail
  • It should serve as a tutorial for creating their first app with your component.
  • If a License Key or access token make sure to illustrate the steps to getting it here.
  • If a particular Android API is being targeted, rather than being Automatic, this should be documented here.
  • Demonstrate initialising the library and perhaps some other code that a user may use.
  • Show use of library specific Using statements or fully qualified class names.

License.md

The License.md document presents the terms and conditions for using the libraries and sample applications contained in your component.

Requirements

  • Make sure to have an appropriate license for your component
  • For newly-created, open-source components, we recommend using the Apache 2.0 license . However MIT X11 , BSD and MS-PL are also acceptable.
  • For commercial or proprietary applications, please include the appropriate licensing, copyright, and attribution information.

Please email us if you are unsure about licensing for your component.

Icons

You will need two icon files for your component, one at 128px by 128px and one at 512px by 512px. These icons will be used on the component store listings page and the product page of your component.

While the design of your icon is entirely up to you there are some requirements/restrictions that you will need to be aware of, which are detailed below.

The icon must follow the naming structure as follows

  • _128x128.png
  • _512x512.png
  • Don’t apply rounded edges to your icons. We apply these to the icons and if the diameter of your corners is different this can lead to odd looking results
  • Don’t copy the imagery of another author’s component or use branding from another customer or developer

Screenshots and Videos

You can provide multiple images in a slideshow at the top of your component page. We recommend using 740x400 images, to fill the space provided. You can also provide a image that will “PopUp” when a user hovers over your component in the components list.

There are two ways to include screenshots with your component. Firstly you can specify them in the Component.yaml file (Detailed below) or you can upload them directly to the component store(Detailing in the “Component Management” section).

For the best looking screenshots we recommend using PlaceIt which allows you to insert your screenshots in to professionally shot visuals of devices in various scenes.

Additionally we provide the facility for linking to a video on YouTube to provide a visual moving demonstration of your component. This is discussed in the “Component Management” section later in the document.

Documentation

You can optionally provide documentation with your component. This can be accessed within the Xamarin Studio IDE once a component has been downloaded.

The documentation needs to be provided in the monodoc format.

There are three ways to produce the documentation for inclusion in the component package

  1. Manually create the documentation in Monodoc format 1. The files should then be copied into the docs folder of your component
  2. Convert .Net inline comments into monodoc format using the monodocer tool. This makes it easy to keep your code and documentation in sync.
  3. Use .NET Xml documentation files(This is the easiest option)

xamarin-component.exe will automatically convert the.net xml documentation files to monodoc format for a dll’s that are specified in the yaml file, as long as they are in the same location. Typically these files have the same name but have an .xml extension.

You can enable the generation of the xml documentation files by setting the Generate xml documentation to true in the Project Options > Compiler section of your projects.

To manually create the monodocs files from the DLLs please refer to Appendix 2 - Manually create monodocs.

Final Preparation

Before you move on to packaging up your component just run through this list of final checks.

  • Component name is reasonably descriptive.
  • Component summary is correct and concise.
  • The Details.md, GettingStarted.md and License.md file should be provided and formatted correctly
  • Ensure you have provided samples for all supported platforms
  • The icon looks good, appropriate, and professionally represents the component in our store. Make sure that your component does not infringe any copyright.
  • Do not apply rounded corners, or glossy highlights to your icon.
  • We strongly recommend that you include a screencast or screenshots.
  • Make sure that your component is appropriately categorized and tagged.
  • If you want to charge for your component , indicate this when submitting and send an email to set an appropriate price.
  • If the submission updates an existing component, ensure that release notes are provided. The notes should indicate what has changed since the release. This information assists users in determining whether to update or not.
  • Components will be rejected if they are duplicates of another component. Check the component store for this before submitting.

Packaging

Creating the .xam file

Once you have prepared your core code and all of the packaging elements are in place then you can use the xamarin-component.exe file to package them up ready to be submitted to Xamarin for review and approval.

This can be done by running xamarin-component.exe with the “package” parameter and specifying the path of the folder containing the yaml file.

Run the following command in the command line or terminal

Windows : xamarin-component.exe package <foldername>

Mac : mono xamarin-component.exe package <foldername>

If you used xamarin.component.exe to create your base structure it may look something like this, where the component.yaml file exists in the component sub-folder of awesome.

mono xamarin-component.exe package awesome/component

xamarin-component.exe will then package up your components and produce a xam file with the version number as specified in the component.yaml file.

If there are any errors during the packaging process you will be see errors in the console.

Trials

If you wish to sell your component then you will need to provide a trial version of your component as a separate .xam file.
The process for creating this is the same as you full component except the source code, images etc is slightly altered to limit the usability of the trial component until the user purchases the full version.

You can limit your trial in any way you wish, but it will be available to download for free by developers.

When you submit the component on the Xamarin Web site you will be able to indicate that a trial package is to be uploaded along with your full one. You can also change the trial package later, once your component is in the store.

Testing

It is important to test the package before submitting it to Xamarin to make sure everything has been including and put together correctly. This ensures that we can review and approve your components more quickly.

You can easily see the contents of the xam file by simply changing the extension to .zip and then extracting it.

The things that you should check are:

  • Does it include all of the libraries files (dlls)?
  • Are there samples for all the supported platforms?
  • When the solutions are opened to they include all the relevant projects?
  • Do the projects link to the libraries included in the package, or download the components that they require from the component store?
  • Do the samples build and run in both Debug and Release configurations?

If you find any issues, you can simply re-run the packaging process to rebuild the xam file and retest.

Submitting

Once you are happy you can submit your component to the Xamarin component store for us to review and approve.

To submit a component you will need to have a Xamarin Account. If you haven’t then go to the Xamarin Home Page and click “Sign In” in the top right corner. When the Sign in dialog appears, select “Create a new account” and follow the instructions to set up a Xamarin Account.

You can charge for the use of any of your components on the component store. To do this you will need to provide us with account details so any sales can be paid to you, less the 30% commision that we charge.

After submission, your component will be subject to a review before going on the Store. During the review process your component may be returned to you a number of times for bug fixing and improvement. The process for creating a new component and updating an existing are slightly different and both detailed below.

Submitting a new Component

In order to create a new sample you will need to login using you Xamarin account and then go to http://components.xamarin.com/. Then click “Submit a component” to go to the new component form.

  • Either drag your component file on to the “Upload package” section or click there to show a file picker to locate the component file.
  • Choose an appropriate category that suits your component
  • If you have a video of your component on YouTube, Vimeo or Screencast.com paste the URL into the Screencast field
  • If you have not included screenshots in your package you can upload them by dragging them into the screenshot section or by clicking in the box to show a file picker instead. If you have included screenshot in your component you can skip this step
  • You can now choose whether your component will be free or paid for. At this point you can specify the price you would like to sell your component for(in US Dollars) in the special notes section at the bottom of the form
  • If you are going to charge for your component you can optionally provide a trial component package for users to download to test out.
  • Enter any additional contact information
  • In Special Notes you can specify any additional information such as the price of your component, if required, or information to allow us to review your component fully (such as API keys etc.). This information will not be published.
  • We will contact you to arrange pricing if required, and we will also contact you for payment details so we can pay you when your component is purchased.
  • Review all of the details and then click “Submit Component” to submit to us for approval

You will then be able to see you component, and its status, in the My Components section on our main website.

Updating an existing component

If you are submitting a new version of an existing component then log in to the Xamarin website and go to My Components.

  • In the “Submitted” section select the component you wish to update and then click “New Version” in the component information panel on the right.
  • This will open the editor form to allow you to upload a new component, and trial, as well as editing the video links and providing Release Notes(in Markdown format)
  • Use the “Choose File” button to select the new version of the component package using the file picker.
  • If you provided a Trial package previously this will be retained, unless you wish to update it also.
  • Enter your release notes to notify the users of any changes in your components.
  • Click the “Save Changes” button to save and submit the new version for approval.

Approval Process

Once you have submitted your component(new or update) we will review it based on the a Component Review Guidelines and If we find any issues we will contact you to let you know what you need to fix. If we don’t find any issues then the component will approved and will be available on the component store for people to download.

Appendix 1 - Component.Yaml tags

Below is a list of the YAML tags that can be included in the component.yaml file, their purpose and if they are optional (or not).

Compulsory tags

  • name:
    • Provides the name of the component
  • id:
    • Provides the unique identity of the component
      • Should not include spaces
      • Should only include letters A-Z, numbers and dashes(_,-)
  • version:
    • Provides the version number of the component(and the xam file)
    • Will work with 4 version fields, though 2 is preferred
  • summary:
    • Short, concise, exciting description of the component
  • publisher:
    • Name of the author or company
  • publisher-url:
    • URL of the author web site
  • license:
    • path of the License.md file
    • relative to the component.yaml file
  • details:
    • path of the Details.md file
    • relative to the component.yaml file
  • getting-started:
    • path of the GettingStarted.md file
    • relative to the component.yaml file
  • icons:
    • At least one icon, sized 128x128 or 512x512 is required
    • Must have begin with the same id of the component
    • Each icon can be specified by providing a line, as below for each icon.
    • Each line should be inset by 2 spaces beneath the icons: tab <filepath></filepath>
    • A maximum of two icons are supported, 128x128 and 512x512
  • libraries:
    • To specify libraries for each supported platform specify a platform ID tag beneath the libraries tag. These are:
      • android:
      • ios-unified
      • mac-unified
      • pcl
      • tvos
      • uap
      • watchos
      • wp8
      • wp81
      • wpa81
      • winrt
      • win8
      • winphone-7.0
      • winphone-7.1
      • winphone-8.0
      • winphone-8.1
      • winphoneapp-8.1
      • winuniversal-10.0
  • The platform id tags should be indented by 2 spaces.
  • If you have only one library per platform you can specify it this way, where filepath is the path to the dll relative to the component.yaml. E.g. ios-unified: ../lib/Awesome.dll
  • If you wish to specify multiple dlls for each platform you can specify each dll and a separate line, beneath the platform ID tag.
    • Each line should be indented by 2 additional spaces.
    • Each line should be prefixed with a “-” followed by the path of the dll.
  • samples:
    • Used to specify the samples for the supported platforms.
    • You can provide as many samples as you wish
  • Each sample must have a unique tag beneath the samples tag
    • Each tag must be inset by 2 spaces beneath the samples: tag
  • The value part is the path to the solution file of the sample, relative to the component.yaml file. samples:
    • iOS Sample2: ../samples/AwesomeSample/AwesomeSample2.sln
    • Android Sample: ../samples/AwesomeSample/AwesomeSampleAnrd.sln

    Optional Tags

    • build:
      • Allows you to specify a solution or solutions to build during the package process
    • docs-url:
      • Specify the url for your online documentation
      • This will show as the “Documentation” button with the component store page
    • monodocs:
      • specify the folder where your monodocs are located.
      • Note: Currently the path is not relative to the component.yaml, but to the xamarin-component.exe. You may need to specify the full path in order for the documentation to be included
    • source:
      • If you wish to include the source code within your component then you specify the path to the source solution file
    • src-url:
      • Specify the url for your source online, such as github.
      • This will show as the “Source” button with the component store page
    • skip_docs:
      • Disable processing of the documentation, either monodocs or xml files
      • set to “true” or “false”

    Appendix 2 - Manually create monodocs

    Below we detail how to convert standard .Net Inline Comments in to monodoc format. This can be done for Android, iOS and even PCL projects.

    Note: Ensure that you have your mono path setup correctly in Terminal or Command Line

    monodocer requires a link to the MonoTouch install so allow it to resolve and iOS types. Below is an example of how to create the monodocs, in the ‘docs’ folder of the standard base folder structure.

    • Make sure that you have commented all of your code and build your components.
    • Open the command line and change directory to you main components path.
    • enter the following, referencing the monotouch installs path, and any libraries you wish to process.
      monodocer -r:/Developer/MonoTouch/usr/lib/mono/2.1 -assembly:lib/<filename>.dll lib/<filename>.dll -path:docs -pretty --delete
        

    This will create the monodocs files in the “docs” folder and process the two dlls specified in the example.

    To include the documents in the package you must add the monodocs: tag in the component.yaml file and provide the path to the folder containing the monodocs files.

    monodocs: ../docs

    Please note that current the monodocs path is relative to xamarin-component.exe not the yaml file, so you may need to specify a full path to get it to work correctly and be included in the package.

  • 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.