Upgrading our .NET Core 3.1 project to .NET 5

Today we are going to upgrade our ASP.NET 3.1 website to the latest preview version of ASP.NET 5. While .NET 5 is not released until November 10th, there have been monthly preview releases, and with the release of release candidate 1, (or RC1), we felt this was the right time to test .NET 5 side by side with our existing 3.1 website, especially with the performance improvements. Using our existing Front Door implementation, we will split the workload 50/50 between the old 3.1 and new 5.0 websites. For this upgrade, we’ve elected to copy our existing project, “SamLearnsAzure.Web”, and created a new “SamLearnsAzure.Web2”. Everything except the project name will be identical between the two projects, with the same namespaces and code.

For those confused about the naming, make sure you check out this excellent blog post about the future roadmap of .NET. Essentially, .NET 5 is the next version of .NET Core.

Upgrading our project

First steps today, .NET 5 is still a preview, we will need to download the Visual Studio 2019 preview. Once we have this, we can open our project and start editing the project file, to select .NET 5.0.

Next, we need to update our NuGet packages. The easiest way to do this is to edit our project file, where we replaced all “3.1.8” versions with “5.0.0-rc.1.*”. We think this is a bit easier than using the NuGet manager, especially when the NuGet packages are in preview, to avoid opting into previews for other packages that aren’t required for the .NET 5 upgrade.

We successfully build and run the website. Since we show the .NET version in our about page, we can browse and see verification of the upgraded .NET version right there:

Updating the build in Azure DevOps

Next, we need to update the build process. The Azure DevOps hosted agents don’t have .NET 5 installed yet, (and won’t for some time), but we can download and use a specific version with the “UseDotNet” task. (Important: Note that as of 10-Nov-2020 and the release of .NET 5, you should use the version 5.0.100):

    - task: UseDotNet@2
      displayName: 'Install .Net 5 SDK'
      inputs:
        packageType: 'sdk'
        version: '5.0.100-rc.1.20452.10'

Next, we need to edit our “dotnet publish” step to create a self-contained package – as Azure web apps will not yet support .NET 5. Since we are using DotNetCoreCLI@2 task, we need to include two new properties:

• self-contained: Include the application and all of the .NET dependencies. The side effect of adding these dependencies is that this creates a larger package. The opposite of “self-contained” is “framework-dependent”, and is the default – this just includes the application and it’s direct dependencies
• runtime: This helps to self-contained command package the right dependencies. We are going to use “win-x86” today, but later we will experiment with 64 bit.

The final yaml for the publish is below:

    - task: DotNetCoreCLI@2
      displayName: 'Publish dotnet 5 project'
      inputs:
        command: publish
        publishWebProjects: false
        zipAfterPublish: true
        projects: |
         SamLearnsAzure/SamLearnsAzure.Web2/SamLearnsAzure.Web2.csproj
        arguments: '--configuration ${{parameters.buildConfiguration}} --output $(build.artifactstagingdirectory) --self-contained true --runtime win-x86'

We run our build, and can confirm that the artifacts are created as expected. Note that the “self-contained” package is 3 times the size of a “framework-dependent” package

Updating the app service

The final step is to update the app service to receive the package. We just need to ensure that the runtime is accurate (in our case, since we are using the Windows x86 runtime, we will need a “32 Bit” platform), and that our deployment removes any additional files – as we noted that deploying on top of a .NET Core 3.1 deployment caused issues until we removed these old files.

GitHub

For GitHub, it’s very similar, just slightly different syntax with the actions instead of tasks. We completed this same migration in our Feature Flags GitHub repo.

Wrap up

Today we upgraded our application to .NET 5, updated the Azure DevOps pipelines, and deployed it to an Azure app service. This was surprisingly easy, taking less than 10 minutes to update .NET 5 – with no compile errors. Hopefully this is a sign that going forward we will have less upgrade challenges!

We’ve started to see some others with similar experiences, notably, Nick at the Stackoverflow team, which is an extremely complex project

References

• Upgrade guidance: https://docs.microsoft.com/en-us/aspnet/core/migration/31-to-50?view=aspnetcore-3.1&tabs=visual-studio
• Upgrading to .NET 5: https://azure.github.io/AppService/2020/04/24/Running-.NET-5-Preview-on-App-Service.html
• Visual Studio 2019 Preview: https://visualstudio.microsoft.com/vs/preview/
• UseDotNet task: https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/tool/dotnet-core-tool-installer?view=azure-devops
• .NET publishing options: https://docs.microsoft.com/en-us/dotnet/core/deploying/
• Reference to help, on packaging .NET Core 3 apps as self-contained: https://timheuer.com/blog/deploy-aspnet-core-applications-using-self-contained-dotnet-core/