Migrate from ASP.NET Core 2.1 to 2.2

By Scott Addie

This article explains how to update an existing ASP.NET Core 2.1 project to ASP.NET Core 2.2.

Prerequisites

Update Target Framework Moniker (TFM)

Projects targeting .NET Core should use the TFM of a version greater than or equal to .NET Core 2.2. Update the <TargetFramework> node's inner text with netcoreapp2.2:

<TargetFramework>netcoreapp2.2</TargetFramework>

Projects targeting .NET Framework may continue to use the TFM of a version greater than or equal to .NET Framework 4.6.1:

<TargetFramework>net461</TargetFramework>

Adopt the IIS in-process hosting model

To adopt the in-process hosting model for IIS, add the <AspNetCoreHostingModel> property with a value of InProcess to a <PropertyGroup> in the project file:

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

For more information, see ASP.NET Core Module configuration reference.

Update package references

If targeting .NET Core, remove the Version attribute for the metapackage reference. Inclusion of a Version attribute results in the following warning:

A PackageReference to 'Microsoft.AspNetCore.App' specified a Version of `2.2.0`. Specifying the version of this package is not recommended. For more information, see https://aka.ms/sdkimplicitrefs

The metapackage reference should resemble the following <PackageReference /> node:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

If targeting .NET Framework, update each package reference's Version attribute to 2.2.0 or later. Here are the package references in a typical ASP.NET Core 2.2 project targeting .NET Framework:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.HttpsPolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.2.0" />
</ItemGroup>

If referencing the Microsoft.AspNetCore.Razor.Design package, update its Version attribute to 2.2.0 or later. Failure to do so results in the following error:

Detected package downgrade: Microsoft.AspNetCore.Razor.Design from 2.2.0 to 2.1.2. Reference the package directly from the project to select a different version.

Update .NET Core SDK version in global.json

If your solution relies upon a global.json file to target a specific .NET Core SDK version, update its version property to the 2.2 version installed on your machine:

{
  "sdk": {
    "version": "2.2.100"
  }
}

Update launch settings

If using Visual Studio Code, update the project's launch settings file (.vscode/launch.json). The program path should reference the new TFM:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            // If you have changed target frameworks, make sure to update the program path.
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchBrowser": {
                "enabled": true,
                "args": "${auto-detect-url}",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start ${auto-detect-url}"
                },
                "osx": {
                    "command": "open"
                },
                "linux": {
                    "command": "xdg-open"
                }
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

Call ConfigureKestrel instead of UseKestrel

If the app calls UseKestrel in the CreateWebHostBuilder method of the Program class, call ConfigureKestrel instead to avoid conflicts with the IIS in-process hosting model:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

For more information, see Kestrel web server implementation in ASP.NET Core.

Update compatibility version

Update the compatibility version in Startup.ConfigureServices to Version_2_2:

services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Update CORS policy

In ASP.NET Core 2.2, the CORS middleware responds with a wildcard origin (*) if a policy allows any origin and allows credentials. Credentials aren't supported when a wildcard origin (*) is specified, and browsers will disallow the CORS request. For more information, including options for correcting the problem on the client, see the MDN web docs.

To correct this problem on the server, take one of the following actions:

  • Modify the CORS policy to no longer allow credentials. That is, remove the call to AllowCredentials when configuring the policy.
  • If credentials are required for the CORS request to succeed, modify the policy to specify allowed hosts. For example, use builder.WithOrigins("https://api.example1.com", "https://example2.com") instead of using AllowAnyOrigin.

Update Docker images

The following table shows the Docker image tag changes:

2.1 2.2
microsoft/dotnet:2.1-aspnetcore-runtime microsoft/dotnet:2.2-aspnetcore-runtime
microsoft/dotnet:2.1-sdk microsoft/dotnet:2.2-sdk

Change the FROM lines in your Dockerfile to use the new image tags in the preceding table's 2.2 column.

Build manually in Visual Studio when using IIS in-process hosting

Visual Studio's Auto build on browser request experience doesn't function with the IIS in-process hosting model. You must manually rebuild the project when using in-process hosting. Improvements to this experience are planned for a future release of Visual Studio.

Additional resources