从 ASP.NET Core 6.0 迁移到 7.0

  • 项目

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

先决条件

在 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。