从 ASP.NET Core 2.1 迁移到 2.2Migrate from ASP.NET Core 2.1 to 2.2

本文内容

作者：Scott Addie

本文介绍如何将现有 ASP.NET Core 2.1 项目更新为 ASP.NET Core 2.2。

系统必备Prerequisites

警告

如果使用 Visual Studio 2017，请参阅 dotnet/sdk 问题 #3124，以了解无法与 Visual Studio 一起使用的 .NET Core SDK 版本的信息。

Visual Studio Code 说明使用用于 ASP.NET Core 的 .NET Core CLI 开发功能，如项目创建。可在任何平台（macOS、Linux 或 Windows）上或在任何代码编辑器中遵循这些说明。如果使用 Visual Studio Code 以外的其他内容，则可能需要进行少量更改。

更新目标框架名字对象 (TFM)Update Target Framework Moniker (TFM)

面向 .NET Core 的项目需使用 .NET Core 2.2 版或更高版本的 TFM。在项目文件中，通过 netcoreapp2.2 更新 <TargetFramework> 节点的内部文本：

  1. <TargetFramework>netcoreapp2.2</TargetFramework>

面向 .NET Framework 的项目需继续使用 .NET Framework 4.6.1 版或更高版本的 TFM：

  1. <TargetFramework>net461</TargetFramework>

采用的 IIS 进程内承载模型Adopt the IIS in-process hosting model

若要采用 IIS 进程内托管模型，请将值为 InProcess 的 <AspNetCoreHostingModel> 属性添加到项目文件中的 <PropertyGroup>：

  1. <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

面向 .NET Framework 的 ASP.NET Core 应用不支持进程内托管模型。

有关详细信息，请参阅 ASP.NET Core 模块。

更新自定义 web.config 文件Update a custom web.config file

对于项目根中使用自定义 web.config 文件的项目，要生成发布的 web.config 文件，请执行以下操作：

  • 在添加 ASP.NET Core 模块 (name="aspNetCore") 的 <handlers> 项中，将 modules 属性值从 AspNetCoreModule 更改为 AspNetCoreModuleV2。
  • 在 <aspNetCore> 元素中，添加托管模型特性 (hostingModel="InProcess")。

有关详细信息和 web.config 文件的示例，请参阅 ASP.NET Core 模块。

更新包引用Update package references

如果面向 .NET Core，则在项目文件中删除元包引用的 Version 特性。包含 Version 特性会导致出现以下警告：

  1. 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

有关详细信息，请参阅 ASP.NET Core 的 Microsoft.AspNetCore.App 元包。

元包引用应类似于以下 <PackageReference /> 节点：

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

如果面向 .NET Framework，请将每个包引用的 Version 属性更新到 2.2.0 或更高版本。以下是面向 .NET Framework 的典型 ASP.NET Core 2.2 项目中的包引用：

  1. <ItemGroup>
  2.   <PackageReference Include="Microsoft.AspNetCore" Version="2.2.0" />
  3.   <PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.2.0" />
  4.   <PackageReference Include="Microsoft.AspNetCore.HttpsPolicy" Version="2.2.0" />
  5.   <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  6.   <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.2.0" />
  7. </ItemGroup>

如果引用 Microsoft.AspNetCore.Razor.Design 包，请将其 Version 特性更新为 2.2.0 或更高版本。否则，会导致出现以下错误：

  1. 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.

在 global.json 中更新 .NET Core SDK 版本Update .NET Core SDK version in global.json

如果解决方案依靠 global.json 文件来定向于特定 .NET Core SDK 版本，请将其 version 属性更新为计算机上安装的 2.2 版本：

  1. {
  2.   "sdk": {
  3.     "version": "2.2.100"
  4.   }
  5. }

更新启动设置Update launch settings

如果使用 Visual Studio Code，请更新项目的启动设置文件 (.vscode/launch.json)。program 路径应引用新 TFM：

  1. {
  2.     "version": "0.2.0",
  3.     "configurations": [
  4.         {
  5.             "name": ".NET Core Launch (web)",
  6.             "type": "coreclr",
  7.             "request": "launch",
  8.             "preLaunchTask": "build",
  9.             "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
  10.             "args": [],
  11.             "cwd": "${workspaceFolder}",
  12.             "stopAtEntry": false,
  13.             "internalConsoleOptions": "openOnSessionStart",
  14.             "launchBrowser": {
  15.                 "enabled": true,
  16.                 "args": "${auto-detect-url}",
  17.                 "windows": {
  18.                     "command": "cmd.exe",
  19.                     "args": "/C start ${auto-detect-url}"
  20.                 },
  21.                 "osx": {
  22.                     "command": "open"
  23.                 },
  24.                 "linux": {
  25.                     "command": "xdg-open"
  26.                 }
  27.             },
  28.             "env": {
  29.                 "ASPNETCORE_ENVIRONMENT": "Development"
  30.             },
  31.             "sourceFileMap": {
  32.                 "/Views": "${workspaceFolder}/Views"
  33.             }
  34.         },
  35.         {
  36.             "name": ".NET Core Attach",
  37.             "type": "coreclr",
  38.             "request": "attach",
  39.             "processId": "${command:pickProcess}"
  40.         }
  41.     ]
  42. }

