通过

开始使用 ASP.NET 到 ASP.NET Core 的增量迁移

Important

开始之前：本文假设你已阅读 ASP.NET 核心迁移概述。 如果尚未阅读，请先了解增量迁移的概念、方法和优势。

对于大型迁移，我们建议设置代理到原始 .NET Framework 应用的 ASP.NET Core 应用。 下图显示了启用代理的新应用：

开始迁移路由

本文提供了在了解此方法后继续执行增量迁移的实际步骤。

Prerequisites

在开始增量迁移之前，请确保：

  1. 阅读概述： 增量迁移 ASP.NET 到 ASP.NET Core
  2. 要迁移的工作 ASP.NET Framework 应用程序
  3. 具有最新更新的 Visual Studio 2022
  4. 已安装 .NET 8 或更高版本的 SDK
  5. 了解应用程序的依赖项 和第三方库

迁移步骤概述

增量迁移过程遵循以下关键步骤：

  1. 设置 ASP.NET 核心项目
  2. 整治技术债务
  3. 确定和解决跨领域问题
  4. 升级支持库

设置 ASP.NET 核心项目

第一步是创建充当代理的新 ASP.NET Core 应用程序。

你将要做的事情：

  • 与现有 ASP.NET Framework 应用一起创建新的 ASP.NET Core 项目
  • 将其配置为使用 YARP（又一个反向代理）代理对原始应用程序的请求
  • 设置用于增量迁移的基本基础结构

Detailed instructions:

缓解技术债务

何时执行此步骤： 在升级任何支持库之前，请解决可能使迁移过程复杂化的技术债务。

在开始升级支持库之前，请务必清理可能会干扰迁移过程的技术债务。 首先应完成此步骤，以确保更流畅的升级体验。

更新软件包依赖项

查看 NuGet 包并将其更新到其最新兼容版本：

  1. 审核现有包：使用 Visual Studio 的 NuGet 包管理器，因为 dotnet CLI 不适用于 ASP.NET Framework 应用程序
  2. 以增量方式更新包：一次更新一个包以避免兼容性问题
  3. 每次更新后进行测试：确保应用程序在每个包更新后仍然正常运行
  4. 解决重大更改：某些包更新可能会引入需要解决的重大更改

实现生成工具现代化

更新生成工具和项目配置：

  1. 更新工具：确保使用的是最新版本的 MSBuild/Visual Studio
  2. 迁移到 PackageReference 以获取依赖项：如果你还没有使用 Web 应用程序项目，请考虑从 packages.config 格式迁移到 PackageReference 格式
  3. 清理未使用的引用：删除任何未使用的程序集引用或 NuGet 包
  4. 迁移到 SDK 样式的项目文件：将现有项目文件转换为新式 SDK 样式格式。 这对于与新式 .NET 项目兼容至关重要，并提供更好的工具支持
  5. 更新生成脚本：查看和更新任何自定义生成脚本或 CI/CD 配置

解决代码质量问题

修复可能导致迁移复杂化的已知代码质量问题：

  1. 修复编译器警告：解决任何编译器警告，尤其是与弃用的 API 相关的警告
  2. 删除死代码：清理未使用的类、方法和其他代码元素
  3. 更新已弃用的 API 用法：尽可能将弃用的 API 的使用替换为其新式等效项

此准备工作将使库升级过程更加顺利，并减少在迁移过程中遇到复杂问题的可能性。

确定和解决跨领域问题

何时执行此步骤： 在修正技术债务的同时，但在升级支持库之前，请确定并配置影响整个应用程序的交叉问题。

跨领域问题是跨多个层或组件的应用程序的各个方面，例如身份验证、会话管理、日志记录和缓存。 迁移过程中需要尽早解决这些问题，因为它们会影响 ASP.NET Framework 和 ASP.NET Core 应用程序在增量迁移期间通信和共享状态的方式。

以下部分介绍最常见的交叉问题。 仅配置适用于应用程序的配置：

会话支持配置

配置这个如果：你的 ASP.NET Framework 应用程序使用会话状态。

