Migrating to ASP.NET Core 2.0

Before we get under way talking about migrating a simple ASP.NET Core 1.1 app to 2.0, we need to keep in mind that 1.1.2 is under LTS support, and that upgrading to 2.0 might not be for you. If you want more information on the current support levels of the various versions of .NET Core, you can find that here.

If you’ve decided to go ahead and want to migrate to 2.0, you’ll also need the 2.0 SDK if you haven’t already installed it. You can find that here.

Once installed, you can use the 2.0 SDK to code against 1.1 applications if you want, and I can confirm this because I’ve removed all previous versions of the SDK from my system and had a good play around with older projects.

Also, please note that I’ll be using VS 2017 for this article. It uses the new csproj file and is upgraded to the latest version; this is required. If you’re using a 1.1 application under VS 2015, you may still be using the old project.json. If this is the case, you can find assistance here…

Upgrading to 2.0

I’m going to walk through the upgrade using an empty 1.1 ASP.NET Core application, using the template provided by VS. And, the first thing we need to do is change our target framework. Edit the project’s csproj file, and you can use Figure 1 as a reference. Right-click the project and click ‘Edit *.csproj.’

Figure 1: Editing the csproj file

If you’re new to VS 2017, you now are able to edit the csproj file while the project is open. There is no need to unload the project first. And, once we have this file open, we need to change this line:

<TargetFramework>netcoreapp1.1</TargetFramework>

to

<TargetFramework>netcoreapp2.0</TargetFramework>

Also, while we’re in the csproj file, we can update our package references. For example, we can change this line:

<ItemGroup>
   <PackageReference Include="Microsoft.AspNetCore"
      Version="1.1.2" />
</ItemGroup>

to

<ItemGroup>
   <PackageReference Include="Microsoft.AspNetCore.All"
      Version="2.0.0" />
</ItemGroup>

Now, once you’ve done this, go ahead and upgrade any of your other packages as needed. However, keep in mind that, in some cases, it may be better to stick with the lowest version possible.

The next thing, while we’re looking at the package references, is to upgrade any CLI tool references as needed. For example, you may be using Entity Framework Core while at the same time using the CLI to create migrations and update your database. This update would look something like this…

<DotNetCliToolReference Include
   "Microsoft.EntityFrameworkCore.Tools.DotNet"
   Version="2.0.0"/>

Moving away from the csproj, let’s turn our attention to the Program.cs. A 1.1 app would have code that looks something like this:

public static void Main(string[] args)
{
   var host = new WebHostBuilder()
      .UseKestrel()
      .UseContentRoot(Directory.GetCurrentDirectory())
      .UseIISIntegration()
      .UseStartup<Startup>()
      .UseApplicationInsights()
      .Build();

   host.Run();
}

In 2.0, this has been simplified and now looks something like this…

public class Program
{
   public static IWebHost BuildWebHost(string[] args) =>
      WebHost
      .CreateDefaultBuilder(args)
      .UseStartup<Startup>()
      .Build();

   public static void Main(string[] args)
   {
      BuildWebHost(args).Run();
   }
}

This new format is recommended and even required in some situations.

Finally, let’s make a small change to your global.json to target the new SDK. If your project is missing one, as is the case with some templates for new projects, you can use Figure 2 as a reference and place it.

Figure 2: The global.json file

If you only have the 2.0 SDK installed, I find that leaving out the global.json is an option and it will, of course, default to the only available SDK on your system.

Now, the content of the global.json looks like this…

{
   "sdk": { "version": "2.0.0" }
}

At this point, you should be able to build the application, and run it. I’ve edited my final middleware component in the Statup.cs to look like this:

app.Run(async (context) =>
{
   await context.Response.WriteAsync("Hello World from
      Code Guru!");
});

Figure 3: The application running under ASP.NET Core 2.0

Conclusion

Given that we used only a simple application to demonstrate the migration project here, I’ve completed the steps shown here on much large projects without issue. However, as we said at the start, I would recommend taking the needed time to decide whether the upgrade is needed, but with all new projects I would heartily recommend starting with .NET Core 2.0.

If you have any questions about this article, you can always find me on Twitter @GLanata.