AspNetCore.Docs/aspnetcore/migration/21-to-22.md

123 lines
4.6 KiB
Markdown

---
title: Migrate from ASP.NET Core 2.1 to 2.2
author: scottaddie
description: This article outlines the prerequisites and most common steps for migrating an ASP.NET Core 2.1 project to ASP.NET Core 2.2.
ms.author: scaddie
ms.custom: mvc
ms.date: 12/08/2018
uid: migration/21-to-22
---
# Migrate from ASP.NET Core 2.1 to 2.2
By [Scott Addie](https://github.com/scottaddie)
This article explains how to update an existing ASP.NET Core 2.1 project to ASP.NET Core 2.2.
[!INCLUDE[](~/includes/net-core-prereqs-all-2.2.md)]
## Update Target Framework Moniker (TFM)
Projects targeting .NET Core should use the [TFM](/dotnet/standard/frameworks#referring-to-frameworks) of a version greater than or equal to .NET Core 2.2. Update the `<TargetFramework>` node's inner text with `netcoreapp2.2`:
```xml
<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:
```xml
<TargetFramework>net461</TargetFramework>
```
## Adopt the IIS in-process hosting model
To adopt the [in-process hosting model for IIS](xref:fundamentals/servers/aspnet-core-module#in-process-hosting-model), add the `<AspNetCoreHostingModel>` property with a value of `InProcess` to a `<PropertyGroup>` in the project file:
```xml
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
```
For more information, see <xref:host-and-deploy/aspnet-core-module#hosting-model>.
## 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:
```console
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:
```xml
<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:
```xml
<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>
```
## Update .NET Core SDK version in global.json
If your solution relies upon a [global.json](/dotnet/core/tools/global-json) file to target a specific .NET Core SDK version, update its `version` property to the 2.2 version installed on your machine:
```json
{
"sdk": {
"version": "2.2.100"
}
}
```
## Call ConfigureKestrel instead of UseKestrel
If the app calls <xref:Microsoft.AspNetCore.Hosting.WebHostBuilderKestrelExtensions.UseKestrel*> in the `CreateWebHostBuilder` method of the `Program` class, call `ConfigureKestrel` instead to avoid conflicts with the [IIS in-process hosting model](xref:fundamentals/servers/aspnet-core-module#in-process-hosting-model):
```csharp
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 <xref:fundamentals/servers/kestrel#how-to-use-kestrel-in-aspnet-core-apps>.
## Update compatibility version
Update the compatibility version in `Startup.ConfigureServices` to `Version_2_2`:
```csharp
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
```
## 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.
## Additional resources
* <xref:mvc/compatibility-version>
* <xref:fundamentals/metapackage-app>
* [Implicit package references](/dotnet/core/tools/csproj#implicit-package-references)