Porting a .NET Framework Library to .NET Core

This article is up-to-date as of June 2017, unlike many other tutorials and guides on the internet.
Anything that mentions a "project.json" is outdated with VS 2017 which requires a .csproj instead.

Introduction

I was pulled into the world of .NET Core/.NET standard with my work on the FluentFTP library. I needed to port it to .NET Core so I decided to learn the technology. After all, it was just a cut-down version of the .NET Framework, how hard could it be? It turned out to be a tough experience and after finding no tutorials on the subject, I decided to write my own. I don't claim this is the best method, however it's a method that worked for me.

My library was built on the .NET Framework 4.0, and was an ideal candidate for porting because it does not use WindowsForms or any UI controls, which are currently unavailable on .NET core. You can only use core data types, collections, file I/O, XML, images, timers, processes, etc. Pretty much everything you need to build a functional console app or backend library.

You might know that .NET Core is the open-source version of .NET framework and is built by Microsoft. It splits the entire .NET framework into "packages" which are hosted on Nuget. Each package pulls in the dependency packages required, keeping your library free from bloat.

Porting this relatively simple library was a difficult experience, and I decided to write my experiences and tips to help developers port their technology to .NET Core and thereby contribute to the platform. You can browse the currently available .NET Core libraries at the Awesome .NET Core project. If you have ported a great library to .NET Core, don't forget to add it into the list by forking and submitting a PR!

This article is written like a tutorial and aims to help you with your own project, however, I will be using screenshots and example files from the FluentFTP project since it provides practical examples for each step.

Review

A quick review of .NET core and the advantages it offers compared to .NET Framework.

• It's cross platform, so your app will run the same on Windows, Unix, Mac, etc. I have still to see legit uses for this, because if you have a server-side application, you could just run it on Windows Server with the full .NET Framework. However, with .NET Core, you can now run it on Unix, which is a free OS.
• It's modular, as the entire .NET Framework is cut into small pieces and uploaded onto Nuget. So your app must specify its dependency packages, which in turn have their own dependencies. When you install your app from nuget, it downloads only the packages it needs, nothing more.
• It's online, meaning it's preferred that every system that your app runs on has an internet connection. If you want offline functionality, you can package dependencies along with your app while compiling, but then you don't have access to nuget-based updates.

Requirements

• You will need Visual Studio 2017 Community Edition or better to compile the .NET core version of your library. It must be installed on an internet connected PC and is free forever once you sign in. You can use VS 2015, but it's outdated and not recommended.
• You will also need Visual Studio 2012 or 2015, for compiling the .NET Framework versions of your library. You can install both 2012 and 2017 on a single machine as I have done.
• You will need Windows 7 or higher since all of the steps are designed for building on a Windows machine, using batch files and the like. I still use Windows 7 so I recommend using that. Building on Unix is out of the scope of this article since it requires VS Code, which is a completely different open-source IDE from Microsoft with completely different project configuration (which is the hardest part).
• You will need NuGet located at C:\Tools\Nuget\nuget.exe in order to create your nuget package
• You will need NuGet Package Explorer to view your final nuget package (.nupkg) and ensure all the metadata and libraries have been pulled in successfully. If you are not publishing for nuget, skip this.

Objectives

In this tutorial, we aim to use a single codebase for the .NET Framework and .NET Core versions of our library, using #if directives to conditionally compile code for a specific platform. Since this is hard to accomplish within a single VS 2017 project, I resorted to using two projects, a VS 2012 project for .NET Fx and a VS 2017 project for .NET Core. Both projects refer to the same codebase, allowing shared code and shared fixes. No need to maintain two codebases and manually sync code over.

We will also aim to target multiple .NET Framework versions with the same two projects and single codebase. You can always add more versions later using the same method.

Platform	Binaries Folder	Solution
.NET 2.0	net20	FluentFTP_NET_VS2012.sln
.NET 4.0	net40	FluentFTP_NET_VS2012.sln
.NET 4.5	net45	FluentFTP_NET_VS2012.sln
.NET Core 5.0	dnxcore50	FluentFTP_Core_VS2017.sln
.NET Standard 1.6	netstandard1.6	FluentFTP_Core_VS2017.sln

