Productive day... Thanks @VSTS for fully automating all my NuGet packages. pic.twitter.com/pDzYUXnG5I

— James Montemagno 🙈 (@JamesMontemagno) May 10, 2018

If you look at this screenshot from VSTS it is everything that I wanted for so long in my development cycle. I push code, things are built, and automatically packages are pushed. In this post I am going to show you how I set this up for my projects and how you can too in just a few minutes.

.NET Standard and Multi-Target Projects

Before we start to setup our CI/CD for libraries I highly recommend you move your projects to SDK style projects. You can read my full guide on how to convert a PCL to .NET Standard or how to convert a Xamarin.iOS or Xamarin.Android project to SDK Style.

Everything that I develop now is based on a single .NET Standard 2.0 library or a Multi-Targeted project for plugins. I have previously written on how to convert your PCLs to .NET Standard and also have templates for Visual Studio 2017 to create Multi-Target projects for plugins.

The reason to use these types of projects is that they include full NuGet packaging including all metadata and dependencies. This also means you can fully delete the .nuspec file that always gets out of sync. It is worth your time to update any and all projects to these types of projects to simplify your life.

If you need to learn more about multi-targeting be sure to check out Oren's amazing MSBuildSdkExtras package which is the core of my templates and all of my projects.

If you are building only an iOS or Android library do not fear as you can still just convert your existing library over to an SDK Style. Take a look at my MonoDroid.Toolkit csproj on GitHub.

Build Definition in VSTS

My builds inside of VSTS are actually really simplistic and only contain 6 steps to fully build my libraries. You can use the Hosted Visual Studio 2017 machines, however I have a small Intel NUC that runs a local VSTS agent so all my NuGets are cached which reduces my build times to seconds instead of minutes.

Empty Definition

Select New and pick your source code that you would like to build. I then like to select Empty process because we can easily fill it in.

NuGet Steps

Under Phase 1 we are going to add two NUGet steps.

First is the NuGet Tool Installer task and change the Version to 4.5.1

Second will be the regular NuGet task which we will use the restore command on our solution that we are going to build. I like to pick the specific .sln or folder where it lives (no need to build other stuff).

Build Steps

I build my libraries twice! That is right twice! Once for a "beta" NuGet and once again for "public" NuGet. They are super quick and all it is really doing is changing the version flags. The reason I do this is for my release definition that will allow me to have a single release that goes from beta to public easily. We will be building the .csproj specifically using the MSBuild task:

We will add it twice so we can build the beta and public releases. Name the first Build Beta and the second Build Public. For each of them set the following:

• Project: Select the .csproj specifically
• Configuration: $(BuildConfiguration)

For MSBuild Arguments user the following for Beta:

/t:restore;build;pack /p:PackageVersion=$(Build.BuildNumber)-beta /p:PackageOutputPath=$(build.artifactstagingdirectory)/beta /p:AssemblyFileVersion=$(Build.BuildNumber)

For Public use:

/t:restore;build;pack /p:PackageVersion=$(Build.BuildNumber) /p:PackageOutputPath=$(build.artifactstagingdirectory)/public  /p:AssemblyFileVersion=$(Build.BuildNumber)

This will ensure that the build numbers are configured correctly and copy the artifacts to different folders.

Optionally, you may have some additional unit tests or device runners that may need to be run here.

Copy and Publish

The next thing to add is the Copy Files task to stage the NuGet packages for release.

Set these properties:

• Source Folder: $(build.sourcesdirectory)
• Contents: **\bin\$(BuildConfiguration)\**\*.nupkg
• Target Folder: $(build.artifactstagingdirectory)

Finally, add the Publish Build Artifacts task and set the following:

• Path to publish: $(build.artifactstagingdirectory)
• Artifact name: drop
• Artifact public location: Visual Studio Team Services/TFS

This will pull only .nupkg files that we will distribute into a folder that release can pick up.

All in all the definition should look like:

Configure Version Number

Under the Options tab in the build definition I like to format the Build number format such as: 4.5.0$(rev:.r)

This means that the next version would be: 4.5.0.1 and then 4.5.0.2.

