This blog post supports the sample code for the "Deploying and Distributing Xamarin.Forms Applications" course on Pluralsight.

I'll update this post if any common issues are identified, along with their solutions.

Currently there are no common issues with the course.

You can check it out here: Deploying and Distributing Xamarin.Forms Applications

This blog post supports the sample code for the "Getting Started with Xamarin.Essentials in Xamarin.Forms" course on Pluralsight.

I'll update this post if any common issues are identified, along with their solutions.

Currently there are no common issues with the course.

You can check it out here: Getting Started with Xamarin.Essentials in Xamarin.Forms

Recently I've been using the excellent Cake for Visual Studio extension. It makes working with Cake build scripts inside Visual Studio that much easier with task runner integration, item templates and (some) syntax highlighting.

While the item template for adding a basic Cake build script is great, it only works when you use the Add New Item functionality on a C# project. However, the majority of our build scripts sit at the solution level (inside the Solution Items folder) so we couldn't take advantage of this template when adding a new item to the solution itself.

Luckily the extension is open source so we can see how the current item template works:

<?xml version="1.0" encoding="utf-8"?>
<VSTemplate Version="3.0.0" Type="Item" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" xmlns:sdk="http://schemas.microsoft.com/developer/vstemplate-sdkextension/2010">
  <TemplateData>
    <Name>Cake Build Script</Name>
    <Description>Basic Cake build script with a sample task</Description>
    <Icon>ItemTemplate.ico</Icon>
    <TemplateID>7d181506-47e9-4f9d-8ac3-5ac65f6b8354</TemplateID>
    <ProjectType>CSharp</ProjectType>
    <NumberOfParentCategoriesToRollUp>1</NumberOfParentCategoriesToRollUp>
    <DefaultName>build.cake</DefaultName>
  </TemplateData>
  <TemplateContent>
    <ProjectItem ReplaceParameters="false">build.cake</ProjectItem>
  </TemplateContent>
</VSTemplate>

The <ProjectType> element is set to CSharp which explains why it appears for new items in C# projects but not for solution items.

According to the Visual Studio template schema the ProjectType element must contain one of the following values:

• CSharp: Specifies that the template creates a Visual C# project or item.
• VisualBasic: Specifies that the template creates a Visual Basic project or item.
• Web: Specifies that the template creates a Web project or item.

None of which sound like they will work for a Solution item.

It turns out this mustn't be a common use case, as checking out the Online Solution Item templates revealed only one other template (although it does have over 8,000 downloads).

Having a look at Runsettings' .vstemplate file revealed an undocumented ProjectType of General to get an Item Template to appear in the Add New Item - Solution Items dialog - exactly what we needed!

So the last step was to create a new item template for Cake, with <ProjectType> of General and submit a pull request to have it included in the addin. Now we can add a new Cake build script at the solution level with ease!

While working on our new Xamarin mobile app we migrated parts of our code base from .NET Framework to .NET Standard. This meant we needed a new dependency injection container for .NET Standard and Microsoft's DependencyInjection framework (as used in ASP.NET Core) ticked all the boxes... except for one.

Our requirements were straightforward:

☑ Must run on all platforms including web, desktop and mobile.

☑ Must support constructor injection.

☑ Modules that register services with the container should depend on a stable abstraction.

☒ It should be simple to register services that implement multiple interfaces.

Unfortunately, Microsoft's framework required us to manually bind all interfaces for a particular service. An unnecessary burden and one feature we took for granted with our previous abstraction (NServiceBus' Configurer).

The NuGet package Microsoft.Extensions.DependencyInjection.Abstractions provides two main interfaces

• IServiceCollection - used to register interfaces to implementations for a specific lifetime with the container

void RegisterServices(IServiceCollection services)
{
  services.AddScoped<IMyDependency, MyDependency>();
  services.AddTransient<IOperationTransient, Operation>();
  services.AddScoped<IOperationScoped, Operation>();
  services.AddSingleton<IOperationSingleton, Operation>();
  services.AddSingleton<IOperationSingletonInstance>(new Operation());
}

• IServiceProvider - used to build instances of interfaces/services

void BuildServices(IServiceProvider provider)
{
  var dependency1 = provider.GetRequiredService<IMyDependency>();
  var operation1 = provider.GetService<IOperationTransient>();
}

In order to meet our last requirement and simplify registering types, we created extension methods on IServiceCollection based off the work done by Particular/NServiceBus on their own DI adapters.

/// <summary>
/// Registers the type <see paramref="TType"/> and all its alias (interfaces + base type) with the container with the specified <see paramref="lifetime"/>
/// </summary>
/// <typeparam name="TType"></typeparam>
/// <param name="services"></param>
/// <param name="lifetime"></param>
/// <returns></returns>
public static IServiceCollection RegisterComponent<TType>(this IServiceCollection services, ServiceLifetime lifetime)
{
  var type = typeof(TType);
  
  services.Add(new ServiceDescriptor(type, type, lifetime));
  
  BindAliasesOfComponentToComponent(services, type, lifetime);
  
  return services;
}

In the above code we first add a service descriptor that maps the type to itself, then we bind all of its aliases (interfaces) to itself which looks like:

private static void BindAliasesOfComponentToComponent(IServiceCollection serviceCollection, Type component, ServiceLifetime lifetime)
{
  var services = GetAllServices(component).Where(t=> t != component);

  foreach (var service in services)
  {
      // Bind all interfaces to a factory method which builds the implementation type
      serviceCollection.Add(new ServiceDescriptor(service, ctx => ctx.GetService(component), lifetime));
  }

  var baseType = component.BaseType;

  if (baseType == null || !baseType.IsAbstract)
  {
      return;
  }
  
  // Don't forget to bind an abstract base type to the implementation
  serviceCollection.Add(new ServiceDescriptor(baseType, ctx => ctx.GetService(component), lifetime));
}