We will finally create a NuGet package to publish our library on NuGet and I will cover the required steps for creating a valid .nuspec, building your nuget package and even publishing your library on NuGet. Your library will install using NuGet on VS 2010, VS 2012 and VS 2017. This is the resultant .nupkg when viewed in the excellent NuGet Package Explorer.

.NET Core vs .NET Standard

Downloads

If you wish to download the completed project, you can grab the source code ZIP of FluentFTP 17.4.2 (latest as of 5^th June 2017) or you can download/fork the source from the github repository.

Included in the ZIP and the Github Repo

• Solution & project files for VS 2012 and VS 2017:
  • For VS 2012 & .NET Framework: FluentFTP_NET_VS2012.sln and FluentFTP.csproj
  • For VS 2017 & .NET Core: FluentFTP_Core_VS2017.sln and FluentFTP_Core.csproj
• The shared codebase (FluentFTP folder)
• Batch files to update .NET core packages (restore.bat) and build the nuget package (build_nuget.bat)
• Nuspec file for building nuget package (FluentFTP.nuspec)
• Key file for strong-name signing (sn.snk)

Only Included in the ZIP

• Pre-built binaries to show the folder structure (FluentFTP\bin)
• Pre-built nupkg file to show the final nuget package (FluentFTP\nuget\FluentFTP.17.4.2.nupkg)

Getting Started

CREATING PROJECTS FOR VS 2012 AND VS 2017

Use any method to create C# Library projects for VS 2012 and VS 2017. You may create new projects or use the ones I provided as a template.

Next, add build configurations for multiple .NET framework versions; open up the VS 2012 project and add build configurations using the UI, or modify the file by hand (as I did). The relevant files and changes required are listed in detail below:

FluentFTP_NET_VS2012.sln

Here, we have 3 sets of build configurations:

• Debug / Release - Builds .NET 4.5 version
• DebugNET4 / ReleaseNET4 - Builds .NET 4.0 version
• DebugNET2 / ReleaseNET2 - Builds .NET 2.0 version

FluentFTP.csproj

Here, we have the same build configurations as above, with one PropertyGroup per configuration. The relevant options are:

• DefineConstants - Add conditional compilation constants as per need (e.g., NETFX, NET2, NETFX45)
• OutputPath - Follow the standard naming system specified by nuget (net20 for .NET 2 and so on)
• TargetFrameworkVersion - The version of .NET you need

FluentFTP_Core.csproj

No changes are required to the solution file for VS 2017, however you must open up the .csproj in Notepad++ and ensure that certain key variables have been filled:

• TargetFrameworks - Very important. Here, I used netstandard1.6 and dnxcore50 (.NET Core 5.0) because I wanted to target both frameworks. If you need .NET Standard 1.4 you will need to add it here, or if you wish to target only .NET Standard, then remove the dnxcore50 moniker.
• DefineConstants - Add the CORE constant for conditional compilation of the shared codebase.
• NetStandardImplicitPackageVersion - We use .NET Standard 1.6.
• TargetFrameworkIdentifier - We use .NET Standard.
• TargetFrameworkVersion - We use .NET Standard 1.6.
• AssemblyOriginatorKeyFile - If you need strong name signing, specify your key file here.
• PackageReference(s) - Very important. Which assemblies in the .NET core framework you need for your library.
  • Start with System.IO and add more as you need later.
  • To know which references to add, refer to the "Referencing .NET classes" section.
  • To know which version number to fill in, visit the nuget page for the assembly and use the latest version offered.
  • Some assemblies are implicitly included, such as System.Runtime and System.Collections. However, you will still need to list these in the .nuspec file.

Creating the NUSPEC File

If you are not publishing for nuget, skip this. I recommend creating your .nuspec file by hand in Notepad++, using mine as a template. Key parameters are shown and detailed below:

• <frameworkAssemblies> contains any extra .NET Framework references you need. You need one entry per .NET Framework version you are publishing for, so in this case net20, net40 and net45.
• <dependencies> is a newer tag honored by newer nuget versions, used to specify every single .NET core dependency, even the obvious ones like System.Runtime and System.Collections.
  • Everytime you add a .NET core dependency, you must add it here as well (see the "Referencing .NET classes" section).
  • Although I placed <group> entries even for the .NET Framework versions, you are not required to fill anything in them, but add them in so newer nuget versions don't break.

Porting your Code

