293 lines
11 KiB
Markdown
293 lines
11 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: 05/28/2019
|
|
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.
|
|
|
|
## Prerequisites
|
|
|
|
# [Visual Studio](#tab/visual-studio)
|
|
|
|
[!INCLUDE[](~/includes/net-core-prereqs-vs2019-2.2.md)]
|
|
|
|
# [Visual Studio Code](#tab/visual-studio-code)
|
|
|
|
[!INCLUDE[](~/includes/net-core-prereqs-vsc-2.2.md)]
|
|
|
|
# [Visual Studio for Mac](#tab/visual-studio-mac)
|
|
|
|
[!INCLUDE[](~/includes/net-core-prereqs-mac-2.2.md)]
|
|
|
|
---
|
|
|
|
## Update Target Framework Moniker (TFM)
|
|
|
|
Projects targeting .NET Core should use the [TFM](/dotnet/standard/frameworks) of a version greater than or equal to .NET Core 2.2. In the project file, 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:host-and-deploy/iis/index#in-process-hosting-model), add the `<AspNetCoreHostingModel>` property with a value of `InProcess` to a `<PropertyGroup>` in the project file:
|
|
|
|
```xml
|
|
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
|
|
```
|
|
|
|
The in-process hosting model isn't supported for ASP.NET Core apps targeting .NET Framework.
|
|
|
|
For more information, see <xref:host-and-deploy/aspnet-core-module#hosting-models>.
|
|
|
|
## Update a custom web.config file
|
|
|
|
For projects that use a custom *web.config* file in the project root to generate their published *web.config* file:
|
|
|
|
* In the `<handlers>` entry that adds the ASP.NET Core Module (`name="aspNetCore"`), change the `modules` attribute value from `AspNetCoreModule` to `AspNetCoreModuleV2`.
|
|
* In the `<aspNetCore>` element, add the hosting model attribute (`hostingModel="InProcess"`).
|
|
|
|
For more information and example *web.config* files, see <xref:host-and-deploy/aspnet-core-module#configuration-with-webconfig>.
|
|
|
|
## Update package references
|
|
|
|
If targeting .NET Core, remove the metapackage reference's `Version` attribute in the project file. 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
|
|
```
|
|
|
|
For more information, see <xref:fundamentals/metapackage-app>.
|
|
|
|
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>
|
|
```
|
|
|
|
If referencing the [Microsoft.AspNetCore.Razor.Design](https://www.nuget.org/packages/Microsoft.AspNetCore.Razor.Design/) package, update its `Version` attribute to 2.2.0 or later. Failure to do so results in the following error:
|
|
|
|
```console
|
|
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](/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"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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:
|
|
|
|
[!code-json[](21-to-22/samples/launch.json?highlight=9)]
|
|
|
|
## Update Kestrel configuration
|
|
|
|
If the app calls <xref:Microsoft.AspNetCore.Hosting.WebHostBuilderKestrelExtensions.UseKestrel*> by calling `CreateDefaultBuilder` in the [CreateWebHostBuilder method](xref:fundamentals/host/web-host#set-up-a-host) of the `Program` class, call `ConfigureKestrel` to configure Kestrel server instead of `UseKestrel` in order to avoid conflicts with the [IIS in-process hosting model](xref:host-and-deploy/iis/index#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
|
|
});
|
|
```
|
|
|
|
If the app doesn't call `CreateDefaultBuilder` and builds the host manually in the `Program` class, call <xref:Microsoft.AspNetCore.Hosting.WebHostBuilderKestrelExtensions.UseKestrel*> **before** calling `ConfigureKestrel`:
|
|
|
|
```csharp
|
|
public static void Main(string[] args)
|
|
{
|
|
var host = new WebHostBuilder()
|
|
.UseContentRoot(Directory.GetCurrentDirectory())
|
|
.UseKestrel()
|
|
.UseIISIntegration()
|
|
.UseStartup<Startup>()
|
|
.ConfigureKestrel((context, options) =>
|
|
{
|
|
// Set properties and call methods on options
|
|
})
|
|
.Build();
|
|
|
|
host.Run();
|
|
}
|
|
```
|
|
|
|
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 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](https://developer.mozilla.org/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials).
|
|
|
|
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 <xref:Microsoft.AspNetCore.Cors.Infrastructure.CorsPolicyBuilder.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 <xref:Microsoft.AspNetCore.Cors.Infrastructure.CorsPolicyBuilder.AllowAnyOrigin*>.
|
|
|
|
## Update Docker images
|
|
|
|
The following table shows the Docker image tag changes:
|
|
|
|
| 2.1 | 2.2 |
|
|
| ----------------------------------------- | ----------------------------------------- |
|
|
| `microsoft/dotnet:2.1-aspnetcore-runtime` | `mcr.microsoft.com/dotnet/core/aspnet:2.2` |
|
|
| `microsoft/dotnet:2.1-sdk` | `mcr.microsoft.com/dotnet/core/sdk:2.2` |
|
|
|
|
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](xref:host-and-deploy/iis/index#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.
|
|
|
|
## Update logging code
|
|
|
|
Recommended logging configuration code didn't change from 2.1 to 2.2, but some 1.x coding patterns that still worked in 2.1 no longer work in 2.2.
|
|
|
|
If your app does logging provider initialization, filtering, and configuration loading in the `Startup` class, move that code to `Program.Main`:
|
|
|
|
* Provider initialization:
|
|
|
|
1.x example:
|
|
|
|
```csharp
|
|
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
|
|
{
|
|
loggerFactory.AddConsole();
|
|
}
|
|
```
|
|
|
|
2.2 example:
|
|
|
|
```csharp
|
|
|
|
public static void Main(string[] args)
|
|
{
|
|
var webHost = new WebHostBuilder()
|
|
// ...
|
|
.ConfigureLogging((hostingContext, logging) =>
|
|
{
|
|
logging.AddConsole();
|
|
})
|
|
// ...
|
|
}
|
|
```
|
|
|
|
* Filtering:
|
|
|
|
1.x example:
|
|
|
|
```csharp
|
|
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
|
|
{
|
|
loggerFactory.AddConsole(LogLevel.Information);
|
|
// or
|
|
loggerFactory.AddConsole((category, level) =>
|
|
category == "A" || level == LogLevel.Critical);
|
|
}
|
|
```
|
|
|
|
2.2 example:
|
|
|
|
```csharp
|
|
public static void Main(string[] args)
|
|
{
|
|
var webHost = new WebHostBuilder()
|
|
// ...
|
|
.ConfigureLogging((hostingContext, logging) =>
|
|
{
|
|
logging.AddConsole()
|
|
.AddFilter<ConsoleLoggerProvider>
|
|
(category: null, level: LogLevel.Information)
|
|
// or
|
|
.AddFilter<ConsoleLoggerProvider>
|
|
((category, level) => category == "A" ||
|
|
level == LogLevel.Critical)
|
|
);
|
|
})
|
|
// ...
|
|
}
|
|
```
|
|
|
|
* Configuration loading:
|
|
|
|
1.x example:
|
|
|
|
```csharp
|
|
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
|
|
{
|
|
loggerFactory.AddConsole(Configuration);
|
|
}
|
|
```
|
|
|
|
2.2 example:
|
|
|
|
```csharp
|
|
public static void Main(string[] args)
|
|
{
|
|
var webHost = new WebHostBuilder()
|
|
// ...
|
|
.ConfigureLogging((hostingContext, logging) =>
|
|
{
|
|
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
|
|
logging.AddConsole();
|
|
})
|
|
// ...
|
|
}
|
|
```
|
|
|
|
For more information, see <xref:fundamentals/logging/index>
|
|
|
|
## Additional resources
|
|
|
|
* <xref:mvc/compatibility-version>
|
|
* <xref:fundamentals/metapackage-app>
|
|
* [Implicit package references](/dotnet/core/tools/csproj#implicit-package-references)
|