More on Xamarin Studio add-ins

As a follow up to my previous post about creating an add-in for Xamarin Studio I thought I’d go into the details of the project template XML.

When creating an add-in that adds a new project type you define each project as a Project node inside the xpt.xml file. This project node has some attributes, and sub nodes made up of options, references, files and packages.

Think of this post as a sort of API reference for these based on what I’ve discovered, or been taught. Once again this post would not be possible without the help of Mikayla Hutchinson - she is awesome.

Variables

In this file you can use ${ProjectName} to refer to the name of the solution. This is not the file name, just the solution name, so MySolution.sln would be called MySolution and every instance of ${ProjectName} would be replaced with MySolution.

The Project node

<Project name = "${ProjectName}.Core" directory = "./${ProjectName}.Core" type="C#PortableLibrary">

The name is the name of the .csproj file. In the files for this project the ${ProjectName} is set to this name.

The directory is the subdirectory under the solution where this project is created.

The type is the type of the project. The 3 types I know about are:

• C#PortableLibrary - PCL
• MonoDroid - Android app
• XamarinIOS - iOS app

The Options node

This is a sub-node of Project, and is used to set options on the project file. The attributes I am aware of are:

PCL projects:

<Options Target="Library" TargetProfile = "Profile259"/>

• Target="Library" - sets this project as a library
• TargetProfile="Profile259" - sets the target profile

Android projects:

<Options AndroidApplication="true" AndroidResgenFile="Resources\Resource.Designer.cs" GenerateSerializationAssemblies="Off" ProductVersion="8.0.30703" SchemaVersion="2.0" AppDesignerFolder="Properties" FileAlignment="512" JavaMaximumHeapSize="1G"/>

• AndroidApplication="true" - Marks this project as an Android app
• AndroidResgenFile="Resources\Resource.Designer.cs" - Tells the Android app which file is autogenerated from the resources
• JavaMaximumHeapSize="1G" - Sets the Java heap size, 1G is better than the default 512M

Not sure exactly what the other attributes do - if you know please tell me and I’ll update this.

iOS projects:

<Options />

I don’t know any of the options here, again if you know please tell me!

The References node

This is where you define references to libraries or other projects. No need to add references to libraries that come from NuGet here, as these are set via the Packages node.

<References>
   <Reference type="Package" refto="Mono.Android.Export" />
   <Reference type="Project" refto="${ProjectName}.Core" />
</References>

• type - Package for an assembly either from the .Net framework or from a library that you are shipping, Project for a reference to another project in your solution
• refto - the assembly to reference (for framework assemblies), or the project name for other projects in the solution.
• HintPath="xxx" - specifies the hint path for references to libraries outside of the framework (such as one you are shipping with the add-in)

The Files node

This is where you define the actual files to copy to your project. These files must come from somewhere, so you need to add them to your project with Copy to output directory ticked. You also need to add these files to your Manifest.addin.xml file as Import entries in the Runtime node.

<Files>
   <File name="Properties/AndroidManifest.xml" src="Droid/Properties/AndroidManifest.xml"/>
   <RawFile name="Resources/drawable/icon.png" src="Droid/Resources/drawable/icon.png"/>
  
  <File name="Pages/FirstPage.xaml" BuildAction="EmbeddedResource" src="Core/Pages/FirstPage.xaml"/>
  <File name="Pages/FirstPage.xaml.cs" AddStandardHeader="True" src="Core/Pages/FirstPage.xaml.cs" DependsOn="FirstPage.xaml" />  
			
</Files>

There are two possible nodes here, File and RawFile. Use File for text files as this will do file ending/unicode conversion. Use RawFile for binary files, such as images or libraries to avoid any conversion.

• name - the file name including the directory for the file to write to
• src - the file name and path of the source file inside your bundle
• BuildAction - the build action for this file. For normal compile you don’t need this but for Xamarin.Forms Xaml files you need to set this to EmbeddedResource .
• AddStandardHeader="True" - don’t know what this does, but is used for xaml files for forms.
• DependsOn - sets the file that this depends on, so used for specifying the Xaml file for a xaml.cs code behind file.

The Packages node

Here you can define what NuGet packages to install in your app. These are installed as if you installed them manually, so all dependent packages are installed.

<Packages>
   <Package Id="Xamarin.Forms" Version="2.3.0.107"/>
   <Package id="MvvmCross" version="4.2.2"/>
   <Package id="MvvmCross.Forms.Presenter" version="4.1.4"/>
</Packages>

• id - The Id of the NuGet package to install
• version - The specific version to install if needed

This doc is nowhere near complete, so if you know of other things to add please let me know and I’ll update it.