Converting PCL (Portable Class Libraries) to .NET Standard Class Libraries – Part 3
In Part 3 of this 3 part series, App Dev Manager, Herald Gjura describes how to incorporate these libraries into an existing .NET application.
In Part 1 and 2 of this blog series I described how to migrate your old PCL libraries into the .NET Standard ones, and how to change you build and release pipeline for a successful NuGet deployment. In this 3rd part I will describe how to incorporate these libraries into an existing .NET application.
In normal circumstances this should not be a topic of a discussion, as you should be able to simply pull the .NET Standard libraries into your application and get going. However, the tooling for these newer technologies is not fully ironed out just yet. Quite a few bugs have been reported to-date, and many hacks and adjustments have been reported in the usual internet code solution websites.
My intention is to go through some of the steps, and document some of the issues, as to save you some frustration and research time. Over time these issues will be resolved and this blog will become obsolete.
Incorporating .NET Standard Libraries
Create your new web application
Let’s go ahead and create a new web application. An existing web application would work the same way.
When prompted I selected to add Web API functionality to the applications, as it is easier to test. You don’t necessarily need to add this.
In the Part 1 of this series, I made the .NET Standard library to be compatible with .NET Standard 1.6 and .NET 4.6.2. In case you wonder why I chose .NET Standard 1.6 and not 2.0, there was no reason. The 2.0 version was not out yet, at the time of writing of that blog entry. You could easily have gone with 2.0 and the results would of have been the same, if not better.
In Visual Studio 2017, the default Web Application is set to .Net Framework 4.6.1. It is possible that your existing application may be in 4.6.1 or even 4.6. Follow carefully the next steps.
Issues that may be encountered
Pulling the .NET Standard NuGet package in an app with the wrong .NET Framework. Since the .NET Standard library is also compatible with .NET 4.6.2, it is implied that the application receiving it should be at least set at .NET Framework 4.6.2. Logically, you would think that is you pull the NuGet library, compatible with 4.6.2, into a 4.6.1 or lower application the Package Manager and/or Visual Studio 2017 would complain and fail it. But it doesn’t. It tries to upgrade whatever it can, and leave the application in strange state where it will not compile anymore.
It will throw endlessly an exception of the type: System.TypeInitializationException: ‘The type initializer for ‘<Type Name>’ threw an exception.’
Also, the inner exception: FileLoadException: Could not load file or assembly ‘<Name of library; Version; Culture, and PubliKeyToken>’ or one of its dependencies. The located assembly’s manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)
If you are getting these exceptions, it means you pulled the NuGet library in an app set at a lower .NET Framework version, and that the Visual Studio did not stop you and gave any warnings, and now you have some work to do.
During build, Visual Studio will flash a warning that some system libraries and other are installed in the wrong target framework. At this point you have 3 options:
– Leave these libraries as they are and reinstall them only when needed or when they create errors.
– The Visual Studio warning will give you an indication of which of the libraries are affected. You can than reinstall them one by one (Note: there may be a lot of them).
– In the Package Manager console, run the command: update-package –reinstall, and it will reinstall all the packages to the latest compatible version. Note: this is a radical measure that is appropriate for smaller application with fewer dependencies. Otherwise, this may create a lot of side-effects and unintended upgrades of packages.
Up to now I described what could go wrong. To avoid all of this, just do the following: before pulling in the .NET Standard libraries, upgrade your application to the .NET Framework 4.6.2.
Afterwards, you bring the NuGet package in either via Package Manager Console by running the command Install-Package <PackageName> or NuGet Manager tool.
At this point everything now should be working and your application should be compiling just fine.
.NET Standard NuGet package not compatible with the .NET Framework. In part 1, I made the .NET Standard library to be compatible with .NET Standard 1.6 and .NET Framework 4.6.2. What if I had not made it compatible with any .NET Framework, or if I was using a library that is not mine and is not compiled with any of the .NET Framework compatibility flags?
Again, in this case Visual Studio tooling will not be very helpful to you. It will pull the package successfully and not give you any warnings. However, the application will no longer run, and it will complain that libraries of a certain version cannot be found.
The solution for this is rather simple: you need to install the NETStandard.Library, either via Package Manager Console or NuGet Package Manager tool.
This completes the tasks on how to integrate the .NET Standard packages into your new or existing >NET applications.
In this three-part blog series, I provided a step-by-step guide on how to:
- Convert your old PCL packages (Part 1)
- Upgrade or create a new build and release pipeline, and publish your new NuGet packages in your private package server (Part 2)
- Integrate the .NET Standard packages into your existing applications (Part 3)
Hopefully this information was useful to you and it helped saving some valuable time.
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.