We use reflection to recursively find all of a type's interfaces:

static IEnumerable<Type> GetAllServices(Type type)
{
  if (type == null)
  {
      return new List<Type>();
  }

  var result = new List<Type>(type.GetInterfaces())
  {
      type
  };

  foreach (var interfaceType in type.GetInterfaces())
  {
      result.AddRange(GetAllServices(interfaceType));
  }

  return result.Distinct();
}

Finally in our module we can use this new extension method to automatically bind a type to all of its interfaces:

using App.Extensions;
using Microsoft.Extensions.DependencyInjection;

public class ServiceAgent : IServiceAgent, IWantNotifications
{

}

public class Module
{
  public void Initialize(IServiceCollection services)
  {    
    services.RegisterComponent<ServiceAgent>(ServiceLifetime.Singleton);
  }
}

In this example the interfaces IServiceAgent and IWantNotifications are bound to the same singleton class ServiceAgent.  They can now be built using provider.GetService<IServiceAgent>() or used in constructor injection for other services.

Different teams are responsible for each of these NuGet packages (and there are a lot of them!) so including the projects in the main Xamarin application solution isn't an option. Unfortunately, this can make debugging and stepping through these internal components much harder when they're added via NuGet packages.

While SourceLink can help us debug and step in to these components in our desktop applications, it isn’t currently supported in Xamarin.

But there is another way! Here is how we build our NuGet packages so that developers can easily debug them if needed from the main application. This method will work for internal NuGet packages within an organisation - it won't work for third party NuGet packages (unless they follow this method too!)

Ultimately this method boils down to 2 basic concepts

• Include the .pdb file in the NuGet package
• Ensure the source file locations baked in to the .pdb are mapped to a well-known location

Sounds simple right? However, there are a few gotchas to keep in mind.

Let's start with a .NET Standard 2.0 class library for our Reminders component that we'll want to include in our Xamarin app.

The new SDK-style projects have made it trivial to create a NuGet package from a project using either Visual Studio or the donet cli.

dotnet pack ItOps.Reminders.Xamarin.csproj

But the resulting NuGet package (.nupkg) will only contain the ItOps.Reminders.Xamarin.dll, not the .pdb.

If we were to pass in the --include-symbols to the pack command above, it would generate a separate *.symbols.nupkg that contains the .pdb file we need for debugging.

However, we can get a better debugging experience by including it in the main package. According to Microsoft:

Embedding symbol files in the main NuGet package gives developers a better debugging experience by default. They don't need to find and configure the NuGet symbol server in their IDE to get symbol files.

The downside to embedded symbol files is they increase the package size by about 30% for .NET libraries compiled using SDK-style projects. If package size is a concern, you should publish symbols in a symbol package instead.

In order to get all the files we need in the main NuGet package, we can add this property to our .csproj file.  

AllowedOutputExtensionsInPackageBuildOutputFolder

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup> 
      <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb;.xml;</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
    <!-- Other properties ommitted -->
</Project>

Now when we run dotnet pack the resulting NuGet package will contain our assembly and the .pdb file. Success!

This NuGet package can be referenced in our main Xamarin application and we can now step in to the Reminders code. (Make sure the Just My Code setting is disabled in Visual Studio)

While this works for a NuGet package built and debugged locally on the same machine, chances are that we won't be able to debug a NuGet package built on our Continuous Integration build server.

The reason for this is that when a .pdb file is generated, it embeds the location of the source code.  Because each developer (and build agent) checks out the source code to a different location, unless our code is also in the same location Visual Studio won't be able to locate the source when debugging.

We can rewrite the source code location inside the pdb while it is being generated by making use of the PathMap property in our .csproj file.

<PathMap>$(MSBuildProjectDirectory)=C:\repos\itops\reminders\xamarin</PathMap

In this case we are mapping the current project build directory (which could be a random folder on the build agent) to a well-known location.

Developers can then either move their local copy of the source code to C:\repos OR create a directory junction to map this path to the actual location of their repository (e.g. D:\code).

mklink /J D:\code C:\repos

With all this in place, we can now debug in to NuGet packages built locally and on the build server.

One last bit to tidy up. Rather than having to modify all our .csproj files individually to set these properties, we can take advantage of a single Directory.Build.props file.

By checking in this file to the root of our git repository, it will automatically apply these settings to every project in the repository.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb;.xml</AllowedOutputExtensionsInPackageBuildOutputFolder>
    <PathMap>$(MSBuildThisFileDirectory)=C:\repos\itops</PathMap>
      
    <!-- Additional properties that we'd like to apply repository wide -->
    <Company>Smokeball</Company>
    <Authors>Smokeball</Authors>
    <DebugSymbols>true</DebugSymbols>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
</Project>

Once Xamarin finally supports SourceLink we will be able to do away with this method and Visual Studio will be able to pull the source code directly from our remote git repository.

Additional notes

To inspect the file paths embedded in the pdb you can use the Dia2Dump tool for Windows pdb files (DebugType = Full)

Dia2Dump.exe ItOps.Reminders.Xamarin.pdb

or for a portable .pdb (DebugType = Portable) you can view the file paths by opening it in Notepad++.

One last thing - if you use ProGet to host your NuGet feeds, then ensure the option to strip symbol files from packages is NOT selected.