Xamarin Component Submission
Quick Start Guide
- PDF for offline use
Let us know how you feel about this
last updated: 2017-03
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 guide provides a quick and simple guide to help you to build, bundle and submit your components to the Xamarin Component Store.
This document is designed to give you a quick guide on how to create, package and submit a component to the Xamarin component store. For a more complete guide please read the full Xamarin Component Store Guide.
This document is split into three sections, Component Creation, Packaging and Submission which should cover everything you need to know, albeit briefly.
It assumed that you have some experience with yaml and producing a component. If you don’t then the full Xamarin Component Store Guide might be a better place to start.
Create the Component
These steps have been created to help guide you through creating relevant folders, prepare the correct documentation and collate all the required parts.
- Download the xamarin-component.exe from Xamarin here: https://components.xamarin.com/submit/xpkg and Extract it.
Use the xamarin-component.exe to create the base structure by typing the following into the console/terminal where
<foldername>is the base folder for your component.
Note: you will need to change the path to the location where you extracted the .exe file.
xamarin-component.exe create <foldername>
mono xamarin-component.exe create <foldername>
You will be asked to answer some questions about your component, and these will be used to pre-populate some of the values in the Component.yaml file. Answer each one and continue through to the end.
- A folder will be created with the name you selected, and within that you will find a Component folder with some template files.
- Within this folder create the lib and samples folders to complete your folder structure
- Within the lib folder create new folders for each platform you support.
- Do the same for the samples folder.
- Copy your components DLL’s into the relevant platform folder within the lib folder - Copy the xml files too if you want to include your documentation
- Create a sample project for each supported platform in the relevant folder in samples
- Reference the DLL’s from the relevant folder in libs and then build your sample
- Create an Icon and replace the two icon files create by the xamarin-component.exe - You need one at 128x128 and one at 512x512
- Don’t use a round icon, we'll apply the rounding when it’s displayed on the component store.
- Edit the GettingStarted.md, Detials.md and License.md files and enter the details of your component/
- Edit the component.yaml file. Update it to point to your DLLs, samples and icons. Enter the name and id of your component and then enter a description in the summary tag. Then enter your Name and the address of your website in the publisher and publisher-url fields.
- Finally enter the version number of your component
Once you have prepared your core code and all of the packaging elements are in place then you can use xamarin-component.exe 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:
xamarin-component.exe package <foldername>
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.
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.
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 do 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.
Once you are happy you can submit your component to the Xamarin component store for us to review and approve.
If you don't already have one, you will need to set up a Xamarin Account. To do this, visit the Xamarin Home page and click “Sign In” at the top right corner. Then “Create a new account” and follow the instructions to set up an 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% commission that we charge.
The process for creating a new component and updating an existing is slightly different so they are both detailed below.
Submitting a new Component
In order to create a new sample you will need to login to the Components portal using your Xamarin account. Then click Submit a component to open a new component form.
Use the steps below for guidance on filling in 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 in by dragging them into the screenshot section or by clicking in the box to show a file picker instead.
Choose whether your component will be free or paid for.
- You can specify the price you like to sell your component at(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 the Special Notes section, you can specify any additional information such as the price of your component if required, or demo information to allow us to review your component fully. The information will not be published.
- We will contact you to arrange pricing if you to specify it here, 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 your component, and its status, in the My Components section on our main website.
Upgrading 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.
Once you have submitted your component(new or update) we will review it based on the 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.