从 ASP.NET Core 6.0 迁移到 7.0

项目
11/30/2023

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

先决条件

带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。

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

如果依靠 global.json 文件来定向于特定 .NET Core SDK 版本，请将 version 属性更新为已安装的 .NET 7.0 SDK 版本。例如：

{
  "sdk": {
-    "version": "6.0.200"
+    "version": "7.0.100"
  }
}

更新目标框架

将项目文件的目标框架名字对象 (TFM) 更新为 net7.0：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFramework>net7.0</TargetFramework>
  </PropertyGroup>

</Project>

更新包引用

在项目文件中，将每个 Microsoft.AspNetCore.*、Microsoft.EntityFrameworkCore.*、Microsoft.Extensions.* 和 System.Net.Http.Json 包引用的 Version 属性更新到 7.0.0 或更高版本。例如：

<ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="6.0.9" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="6.0.9" />
-    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="6.0.9" />
-    <PackageReference Include="System.Net.Http.Json" Version="6.0.0" />
+    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="7.0.0" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="7.0.0" />
+    <PackageReference Include="System.Net.Http.Json" Version="7.0.0" />
</ItemGroup>

Blazor

采用 .NET 7 功能

按照本文前面所述的指导将应用更新到 7.0 后，请按照 ASP.NET Core 7.0 的新增功能中的链接采用特定功能。

要为 Blazor 应用采用所有新的 7.0 功能，我们建议使用以下过程：

通过其中一个 Blazor 项目模板创建新的 7.0 Blazor 项目。有关详细信息，请参阅用于 ASP.NET Core Blazor 的工具。
将应用的组件和代码移动到 7.0 应用，进行修改以采用新的 7.0 功能。

迁移未封装的 JavaScript 互操作

使用 IJSUnmarshalledRuntime 接口未封装的互操作已过时，应替换为 JavaScript [JSImport]/[JSExport] 互操作。

有关详细信息，请参阅 JavaScript JSImport/JSExport 与 ASP.NET Core Blazor 互操作。

Blazor WebAssembly 身份验证使用历史记录状态进行重定向

对 Blazor WebAssembly 应用中身份验证的支持已更改为依赖于导航历史记录状态，而不是 URL 中的查询字符串。因此，在 .NET 7 中成功登录后，通过查询字符串传递返回 URL 将无法重定向回原始页面。

以下示例演示了面向 .NET 6 或更早版本的应用的先前重定向方法，该方法基于具有 NavigateTo 的重定向 URL (?returnUrl=)：

@inject NavigationManager Navigation
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication
@code {
    protected override void OnInitialized()
    {
        Navigation.NavigateTo(
            $"authentication/login?returnUrl={Uri.EscapeDataString(Navigation.Uri)}");
    }
}

以下示例演示了面向 .NET 7 或更高版本的应用的新重定向方法，该方法基于具有 NavigateToLogin 的导航历史记录状态：

@inject NavigationManager Navigation
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication
@using Microsoft.Extensions.Options

@inject IOptionsSnapshot<RemoteAuthenticationOptions<ApiAuthorizationProviderOptions>> OptionsSnapshot
@code {
    protected override void OnInitialized()
    {
        Navigation.NavigateToLogin(OptionsSnapshot.Get(Options.DefaultName).AuthenticationPaths.LogInPath);
    }
}

作为此更改的一部分，SignOutSessionStateManager 在 .NET 7 或更高版本中已过时，并替换为 NavigateToLogout。

以下示例演示从 Blazor WebAssembly 项目模板生成的应用中 Shared/LoginDisplay.razor 的先前方法：

@inject SignOutSessionStateManager SignOutManager

...

@code{
    private async Task BeginLogout(MouseEventArgs args)
    {
        await SignOutManager.SetSignOutState();
        Navigation.NavigateTo("authentication/logout");
    }
}

以下示例演示调用 NavigateToLogout 的新方法。 SignOutSessionStateManager的注入 (@inject) 从文件顶部的组件指令中删除，并将 BeginLogOut 方法更新为以下代码：

@code{
    public void BeginLogOut()
    {
        Navigation.NavigateToLogout("authentication/logout");
    }
}

SignOutSessionStateManager 服务注册已在 Program.cs 中删除：

- builder.Services.AddScoped<SignOutSessionStateManager>();

有关详细信息，请参阅以下资源：

适用于 .NET 6 项目的 .NET WebAssembly 生成工具

现在，在使用 .NET 7 SDK 时，可以将 .NET WebAssembly 生成工具与 .NET 6 项目配合使用。新 wasm-tools-net6 工作负载包括适用于 .NET 6 项目的 .NET WebAssembly 生成工具，以便可以与 .NET 7 SDK 一起使用。现有的 wasm-tools 工作负载安装适用于 .NET 7 项目的 .NET WebAssembly 生成工具。但是，.NET 7 版本的 .NET WebAssembly 生成工具与使用 .NET 6 生成的现有项目不兼容。使用必须同时支持 .NET 6 和 .NET 7 的 .NET WebAssembly 生成工具的项目必须使用多目标。

更新 Docker 映像

对于使用 Docker 的应用，请更新 Dockerfile FROM 语句和脚本。使用包含 ASP.NET Core 7.0 运行时的基础映像。请考虑 ASP.NET Core 6.0 和 7.0 之间的以下 docker pull 命令差异：

- docker pull mcr.microsoft.com/dotnet/aspnet:6.0
+ docker pull mcr.microsoft.com/dotnet/aspnet:7.0

查看中断性变更

有关从 .NET Core 6.0 到 .NET 7.0 的中断性变更，请参阅 .NET 7 中的中断性变更。列表中包括 ASP.NET Core 和 Entity Framework Core。

通过