从 ASP.NET Framework 升级到 ASP.NET Core

项目
11/06/2024

为何升级到最新 .NET

ASP.NET Core是适用于 .NET 的新式 Web 框架。尽管 ASP.NET Core 与 .NET Framework 中的 ASP.NET 有许多相似之处，但它是一个完全经过重写的新框架。更新到 ASP.NET Core 的 ASP.NET 应用可以获得改进的性能，并有权访问最新的 Web 开发特性和功能。

ASP.NET Framework 的更新方法

大多数重要的 ASP.NET Framework 应用应考虑使用增量升级方法。有关详细信息，请参阅从 ASP.NET 到 ASP.NET Core 的增量升级。

对于 ASP.NET MVC 和 Web API 应用，请参阅了解如何从 ASP.NET MVC 和 Web API 升级为 ASP.NET Core MVC。对于 ASP.NET Framework Web Forms 应用，请参阅了解如何从 ASP.NET Web Forms 升级为 ASP.NET Core。

可靠的 Web 应用模式

请观看《适用于 .NET 的可靠 Web 应用模式》YouTube 视频和文章，了解如何创建新式、可靠、高性能、可测试、经济高效且可缩放的 ASP.NET Core 应用，无论是从头开始创建还是重构现有应用。

ASP.NET 与 ASP.NET Core 的 URI 解码差异

ASP.NET Core 与 ASP.NET Framework 之间存在以下 URI 解码差异：