更新 Kestrel 配置Update Kestrel configuration

如果应用通过调用 Program 类 CreateWebHostBuilder 方法 中的 CreateDefaultBuilder 来调用 UseKestrel，请调用 ConfigureKestrel 而非 UseKestrel 来配置 Kestrel 服务器，以避免与 IIS 进程内托管模型发生冲突：

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

如果应用不调用 CreateDefaultBuilder 并在 Program 类中手动生成主机，请在调用 ConfigureKestrel之前调用 UseKestrel：

  1. public static void Main(string[] args)
  2. {
  3.     var host = new WebHostBuilder()
  4.         .UseContentRoot(Directory.GetCurrentDirectory())
  5.         .UseKestrel()
  6.         .UseIISIntegration()
  7.         .UseStartup<Startup>()
  8.         .ConfigureKestrel((context, options) =>
  9.         {
  10.             // Set properties and call methods on options
  11.         })
  12.         .Build();
  14.     host.Run();
  15. }

有关详细信息，请参阅 ASP.NET Core 中的 Kestrel Web 服务器实现。

更新兼容性版本Update compatibility version

将 Startup.ConfigureServices 中的兼容性版本更新为 Version_2_2：

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

更新 CORS 策略Update CORS policy

在 ASP.NET Core 2.2 中，如果策略允许任何来源并允许凭据，则 CORS 中间件会使用通配符源 () 进行响应。如果指定通配符源 ()，则不支持凭据，并且浏览器将不允许 CORS 请求。有关详细信息，包括如何在客户端解决此问题的选项，请参阅 MDN Web 文档。

若要在服务器上解决此问题，请执行下列操作之一：

更新 Docker 映像Update Docker images

下表显示了 Docker 映像标记更改：

2.12.2
microsoft/dotnet:2.1-aspnetcore-runtimemcr.microsoft.com/dotnet/core/aspnet:2.2
microsoft/dotnet:2.1-sdkmcr.microsoft.com/dotnet/core/sdk:2.2

将 Dockerfile 中的 FROM 行更改为使用上表的 2.2 列中的新映像标记。

使用 IIS 进程内托管时，在 Visual Studio 中手动生成Build manually in Visual Studio when using IIS in-process hosting

Visual Studio 的“在浏览器请求时自动生成”体验无法与 IIS 进程内托管模型一起使用。使用进程内托管时，必须手动重新生成项目。我们已计划对 Visual Studio 的未来版本改进此体验。

更新日志记录代码Update logging code

建议的日志记录配置代码未从 2.1 更改为 2.2，但在 2.1 中仍然有效的某些 1.x 编码模式在 2.2 中不再适用。

如果应用在 Startup 类中执行日志记录提供程序初始化、筛选和配置加载，请将该代码移动到 Program.Main：

  • 提供程序初始化：

1.x 示例：

  1. public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
  2. {
  3.     loggerFactory.AddConsole();
  4. }

2.2 示例：

  2. public static void Main(string[] args)
  3. {
  4.     var webHost = new WebHostBuilder()
  5.         // ...
  6.         .ConfigureLogging((hostingContext, logging) =>
  7.         {
  8.             logging.AddConsole();
  9.         })
  10.         // ...
  11. }
  • 筛选：

1.x 示例：

  1. public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
  2. {
  3.     loggerFactory.AddConsole(LogLevel.Information);
  4.     // or
  5.     loggerFactory.AddConsole((category, level) => 
  6.         category == "A" || level == LogLevel.Critical);
  7. }

2.2 示例：

  1. public static void Main(string[] args)
  2. {
  3.     var webHost = new WebHostBuilder()
  4.         // ...
  5.         .ConfigureLogging((hostingContext, logging) =>
  6.         {
  7.             logging.AddConsole()
  8.                    .AddFilter<ConsoleLoggerProvider>
  9.                        (category: null, level: LogLevel.Information)
  10.                    // or
  11.                    .AddFilter<ConsoleLoggerProvider>
  12.                        ((category, level) => category == "A" ||
  13.                            level == LogLevel.Critical)
  14.             );
  15.         })
  16.         // ...
  17. }
  • 配置加载：

1.x 示例：

  1. public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
  2. {
  3.     loggerFactory.AddConsole(Configuration);
  4. }

2.2 示例：

  1. public static void Main(string[] args)
  2. {
  3.     var webHost = new WebHostBuilder()
  4.         // ...
  5.         .ConfigureLogging((hostingContext, logging) =>
  6.         {
  7.             logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
  8.             logging.AddConsole();
  9.         })
  10.         // ...
  11. }

有关详细信息，请参阅.NET Core 和 ASP.NET Core 中的日志记录。

其他资源Additional resources