With the introduction of ASP.NET Core 1.1 RTM I decided it would be worth attempting the upgrade process.
Whilst this post is primarily intended to remind myself of the steps required to upgrade an ASP.NET Core 1.0 application, it makes sense to share this with others who want to update their own.
This tutorial makes the following assumptions:
- The .NET Core 1.1 SDK has already been installed
- A previous installation of the .NET Core 1.0 SDK exists
- In this demonstration I am using 1.0.3
- You’ve already installed a code editor
- I will be using Visual Studio Code due to running macOS
Multiple .NET Core Installations
Before we get onto the actual upgrade process it’s worth spending a minute looking at how multiple versions of .NET Core are managed on a given system.
Regardless of how many versions you install of the .NET Core SDK they will never intefer with each other as they’re isolated to their own execution folder.
On macOS you can find all .NET Core SDK installations in the /usr/local/share/dotnet/sdk folder:
The installation depicted in the screenshot shows that the SDKs installed are:
- .NET Core SDK 1.1
- .NET Core SDK 1.0.3
Executing the .NET Core CLI will always run from the latest SDK version available unless overridden by the sdk attribute defined inside the global.json file for a given .NET Core project.
For further information on the relationship between SDK versions and how to maintain them across projects, read Nicolò Carandini’s great post on the subject.
Setting the scene
I have created an empty directory on my machine called ASPNET_Upgrade which will be the basis for the initial ASP.NET Core 1.0 application. This will be referred to as the “working directory” in subsequent steps.
As we have multiple versions of the .NET SDK on our machine we need to ensure the given ASPNET_Upgrade project is focused on the 1.0.3 installation.
Create a file called global.json in the working directory with the following content:
"projects": [ "src" ],
"version": "1.0.0-preview2-003156" }
Verify the correct .NET SDK version is referenced by running “dotnet –version” in the working directory:
If the output does not match the value defined in the version attribute double check the global.json file for mistakes.
With the version verified the next step is to run “dotnet new -type web” in the working directory to generate the default ASP.NET Core 1.0 project structure.
Executing “dotnet restore” followed by “dotnet build” will provide the following output:
Take note of the initial line of output – “(.NETCoreApp,Version=v1.0)”, this shows our application currently targets ASP.NET Core 1.1. Now we’re ready to start the upgrade process.
In order to upgrade the existing ASP.NET Core 1.0 application we need to:
- Update the SDK version specified in global.json
- Update two .NET Core framework references in project.json
- Update ASP.NET Core dependencies to version 1.1.0
Updating the SDK Version
Go to the working directory, open the global.json file and change the sdk value to match the version representing SDK v1.1 before saving changes:
Updating .NET Core Framework references
Go to the working directory, open the project.json file and update the version of the Microsoft.NETCore.App dependency to 1.1.0:
In the same file find the netcoreapp1.0 framework reference and update it to netcoreapp1.1:
Save both changes to this file, but don’t close it just yet.
Updating ASP.NET Core dependencies
The project.json file contains numerous ASP.NET Core NuGet packages that need to be updated to the 1.1.0 version number. The fully fledged IDE version of Visual Studio has a GUI for updating NuGet packages however this is missing from Visual Studio Code. Fortunately it’s still possible to update the packages using Visual Studio Code as it will provide available version numbers via IntelliSense when you delete the current one.
Verify you have updated all listed dependencies and save the changes. Your list should look something like this:
To verify that the ASP.NET Core Application has been updated to version 1.1:
- Run “dotnet restore” from within the working directory – this will retrieve 1.1.0 package dependencies from NuGet
- Run “dotnet build” from the working directory. This will compile the ASP.NET Core application using the 1.1 SDK framework because of our global.json change.
Verify that the output reads “(.NETCoreApp,Version=v1.1)” to signify the application is running against ASP.NET Core 1.1, otherwise review the previous steps to ensure everything is in order.
Congratulations, your application is now running on ASP.NET Core 1.1!
With your application updated there are a few avenues you can explore.
Updating your Docker base image
If you’re leveraging Docker, update the base image within your Dockerfile to reflect ASP.NET Core 1.1.
Favour the aspnet image instead of dotnet as it’s optimised for ASP.NET Core tasks, not to mention it contains images for all ASP.NET Core libraries for improved cold start performance.
Implement ASP.NET Core 1.1 features
The introduction of ASP.NET Core 1.1 includes a number of additions to improve your application, and one feature in particular deserves a mention – HTTP response compression.
Whilst response compression is nothing new to ASP.NET Core the existing solutions were bespoke, created by those who wanted to cover the gap in functionality and share it with others.
Fortunately with the ASP.NET Core 1.1 HTTP response compression is built into the framework and exposed to the user via middleware, a clean and extensible solution. The steps to introduce this to your application are minimal and worth implementing if you want to reduce the footprint of your http responses.