通过

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

  • 项目

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

更大的挑战之一是在整个代码库中广泛使用 HttpContext。 如果没有增量方法和工具，需要大规模重写才能删除 HttpContext 依赖项。 dotnet/systemweb-adapters 中的适配器 提供了一组运行时帮助程序，以便访问 ASP.NET Framework 应用中使用的类型，从而能够在 ASP.NET Core 中以最小的修改进行工作。

完全迁移可能需要大量精力，具体取决于使用的应用、依赖项和非可移植 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。

Microsoft.AspNetCore.SystemWebAdapters

设置使用 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 Core 应用处理更多路由

不再需要 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 等。 此包面向 .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 应用程序（例如会话状态序列化）使用的服务提供抽象。

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

有关使用情况的指导，请参阅 使用指南文章。

其他资源