从 ASP.NET 到 ASP.NET Core 的增量更新

对于大多数生产应用来说，将应用从 ASP.NET Framework 更新为 ASP.NET Core 并非易事。 这些应用通常会在新技术可用时将其纳入，并且通常由许多旧的决策组成。 本文提供了有关工具的指导和链接，这些工具用于将 ASP.NET Framework 应用更新到 ASP.NET Core，并尽可能减少更改。

更大的挑战之一是在整个代码库中普遍使用 HttpContext。 如果没有增量方法和工具，则需要进行大规模重写才能移除 HttpContext 依赖项。 dotnet/systemweb-adapters 中的适配器提供了一组运行时帮助程序，只需进行最少量的更改，即可通过适用于 ASP.NET Core 的方法访问 ASP.NET Framework 应用中使用的类型。

完整迁移可能需要执行大量工作，具体取决于应用的大小、依赖项和所使用的非可移植 API。 为了在进行更新时继续将应用部署到生产，最佳模式是遵循 Strangler Fig 模式。 使用 Strangler Fig 模式，可以在旧系统上使用增量方法将特定功能部分替换为新服务，从而在旧系统上进行持续开发。 本文档介绍了如何将 Strangler Fig 模式应用于向 ASP.NET Core 更新的 ASP.NET 应用。

如果想要跳过此概述文章并开始更新，请参阅开始。

将应用迁移到 ASP.NET Core

在开始迁移之前，应用以 ASP.NET Framework 为目标，并通过其支持库在 Windows 上运行：

迁移首先引入基于 ASP.NET Core 的新应用，该应用将成为入口点。 传入请求将转到 ASP.NET Core 应用，应用会处理请求或通过 YARP 将请求代理到 .NET Framework 应用。 最初，大多数提供响应的代码位于 .NET Framework 应用中，但现在 ASP.NET Core 应用已设置为开始迁移路由：

要迁移依赖于 HttpContext 的业务逻辑，需要使用 Microsoft.AspNetCore.SystemWebAdapters 生成库。 使用 SystemWebAdapters 生成库允许：

• 针对 .NET Framework、.NET Core 或 .NET Standard 2.0 生成库。
• 确保库使用的是在 ASP.NET Framework 和 ASP.NET Core 上均可用的 API。

设置了使用 YARP 的 ASP.NET Core 应用后，可以开始将路由从 ASP.NET Framework 更新到 ASP.NET Core。 例如，WebAPI 或 MVC 控制器操作方法、处理程序或路由的一些其他实现。 如果路由在 ASP.NET Core 应用中可用，则会匹配并提供该路由。

在迁移过程中，会标识其他必须更新后才能在 .NET Core 上运行的服务和基础结构。 按可维护性顺序列出的选项包括：

1. 将代码移动到共享库
2. 链接新项目中的代码
3. 复制代码

最终，ASP.NET Core 应用会处理比 .NET Framework 应用更多的路由：

不再需要并删除 ASP.NET Framework 应用后：

• 应用会在 ASP.NET Core 应用堆栈上运行，但仍使用该适配器。
• 剩余的迁移工作是移除适配器的使用。

Visual Studio 扩展 .NET 升级助手可帮助 ASP.NET Framework Web 应用升级到 ASP.NET Core。 有关详细信息，请参阅博客文章使用 Visual Studio 升级 .NET 项目。

System.Web 适配器

命名空间 Microsoft.AspNetCore.SystemWebAdapters 是运行时帮助程序集合，用于在移动到 ASP.NET Core 时帮助使用针对 System.Web 编写的代码。 可以通过几个包来使用这些适配器的功能：

• Microsoft.AspNetCore.SystemWebAdapters：此包用于支持库，并提供你可能已依赖的 System.Web API，例如 HttpContext 和其他 API。 此包面向 .NET Standard 2.0、.NET 4.5+ 和 .NET 6+。
• Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices：此包仅面向 .NET Framework，并旨在向可能需要提供增量迁移的 ASP.NET Framework 应用程序提供服务。 这通常不应从库引用，而是从应用程序本身引用。
• Microsoft.AspNetCore.SystemWebAdapters.CoreServices：此包仅面向 .NET 6+，并旨在向 ASP.NET Core 应用程序提供服务，以配置 System.Web API 的行为以及选择使用任何行为来进行增量迁移。 这通常不应从库引用，而是从应用程序本身引用。
• Microsoft.AspNetCore.SystemWebAdapters.Abstractions：此包是一个支持包，它为 ASP.NET Core 和 ASP.NET Framework 应用程序使用的服务提供抽象，例如会话状态序列化。

有关适用此方法的方案示例，请参阅适配器一文。

有关用法的指导，请参阅用法指导一文。

其他资源

• 将 eShop 迁移到 ASP.NET Core 的示例
• 视频：适用于增量 ASP.NET Core 迁移的工具
• 单元测试