Once you've got all the projects setup, it's time to begin compiling and porting your library to .NET core. Fire up VS 2017 and open your .NET core solution. If you are using my template, the file you need is FluentFTP_Core_VS2017.sln. Hit compile. If using your library, you should see hundreds of errors. Don't worry! Most are trivially solved.

Useful Techniques

Use #if CORE to mark alternative code that .NET core needs. A common pattern is:

#if CORE
    socket.Close();
#else
    socket.Dispose();
#endif

And to "disable" code from compiling into your .NET core version:

#if !CORE
    // advanced code that only works on .NET framework
#endif

If you are compiling for .NET 2.0 as well, then you will need to guard your imports with:

#if (CORE || NETFX)
using System.Threading;
#endif
#if (CORE || NETFX45)
using System.Threading.Tasks;
#endif

Common Errors

• Cannot find type X - You need to find which .NET core assembly the required class is inside, and add a reference into your .NET Core .csproj and your .nuspec (if publishing for nuget). Remember to run restore.bat every time you add a reference or it the compile errors will not go away! For more information, see the "Referencing .NET classes" section.
• Method X is not available in type X - It might have been renamed or removed. To check, simply open the .NET Core API reference for the class in question and manually review the members it has.

Some Key Points

• Reflection is available in .NET core, but you need to reference the following:
  • System.Reflection
  • System.Reflection.Primitives
  • System.Reflection.Extensions
  • System.Reflection.TypeExtensions
  • If you need IL generation, then add System.Reflection.Emit and System.Reflection.Emit.ILGeneration
• Tasks and Threading and async/await are available, but you will have to reference the following:
  • System.Threading.Thread
  • System.Threading.Tasks
• Sockets are available, but you need to reference the following:
  • System.Net.Sockets.
  • System.Net.Security if you want SslStream.
  • Also, socket.Close() is now socket.Dispose()
• Async is supported (see above point) but the older IAsyncResult-based async is not supported. You will have to disable those sections using #if tags or upgrade to async/await.
• Serialization by converting data to and from Binary is unsupported, but XML, and JSON serialization is. (see System.Runtime.Serialization.Xml and System.Runtime.Serialization.Json)
• Bitmaps are unavailable (System.Drawing.Image) but for the geometry primitives like Point and Rect, see System.Drawing.Primitives.
• Crypto is available but many classes are renamed and refactored, for eg. new SHA1CryptoServiceProvider() is now SHA256.Create().
• StackTrace is available but you need the extra System.Diagnostics.StackTrace, so if it's not essential, you may want to remove from your code rather than add an additional dependency.
• DataTable and DataSet is not available in the System.Data namespace but other features like the provider model and SQL client are available.
• XAML is unsupported but if you are targeting UWP, you will have to use the Windows RT XAML APIs.

Some Key Missing Components (Source)

• System.AppDomain - App Domains
• System.Drawing.Image - Graphics, Bitmap Images
• System.DirectoryServices - LDAP, Active Directory
• System.Transactions - ambient transactions, distributed transactions
• System.Xml.Xsl - XSLT
• System.Xml.Schema - XSD
• System.Net.Mail - Sending Email
• System.Runtime.Remoting - Remoting, RPC
• System.Runtime.Serialization.Xml - Binary Serialization
• System.IO.Ports - Serial Port
• System.Workflow - Windows Workflow Foundation

Referencing .NET Classes

Many classes and methods are renamed or deleted in order to clean-up or modernize the API. Even the classes that have not been renamed need to be referenced in a specific way for the .NET core compiler to include them in your project. So when you want to use a .NET class, this is the process:

• Find the class on the online .NET core site (e.g., Directory) or using any of these other tools
• On the header, you will find Assemblies: System.IO.FileSystem.dll - this tells you the nuget package you need for that class (see the image below)
• Add that nuget package into your .NET core ".csproj" and your ".nuspec" file. (see the images below)
• Run the “dotnet restore” command to download the new assembly (run restore.bat)
• Add an import and use the class in your code.
• Hopefully by now it compiles, if not, try using the latest version of .NET standard (currently 1.6).

The .NET Core Docs

Adding a Reference into your .NET Core .csproj

Adding a Reference into your .nuspec

Creating your NuGet Package