Now if you change this to: 5.0.0$(rev:.r) it will reset the revision so it will be 5.0.0.1.

Other things!

You will probably want to setup *Triggers so CI and PR validation are configured. This means that every time master is pushed to a package is generated.

Release Definition in VSTS

Now we have our full build complete it is time to setup our release. Our goal for me was to automatically have every build of master go to MyGet and then manually approve the next release to go to NuGet (beta) and finally another approval to go to NuGet with the public non-beta package.

Head over to the Releases section and create a new release definition with an Empty process. Think of Environments as the stages of release. We can create three of them to define each release of the artifacts. Inside of each environment are a sequence of tasks, just like our build definition, that will be run. For my libraries it is really simple as each has just one task. However, before the NuGet beta and production environments I turn on pre-deployment approval steps.

Push to MyGet

In our first environment we will want to push to MyGet. Add the NuGet task with the following settings:

• Command: push
• Path to NuGet package: $(System.DefaultWorkingDirectory)/**/drop/beta/*.nupkg
• Target Feed: External NuGet server

For this step you will want to configure the feed information from MyGet:

Push NuGet Beta

For this step you can select Clone or if you already create the new environment simply add the NuGet task again. The settings will be the same as above:

• Command: push
• Path to NuGet package: $(System.DefaultWorkingDirectory)/**/drop/beta/*.nupkg
• Target Feed: External NuGet server

However, we will now want to select or configure NuGet as our destination:

Head back to Pipeline and for this environment we don't want it to automatically trigger, we want to approve this release. You will see a lightning bolt and a person shape on the left side of the environment to configure pre-deployment conditions. I turn on pre-deployment approvals and select myself and turn off the policies since I am a solo developer:

There is all sorts of rad stuff you can do here on pre and post-deployment so you should totally look into that for larger projects.

Push NuGet Production

Add or clone another environment for after the Beta environment. This is going to be almost the same as the previous step but we are going to change our Path to NuGet package:

• Command: push
• Path to NuGet package: $(System.DefaultWorkingDirectory)/**/drop/public/*.nupkg
• Target Feed: External NuGet server

Notice I am using public here :)

Add Artifact

Finally, click the big Add artifact button on the left side and select the build definition that you created earlier. Also tap on that little lightning bolt and turn on the Continuous deployment trigger so this flow automatically happens!

CI/CD Pro!

You did it! You are totally a Continuous integration and delivery pro!! Enjoy a seamless deployment of every push to master to MyGet and then approval steps to push to NuGet for any and all of your .NET Libraries. <3 Feel free to ask questions below.

Unload that Project

First things first, we need to get at that raw .csproj madness. Right click on the project and click Unload Project. Then right click again and select Edit *.csproj:

Delete Everything!

That is right! Delete it all because we don't need it at all!

Replace it with my base project information. It is a bit verbose but based on the type of library you are creating there are some special things that you may want to include such as Android resources.

Note: I like to only compile items that end in .shared.cs, .ios.cs, or .android.cs to keep it tidy, but you can easily change what you compile into your library in the project structure.

Right click and re-load the project!

Spice it up

Now you can go in and any NuGets you may need with the PackageReference node in the ItemGroup of your choosing. Additionally, you can also turn on Multi-Targeting to generate both an iOS and Android (or whatever else like UWP and netstandard) by change TargetFramework to TargetFrameworks and specifying more frameworks.

NuGet that Library

What is great about the SDK style projects is that you don't need a .nuspec at all for your NuGet and it can be generated automatically at build time! Whoa! Amazing Yes! You can also see the contents with the NuGet Package Explorer

All you need to do is turn on GeneratePackageOnBuild in the Release property group and then add the following items to the main PropertyGroup for the NuGet's information:

You can read more about these attributes over on the NuGet documentation.

Now when you compile in release mode you get a full NuGet with your library:

SDK and Multi-Target Everything

If you have multiple libraries like me or building multiple libraries from a single solution you can also look into Directory.Build.props and Directory.Build.targets that enable you to group common properties together for a full solution.

I have gone through just about every project I have created and switched over to this new style of project because CI is so simple with it that I can manage a full CI/CD cycle for all of my libraries from one location:

Check back later this week for my blog on how to take the SDK style projects that we have here and set them up for CI in VSTS.

See Me Convert a Library Live!

Because I love seeing things in action I walk through the exact steps here in this short video:

It is important to remember that there is nothing special you need to do to get PCL support. If you copied over dlls or added xml files you should remove all of this and just use the Stable branches of Xamarin to get official support.

What is a PCL and what are profiles?

A PCL is a portable class library which is a project template inside of VS and XS which allows you to select platform targets that the project will be compatible with. This is amazing because you have one project that works everywhere. PCLs have actually been around since VS 2010, but they have always been locked into Windows specific platforms, but that all changed last November when Microsoft and Xamarin announced a major partnership which included PCL support for Xamarin.Android and Xamarin.iOS apps. PCLs use these things called “profiles”, which are actually supposed to be hidden from developers, but you will see them everywhere. Profile numbers are a peek into what platforms the PCL supports and how NuGet handles PCL support when installing. There are several parts to a profile such as net45, wp8, and now monotouch and monoandroid. PCLs work a bit interestingly which is that the DLss that are in the .NET subset are actually more like stub methods or interfaces that you are developing against. The DLL that gets used is the DLL that is included in the base project. This still puzzles me a bit and I am not a Microsoft PCL compiler expert like Daniel Plaisted, so you can ask him tons of questions on Twitter.

Tips & Tricks

1. Remember that PCLs are platform independent. Not all APIs will be available to you.

2. Don’t try to put platform specific code in a PCL, that is now what they are for. Abstract all platform specific code with interface that you implement on each platform

3. PCL’s are great for large or small libraries, try to break your project up into small re-usable components. For instance I have a Settings PCL that is cross platform compatible that I reuse on every project. Growing a large PCL is fine, but try to think about how you can reuse code on more projects

4. Choose only the targets you want to support. The more you select the smaller the subset of .NET you will get. If you select Windows Phone which doesn’t have HTTPClient you will not get access to it.

5. Use NuGet to fill in the gaps. If you need to use a specific PCL profile be sure to search NuGet to see if there is something to fill in the missing functionality such as HTTPClient or PCL Storage.

6. Recommendation is to leave out Silverlight and Windows Phone if you are not currently developing for these platforms as they will limite your APIs.

7. This means use Profile 7 or Profile 78 for your projects based on your needs.

Setup

Here is a short guide on how to create your first PCL:

Visual Studio

Inside of Visual Studio it is easy to create a PCL by simply selecting File->New Project -> C# -> Portable Class Library.

When you select this you will see a dialog pop up asking you what platforms you wish to support.

That’s it you are good to go. As you can see they hide the “Profile” from you, but if you expand your References folder and select the .NET Subset DLL you will see in the path a specific profile that you are using.

Xamarin Studio

Similar to Visual Studio you will create a new PCL by selecting File->New Project -> C# -> Portable Library:

Now instead of popping up the target dialog like Visual Studio does you need to actually edit the project properties to specify the correct PCL Profile:

PCL/NuGet Issues

All PCLs and NuGets are not created equal and you will need to do some testing that is for sure. One issue that a lot of people might run into is with Json.NET that has an official Xamarin Component and also an official NuGet as well. While the NuGet does have official support for Xamarin.iOS and Xamarin.Android and issue does comes up if you are using profiles that include .NET 4.5, which is that Json.NET will install a newer version that is including System.Runtime.Dynamic, which is not supported in Xamarin.iOS. This means that that NuGet in general just will not work. There are a few work around for this and I recommend simply installing the Json.NET component in both the Android and iOS project and then manually referencing this DLL (iOS or Android it doesn’t matter) in your PCL. The only thing you will really miss is the DeserializeAsync, which you can create your self easily by wrapping it in a Task. This may change in the future as I have been working with James to get this fixed, but this can be the case with any NuGet out there so be careful.

I hope this helps you get up and running with PCLs. I love PCLs because they are awesome so always feel free to reach out to me on Twitter with questions.