In Part 1 of this 3 part series, App Dev Manager, Herald Gjura discusses converting PCL (Portable Class Libraries) to .NET Standard Class Libraries.
I have been working for this client for quite a few years and had advised them to break down some of their key business functionality and features and distribute them as NuGet packages.
With the introduction of the mobile apps, most of these packages were re-packaged again as PCLs to be used in Xamarin cross platform applications.
During this process of continuous refactoring, things evolved again. There was a migration from TFS to VSTS and rewriting of the build and release processes.
PCLs were great as a solution to the problem of what they were trying to solve, however, they were cumbersome and prone to all sort of issues and inconsistencies. I always thought of them as a temporary bridge to something that was coming later. Eventually PCLs and their technology were marked for extinction and the natural next step is now to migrate toward the .NETStandard model.
The purpose of this blog is to document this last refactoring effort in order to help anyone that is going through the same process.
One thing I did from the beginning is to migrate to Visual Studio 2017.
I have seen some writing out there, documenting part of what is to follow being done in older versions of VS, but it will get increasingly complicated very fast, to the point that I would question the added complexity and effort vs just migrating to VS 2017 first.
If for any reason you cannot migrate to VS 2017, I suggest you wait and live with the PCLs as they are, until you are able to make the migration.
From PCL to .NET Standard Core Libraries
My first instinct when I started this process was to just simply upgrade the PCL to use the .NetStandard by changing the target framework, but I was wrong.
With Visual Studio 2017, the tooling and build functionality for packages has changed. Many new and welcomed features have been introduced that makes this process much easier.
So the right approach is to recreate the project as a .NET Standard Class Library. Here is what I did and the steps I followed.
1) Go to the original folder of your PCL project. (Make a zip backup of the project, in case something goes terribly wrong and you need to restore). Navigate to where the project files are and delete all project related files and folders (see image on how they look for my package library solution and project). Do NOT remove any of the .git folders or .gitattributes and .gitignores files.
2) Open Visual Studio 2017 and create a new solution/project by choosing the Class Library (.NET Standard) project template (see image on how this looks for me and where to find it).
a. In name type the name of the old PCL project (unless you really intend to give the package a new name).
b. Keep unchecked the Create directory for solution
c. Keep unchecked the Create new Git repository
d. In Location make sure you place the new solution files at the same place where the old PCL solution files where.
3) Open the newly created solution and follow some of these steps:
a. Delete the Class1.cs that was created.
b. In Solution Explorer click Show All Files and add any new files and folders that are there form the older PCL library.
c. Note that if you were using any nuspec files or command line file to create the package you will not need them anymore. Keep them for now to extract information, but be ready to remove them later.
d. Make sure that you are targeting .NET Standard 1.6 as a target framework. Some of the packages you were previously using may only be available for this target only.
e. Restore the nuget packaged you were using in the old PCL .Some refactoring and manual debugging may need to take place here to get it everything right.
f. Rebuild the solution.
Note that some older public nuget packages may have not been updated to support .NETStandard. At this point you should judge the situation yourself in a case by case scenario if you need to proceed further or roll back to where everything was.
In my case, for a large number of PCL libraries, at this point the solution will build just fine, without additional refactoring efforts needed. Some more optional steps to follow:
4) Open up in a text editor (Notepad or Notepad++) the .csproj file, and we will take a look at some of the changes we will make in there. You will see that the format of the .csproj file has changed significantly.
a. If you want your new .NETStandard library to be available and compatible with other standards and frameworks make the following change: Change the <TargetFramework> tag to <TargetFrameworks> (note it is now in plural) and the content as net462;netstandard1.6. This will make the library compatible and available for both .NET 4.6.2 and .NETStandard 1.6.
b. You should also go ahead and delete the metadata in the nuspec file and add it to the .csproj file. You may also delete the nuspec file at this time.
5) If you have any test project that tests the functionality of the package, they will not work anymore with the .NETStandard packages. You will need a >NET Core Test project for that.
a. Go ahead and create a new .NET Core Test Project
b. Cut and paste all the old test files into the new .NET core project
c. Compile the test project and refactor and issues with the tests.
At this point, all the work we had to do in Visual Studio and with the code is complete. We should look now into the deployment and release tasks of VSTS.
Premier Support for Developers provides strategic technology guidance, critical support coverage, and a range of essential services to help teams optimize development lifecycles and improve software quality. Contact your Application Development Manager (ADM) or email us to learn more about what we can do for you.