ASCII	Encoded	ASP.NET Core	ASP.NET 框架
`\`	`%5C`	`\`	`/`
`/`	`%2F`	`%2F`	`/`

在 ASP.NET Core 上解码 %2F 时：

除了 %2F 之外，整个路径都不可转义，因为将其转换为 / 会改变路径的结构。在将路径拆分为段之前，无法对其进行解码。

若要生成 HttpRequest.Url 的值，请使用 new Uri(this.AspNetCoreHttpRequest.GetEncodedUrl()); 以避免 Uri 错误解释值。

将用户机密从 ASP.NET Framework 迁移到 ASP.NET Core

请参阅此 GitHub 问题。

本文可作为从 ASP.NET 应用迁移到 ASP.NET Core 的参考指南。

Visual Studio 提供工具来帮助将 ASP.NET 应用迁移到 ASP.NET Core。有关详细信息，请参阅从 ASP.NET 迁移到 Visual Studio 中的 ASP.NET Core。

.NET 升级助手是一个命令行工具，可以帮助将 ASP.NET 迁移到 ASP.NET Core。有关详细信息，请参阅 .NET 升级助手概述和使用 .NET 升级助手将 ASP.NET MVC 应用升级到 .NET 6。

有关完整的移植指南，请参阅电子书将现有的 ASP.NET 应用移植到 .Net Core，。

先决条件

.NET Core SDK 2.2 或更高版本

目标框架

ASP.NET Core 项目为开发人员提供了面向 .NET Core 和/或 .NET Framework 的灵活性。若要确定最合适的目标框架，请参阅为服务器应用选择 .NET Core 或 .NET Framework。

面向 .NET Framework 时，项目需要引用单个 NuGet 包。

得益于有 ASP.NET Core 元包，面向 .NET Core 时可以避免进行大量的显式包引用。在项目中安装 Microsoft.AspNetCore.App 元包：

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

使用此元包时，应用不会部署元包中引用的任何包。 .NET Core 运行时存储中包含这些资产，并已预编译，旨在提升性能。如需了解更多详情，请参阅用于 ASP.NET Core 的 Microsoft.AspNetCore.App 元包。

项目结构差异

ASP.NET Core 中简化了 .csproj 文件格式。下面是一些显著的更改：

无需显式添加，即可将文件视作项目的一部分。服务于大型团队时，这可减少出现 XML 合并冲突的风险。
没有对其他项目的基于 GUID 的引用，这可以提高文件的可读性。
无需在 Visual Studio 中卸载文件即可对它进行编辑：

？

Global.asax 文件替换

ASP.NET Core 引入了启动应用的新机制。 ASP.NET 应用程序的入口点是 Global.asax 文件。路由配置及筛选器和区域注册等任务在 Global.asax 文件中进行处理。

public class MvcApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        AreaRegistration.RegisterAllAreas();
        FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
        RouteConfig.RegisterRoutes(RouteTable.Routes);
        BundleConfig.RegisterBundles(BundleTable.Bundles);
    }
}

此方法会将应用程序和应用程序要部署到的服务器耦合在一起，并且它们的耦合方式会干扰实现。为了将它们分离，引入了 OWIN 来提供一种更为简便的同时使用多个框架的方法。 OWIN 提供了一个管道，可以只添加所需的模块。托管环境使用 Startup 函数配置服务和应用的请求管道。 Startup 在应用程序中注册一组中间件。对于每个请求，应用程序都使用现有处理程序集的链接列表的头指针调用各个中间件组件。每个中间件组件可以向请求处理管道添加一个或多个处理程序。为此，需要返回对成为列表新头的处理程序的引用。每个处理程序负责记住并调用列表中的下一个处理程序。使用 ASP.NET Core 时，应用程序的入口点是 Startup，不再具有 Global.asax 的依赖关系。结合使用 OWIN 和 .NET Framework 时，使用的管道应如下所示：

using Owin;
using System.Web.Http;

namespace WebApi
{
    // Note: By default all requests go through this OWIN pipeline. Alternatively you can turn this off by adding an appSetting owin:AutomaticAppStartup with value “false”. 
    // With this turned off you can still have OWIN apps listening on specific routes by adding routes in global.asax file using MapOwinPath or MapOwinRoute extensions on RouteTable.Routes
    public class Startup
    {
        // Invoked once at startup to configure your application.
        public void Configuration(IAppBuilder builder)
        {
            HttpConfiguration config = new HttpConfiguration();
            config.Routes.MapHttpRoute("Default", "{controller}/{customerID}", new { controller = "Customer", customerID = RouteParameter.Optional });

            config.Formatters.XmlFormatter.UseXmlSerializer = true;
            config.Formatters.Remove(config.Formatters.JsonFormatter);
            // config.Formatters.JsonFormatter.UseDataContractJsonSerializer = true;

            builder.UseWebApi(config);
        }
    }
}

这会配置默认路由，默认为 XmlSerialization 而不是 Json。根据需要向此管道添加其他中间件（加载服务、配置设置、静态文件等）。

ASP.NET Core 使用相似的方法，但是不依赖 OWIN 处理条目。而是通过 Program.cs Main 方法（类似于控制台应用程序）来完成，并且 Startup 会通过该方法加载。

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace WebApplication2
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>();
    }
}

Startup 必须包含 Configure 方法。在 Configure 中，向管道添加必要的中间件。在下面的示例（来自默认网站模板）中，扩展方法为管道配置以下支持：

错误页
HTTP 严格传输安全
从 HTTP 重定向到 HTTPS
ASP.NET Core MVC

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseMvc();
}

现在主机和应用程序已分离，这样将来就可以灵活地迁移到其他平台。

注意

若要获取 ASP.NET Core Startup 和中间件的更深入的参考信息，请参阅 ASP.NET Core 中的 Startup

存储配置

ASP.NET 支持存储设置。这些设置可用于支持应用程序已部署到的环境（以此用途为例）。常见做法是将所有的自定义键值对存储在 Web.config 文件的 <appSettings> 部分中：

<appSettings>
  <add key="UserName" value="User" />
  <add key="Password" value="Password" />
</appSettings>

应用程序使用 System.Configuration 命名空间中的 ConfigurationManager.AppSettings 集合读取这些设置：

string userName = System.Web.Configuration.ConfigurationManager.AppSettings["UserName"];
string password = System.Web.Configuration.ConfigurationManager.AppSettings["Password"];

ASP.NET Core 可以将应用程序的配置数据存储在任何文件中，并可在启动中间件的过程中加载它们。项目模板中使用的默认文件是 appsettings.json：

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "AppConfiguration": {
    "UserName": "UserName",
    "Password": "Password"
  }
}

将此文件加载到应用程序内的 IConfiguration 的实例的过程在 Startup.cs 中完成：

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

应用读取 Configuration 来获得这些设置：

string userName = Configuration.GetSection("AppConfiguration")["UserName"];
string password = Configuration.GetSection("AppConfiguration")["Password"];

此方法有扩展项，它们可使此过程更加可靠，例如使用依存关系注入 (DI) 来加载使用这些值的服务。 DI 方法提供了一组强类型的配置对象。

// Assume AppConfiguration is a class representing a strongly-typed version of AppConfiguration section
services.Configure<AppConfiguration>(Configuration.GetSection("AppConfiguration"));

注意

若要获取 ASP.NET Core 配置的更深入的参考信息，请参阅 ASP.NET Core 中的配置。

本机依存关系注入

生成大型可缩放应用程序时，一个重要的目标是将组件和服务松散耦合。依赖项注入不仅是可实现此目标的常用技术，还是 ASP.NET Core 的本机组件。

在 ASP.NET 应用中，开发人员依赖第三方库实现依存关系注入。其中的一个库是 Microsoft 模式和做法提供的 Unity。

实现打包 UnityContainer 的 IDependencyResolver 是使用 Unity 设置依存关系注入的一个示例：

using Microsoft.Practices.Unity;
using System;
using System.Collections.Generic;
using System.Web.Http.Dependencies;

public class UnityResolver : IDependencyResolver
{
    protected IUnityContainer container;

    public UnityResolver(IUnityContainer container)
    {
        if (container == null)
        {
            throw new ArgumentNullException("container");
        }
        this.container = container;
    }

    public object GetService(Type serviceType)
    {
        try
        {
            return container.Resolve(serviceType);
        }
        catch (ResolutionFailedException)
        {
            return null;
        }
    }

    public IEnumerable<object> GetServices(Type serviceType)
    {
        try
        {
            return container.ResolveAll(serviceType);
        }
        catch (ResolutionFailedException)
        {
            return new List<object>();
        }
    }

    public IDependencyScope BeginScope()
    {
        var child = container.CreateChildContainer();
        return new UnityResolver(child);
    }

    public void Dispose()
    {
        Dispose(true);
    }

    protected virtual void Dispose(bool disposing)
    {
        container.Dispose();
    }
}

创建 UnityContainer 的实例，注册服务，然后将 HttpConfiguration 的依赖关系解析程序设置为容器的 UnityResolver 新实例：

public static void Register(HttpConfiguration config)
{
    var container = new UnityContainer();
    container.RegisterType<IProductRepository, ProductRepository>(new HierarchicalLifetimeManager());
    config.DependencyResolver = new UnityResolver(container);

    // Other Web API configuration not shown.
}

在必要时注入 IProductRepository：

public class ProductsController : ApiController
{
    private IProductRepository _repository;

    public ProductsController(IProductRepository repository)  
    {
        _repository = repository;
    }

    // Other controller methods not shown.
}

由于依赖关系注入是 ASP.NET Core 的组成部分，因此可以在 Startup.cs 的 ConfigureServices 方法中添加你的服务：

public void ConfigureServices(IServiceCollection services)
{
    // Add application services.
    services.AddTransient<IProductRepository, ProductRepository>();
}

可在任意位置注入存储库，Unity 亦是如此。

注意

有关依赖关系注入的详细信息，请参阅依赖关系注入。

提供静态文件

Web 开发的一个重要环节是提供客户端静态资产的功能。 HTML、CSS、Javascript 和图像是最常见的静态文件示例。这些文件需要保存在应用（或 CDN）的发布位置中，并且需要引用它们，以便请求可以加载这些文件。在 ASP.NET Core 中，此过程发生了变化。

在 ASP.NET 中，静态文件存储在各种目录中，并在视图中进行引用。

在 ASP.NET Core 中，静态文件存储在“Web 根”（<内容根>/wwwroot）中，除非另有配置。通过从 Startup.Configure 调用 UseStaticFiles 扩展方法将这些文件加载到请求管道中：

注意

如果面向 .NET Framework，请安装 NuGet 包 Microsoft.AspNetCore.StaticFiles。

例如，可以通过浏览器从类似 http://<app>/images/<imageFileName> 的位置访问 wwwroot/images 文件夹中的图像资产。

注意

若要获取在 ASP.NET Core 中提供静态文件的更深入的参考信息，请参阅静态文件。

多值 cookie

ASP.NET Core 不支持多值 cookie。为每个值创建一个 cookie。

ASP.NET Core 中不压缩身份验证 Cookie

出于安全原因，ASP.NET Core 中不压缩身份验证 Cookie。使用身份验证 Cookie 时，开发人员应将包含的声明信息数量减少到正好满足其需求所需的数量。

部分应用迁移

部分应用迁移的一种方法是创建 IIS 子应用程序，只将特定的路由从 ASP.NET 4.x 迁移到 ASP.NET Core，同时保留应用的 URL 结构。例如，applicationHost.config 文件中应用的 URL 结构：

<sites>
    <site name="Default Web Site" id="1" serverAutoStart="true">
        <application path="/">
            <virtualDirectory path="/" physicalPath="D:\sites\MainSite\" />
        </application>
        <application path="/api" applicationPool="DefaultAppPool">
            <virtualDirectory path="/" physicalPath="D:\sites\netcoreapi" />
        </application>
        <bindings>
            <binding protocol="http" bindingInformation="*:80:" />
            <binding protocol="https" bindingInformation="*:443:" sslFlags="0" />
        </bindings>
    </site>
	...
</sites>

目录结构：

.
├── MainSite
│   ├── ...
│   └── Web.config
└── NetCoreApi
    ├── ...
    └── web.config

[BIND] 和输入格式化程序

ASP.NET 早期版本使用 [Bind] 属性防止“过多发布”攻击。在 ASP.NET Core 中，输入格式化程序的工作方式有所不同。与输入格式化程序一起用于分析 JSON 或 XML 时，[Bind] 属性不再专用于防止过多发布。数据源是使用 x-www-form-urlencoded 内容类型发布的表单数据时，这些属性会影响模型绑定。

对于将 JSON 信息发布到控制器并使用 JSON 输入格式化程序分析数据的应用程序，我们建议将 [Bind] 属性替换为与 [Bind] 属性定义的属性相匹配的视图模型。

其他资源

将库移植到 .NET Core