请参阅常规 会话迁移文档 以获取指导。

会话是 ASP.NET 的常用功能，它与 ASP.NET Core 中的功能共享名称，但 API 大相径庭。 升级使用会话状态的库时，需要配置会话支持。 有关如何在应用程序之间启用会话状态共享的详细指南，请参阅 有关远程会话支持 的文档。

Authentication Configuration

配置此项如果： 您的 ASP.NET Framework 应用程序使用身份验证，并且您希望在旧应用程序和新应用程序之间共享身份验证状态。

有关此处的指南，请参阅常规 身份验证迁移文档 。

可以使用 System.Web 适配器远程身份验证功能在原始 ASP.NET 应用与新的 ASP.NET Core 应用之间共享身份验证。 此功能允许 ASP.NET Core 应用将身份验证延迟到原始 ASP.NET 应用。 有关详细信息，请参阅有关 远程身份验证 的文档。

要考虑的其他交叉问题

根据应用程序，可能还需要解决以下问题：

  • 日志记录：确保两个应用程序中的一致日志记录。 请考虑使用共享日志记录提供程序或确保正确聚合日志。
  • 缓存：如果应用程序使用缓存（内存中、分布式缓存或输出缓存），请计划如何在应用程序之间保持缓存一致性。
  • 错误处理：跨 ASP.NET Framework 和 ASP.NET Core 应用程序建立一致的错误处理和报告。
  • 配置管理：规划如何在两个应用程序之间共享或管理配置设置。
  • 运行状况监视：在迁移过程中为这两个应用程序设置监视和运行状况检查。
  • 依赖项注入：如果在 ASP.NET Framework 应用中使用 DI 容器，请计划迁移到 ASP.NET Core 的内置 DI 容器。

升级支持库

何时执行此步骤： 仅当需要迁移依赖于包含业务逻辑的类库的特定路由时，需要在旧应用程序和新应用程序之间共享。

Note

增量方法：使用增量迁移过程，无需一次性升级所有支持库。 对于当前正在迁移的特定路由，只需升级所需的库。 这样，就可以在更小、更易于管理的片段中处理迁移。

库升级过程

Important

必须在 后序深度优先搜索顺序中升级支持库。 This means:

  1. 从叶依赖项开始：从解决方案中不依赖于其他库的库开始
  2. 通过依赖项树向上工作：仅在其所有依赖项都成功升级后升级库
  3. 以主应用程序结尾：主 ASP.NET 框架应用程序应该是要修改的最后一项

此排序至关重要，因为：

  • 它可确保升级库时，其所有依赖项都已兼容
  • 它在升级过程中阻止循环依赖项问题
  • 它允许在移动到其依赖项之前独立测试每个库

注意：只需要按照此顺序对您当前正在迁移的路由所需的库子集进行排序，而不需对整个解决方案进行排序。

每个库的升级过程：

如果解决方案中有支持库，并且需要在迁移的路由中使用它们，那么应将这些库升级到 .NET Standard 2.0（如果可能的话）。 升级助手 是一个很好的工具。 如果库无法面向 .NET Standard，则可以将 .NET 8 或更高版本与原始项目中的 .NET Framework 目标一起定位到原始项目或新项目中。

System.Web 适配器可用于这些库，以支持HttpContext在类库中使用。 若要在库中启用 HttpContext 用法，请执行以下作：

  1. 删除项目文件中的System.Web引用
  2. 添加Microsoft.AspNetCore.SystemWebAdapters包
  3. 启用多目标并添加 .NET 8 目标或更高版本，或将项目转换为 .NET Standard 2.0。

此步骤可能需要根据解决方案结构和要迁移的路由更改多个项目。 升级助手能够帮助你识别哪些内容需要更改，并自动化执行流程中的多个步骤。

Next Steps

完成上述安装和库升级步骤后：

  1. 从小开始：首先迁移简单无状态终结点
  2. 全面测试：确保每个已迁移组件在两个环境中都正常工作
  3. 监控性能：关注代理设置可能引发的任何性能影响
  4. 循环访问：继续以增量方式迁移组件，直到迁移完成