Once you've got your libraries compiling and building, you probably want to release them to the world on NuGet. In case you haven't caught up, NuGet is a cool way to instantly and automatically pull in libraries (and all their dependencies) into a .NET project. It's bought by Microsoft and officially supported in Visual Studio.

To test creating a nuget package, run the build_nuget.bat. Any nuget related errors will show up in the console window. Fix them. Once everything is fine, you should see "Successfully created package XYZ" in the console.

Common errors:

• Missing parameters. The Nuspec format keeps changing, and if you have missing parameters, you will be informed by the nuget.exe when you try to build for it. Use Google to find default values for new paramaters.
• Incorrect assembly references. Nuget will sometimes warn you if assembly refs specified in the <dependencies> don't exist on Nuget. Open the nuget website (or one of these tools) and search for the exact name of the .NET core assembly you need.

Open up your nuget directory (located at FluentFTP\nuget in my template) and double-click the newly created .nupkg file to open up your NuGet package in the NuGet Package Explorer.

Common errors:

• Incorrect metadata. Remember that your nuspec must be valid XML, so you cannot use < and > in your metadata strings.
• No assemblies are shown on the file tree (right side). Check your <files> section in the .nuspec. To include all files in a certain directory, use this:
• XML

  <files>
     <file src="bin\Release\**" target="lib" />
  </files>

If all went well, you should see something like this:

Publishing to NuGet

I'm sure there are more automated ways to achieve this, but here are steps I use every time I need to push an update of the library to NuGet.

Compile Your Library

1. Increment version number in AssemblyInfo.cs
2. Increment version number in FluentFTP.nuspec
3. Increment version number in FluentFTP_Core.csproj
4. Open VS 2012 - Compile "NET Release", "Release_NET2", "Release_NET4"
5. Open VS 2017 - Compile "Release"

Build and Publish the Nuget PAckage

1. Run the 'build_nuget.bat' script to create a .nupkg
2. Visit this link at nuget to upload a package
3. Login to your nuget account (create one if you don't have one)
4. Browse to your nuget package (.nupkg)
5. Add "release notes" (limited markdown is supported such as bulleted lists)
6. Upload the package
7. You will get an email when you package has been "published"

Summary

While the .NET Core ecosystem is being actively improved by Microsoft, it still needs a lot of work especially on the documentation side before it becomes practical to work with. Porting a simple library took over a week of hard work, and although my tutorial should help with project configuration and compiling, there is still much effort required on the part of the developer during the porting and testing phases. There should have been a "one click" application porting tool that refactors your project to work with .NET core.

The hardest part was compiling it in a nuget friendly format (discovering the dnxcore50 moniker) and creating an valid "combined" nuspec for .NET framework and .NET core versions of the library.

I hope my tutorial helped you port your .NET library to .NET core, and if it did, add a comment below!

Thank you.

Useful Links

You will need these during your porting process to help find equivalent .NET core classes for .NET Framework classes. Sometimes a class has been renamed, or sometimes it's simply absent.

• .NET API Browser - Great tool by Microsoft that helps you find classes included in .NET core / .NET standard. You can type the name of a class, such as "stream" to see which similarly named classes are included.
• Reverse Package Search - Similar to the above, only you can search for classes and members! Type the name of a class and hit ENTER (it does not have "find as you type"). It lists all similarly named classes as well as details about which .NET core / .NET standard version that class is in.
• NuGet Search - Once you know which .NET core assembly you need, search nuget to get the exact package name, and to get the latest version, which you add into your .nuspec and your .csproj.
• .NET API Portability Analyzer - A tool from Microsoft which analyzes your project and highlights classes that are not available in .NET core. Never used it so I have no comments.
• Porting FluentFTP - The changes that were required to port FluentFTP from .NET Framework 4.0 to .NET Core 5.0 and .NET Standard 1.6. The link takes you to my github commit history for the same.

History

• 5 June, 2017 - First version of article with Intro, Review, Requirements, Objectives, .NET core vs .NET standard, Downloads, Getting started, Referencing .NET classes, Creating your NuGet Package, Publishing to NuGet, Useful links, and Summary.
• 6 June, 2017 - Added "up-to-date" note on top. Added NuGet to list of Requirements. Separated downloads that are only in the ZIP vs common stuff.
• 9 June, 2017 - Fix note about .NET core being "online only". Mention that offline also works.