I’m working on a project written with Asp.Net MVC 5 were I work. We intend first upgrade our class libraries to .Net Standard as much as we can. Then we make the move to Asp.Net Core. But since we have many class libraries, I’ve decide to first do a little search about what is the best way to go about doing that. I’ve found a few resources, blog posts, videos and libraries which can help us with upgrade to Asp.Net Core. In this post, I’m going to share them with you.
.Net Portability Analyzer
I first started by using a tool called .net portability analyzer. It can help us to analyze our solution to see how portable it is. Then we can strategize about how we want to move on with our upgrade. So the first step is to install the analyzer for visual studio. This extension can be found in visual studio marketplace. Also there is a command line version which has more functionality than this extension, the command line version can be downloaded from here.
After installing this extension, we have the option to choose which framework we want to migrate to.
After that we can go ahead and analyze our solution for portability.
This extension generate a report for us, it can do this in three difference format, HTML, JSON and excel file. The excel version look something like this.
In the detail tab, we can see in detail which type is used and whether or not this type in available in the chosen frameworks. We can also generate the report in HTML and it gives us the availability of different APIs in a more readable format.
We can also use the command line to generate this report, but with more flexibility. For example if we want to detect the breaking changes we can use the following command.
ApiPort.exe analyze -f [your path]\Infrastructure\bin\Debug\net472 -b -r html
More on how to use the command line here.
Another tools which can be useful is a tool that help us change our project format from the old csproj to to the new one. It is called CsprojToVs2017. But in the current company we didn’t need this tool because all our projects already where in the latest format.
But even if it wasn’t the cause using this kind of tools is not recommended in Microsoft community. Damian Edwards (Asp.Net Program manager) recommends starting the migration by a clean project as opposed to using a migration tools to avoid bringing along unnecessary cruft. But if you’re interested to know how it works, Scott Hanselman upgrade a project using this tool in this video. Now that we got familiarize with couple of tools, let’s look at the our upgrade path.
Our Asp.Net Core Upgrade Path
Our upgrade path started by upgrading our libraries to .Net Standard. Upgrading our project to .Net Standard is ideal, but as it turns out it is not necessary if we want to start using Asp.Net Core. Not to mention that we were using some feature that existed in full .Net and not .Net Core. Let’s have a look at .Net Core, .Net Stardard and other frameworks first as it relate to our case.
As you can see the .Net Standard have the most flexibility in terms of usage across different platform. But we had a few projects that were not usable on .Net Standard. For these project we decide for now we go with using full .Net. That meant that we couldn’t go cross platform. But that wasn’t our focus in this upgrade. Another point was that test projects cannot use .Net Standard. It should either be a full .net framework project or a .Net Core project.
How Did We Start The Upgrade to Asp.Net Core?
There are couple of problems we faced which made it difficult to fully migrate the libraries to .Net Standard. Even though those libraries themselves don’t have a irreplaceable dependency. But they depends on the projects that are using the full .Net core.
<ProjectReference Include="..Infrastructure.csproj" />
Now if we upgrade those projects, the project is going to build but with a warning that basically says.
warning NU1701: Package ‘Microsoft.AspNet.Razor 3.2.7’ was restored using ‘.NETFramework,Version=v4.6.1, .NETFramework,Version=v4.6.2, .NETFramework,Version=v4.7, .NETFramework,Version=v4.7.1, .NETFramework,Version=v4.7.2, .NETFramework,Version=v4.8’ instead of the project target framework ‘.NETStandard,Version=v2.0’. This package may not be fully compatible with your project.
This is not a problem in and of itself, but because of full .Net dependency, these projects have problem loading certain other dependencies. For example I tried to upgrade a test project into .Net Core, but the test projects could not load the System.Runtime.Remoting. That why it is recommended that we upgrade all projects eventually to prevent this kinds of problems. So what did we do? As it turns out we can have a libraries which runs on full .Net and reference it in our Asp.Net Core app. The only issue that this can cause is that we can’t host our app on Linux which at this stage we didn’t want to do anyway.
This is the assumption that I see a lot of people have about the upgrade. We don’t need to upgrade everything to .Net Core/Standard packages. If there’s a dependency that cannot be resolved with .Net Core cross platform packages, we can simply use full .Net framework for that by using <TargetFramework>net472</TargetFramework> for example. That means we don’t have any problem! Upgrading to Asp.Net Core (hopefully).
Using a Dependency Graph
Another tool which can be useful in our planning is a architectural graph. We can generate it using visual studio or we used Resharper in this case. By analyzing this information we can see what are the most difficult project to upgrade. The project with the most dependencies are going to cause the most pains.
Our Final Plan for Upgrade to Asp.Net Core
- First we migrate the least important projects to Asp.Net Core, this can help us to warm up for the upgrade and face the issues that we might face in a project that are not critically important.
- Then We migrate the main web project to Asp.Net Core (which involved upgrading EF and EF Identity). By this time we have a good idea about all the problems that we might face from our previous upgrade.
- Then we than can move on to upgrading the most referenced projects. Because we already upgraded a large portion of our app, upgrading heavily referenced class libraries are going to get easier.
- Once we’ve done with upgrading the most referenced projects, migrating other projects becomes very easy.
- If there are projects which we can’t migrate to .Net Standard/.Net Core because the equivalent functionality does not exist in those libraries, we use the full .Net framework or we can host it as an API and use it independently over the wire.
Please feel free to share your ideas in the comments section if you think there might be a better approach to upgrade.
The .NET Portability Analyzer
.NET Portability Analyzer (Console application)
Migrate from ASP.NET to ASP.NET Core
How to Migrate a Project From ASP.NET MVC to ASP.NET Core
In this post I introduced some tools that helps us with our Upgrade to Asp.Net Core. Some of these tools help us with creating an upgrade plans, others automate certain tasks. Then I discussed the upgrade path that I’ve come up with for my project.