升级到新的 .NET 版本

.NET 每年都会发布新的版本。 许多开发人员在新版本推出后立即启动升级过程，而其他开发人员则等到他们正在使用的版本不再受支持时才升级。 升级过程需要考虑多个方面。

升级到新的 .NET 版本的常见原因：

• 当前使用的 .NET 版本不再受支持
• 新版本支持新的操作系统
• 新版本具有重要的 API、性能或安全功能

升级开发环境

若要升级到新的 .NET 版本，.NET SDK 是要安装的主要组件。 它包括更新的 .NET CLI、生成系统和运行时版本。

.NET 网站提供安装程序和存档，可在任何受支持的操作系统和体系结构上下载和使用。

某些操作系统有一个包管理器，可用于安装你可能更喜欢的新 .NET 版本。

• macOS
• Linux
• Windows操作系统

Visual Studio 会自动安装新的 .NET SDK 版本。 对于 Visual Studio 用户，升级到较新的 Visual Studio 版本就足够了。

升级源代码

升级应用的唯一必需更改是将项目文件中的 TargetFramework 属性更新为较新的 .NET 版本。

操作方法如下：

• 打开项目文件（*.csproj、*.vbproj 或 *.fsproj 文件）。
• 例如，将 <TargetFramework> 属性值从 net6.0 更改为 net8.0。
• 如果使用 <TargetFrameworks> 属性，则相同的模式适用于该属性。

下一步是使用新的 SDK 生成项目（或解决方案）。 如果需要进行其他更改，SDK 将提供警告和错误进行指导。

可能需要运行 dotnet workload restore 才能使用新的 SDK 版本还原工作负载。

更多资源：

• .NET 9 中的中断性变更
• 迁移 ASP.NET Core 应用
• 将 .NET MAUI 从 .NET 7 升级到 .NET 8

版本锁定

升级 .NET SDK、Visual Studio 或其他组件等开发工具时，可能会遇到影响生成过程的新行为、分析器警告或中断性变更。 通过固定到某个版本，你可以升级开发环境，同时保持对项目中特定组件更新的时间的控制。

版本固定带来以下几个优势：

• 可预测生成：确保在不同计算机和 CI/CD 环境中生成结果一致。
• 逐步采用：允许以增量方式而不是一次性采用新功能。
• 避免意外更改：防止新的分析器规则、SDK 行为或包版本导致生成失败。
• 团队协调：使团队能够在计划的时间而不是在工具更新时单独升级。
• 调试和故障排除：在控制哪些版本发生更改时，可以更轻松地隔离问题。

以下部分介绍用于控制 .NET 项目中不同组件版本的各种机制：

• 使用 global.json控制 SDK 版本
• 控制分析器行为
• 控制 NuGet 包版本
• 控制 MSBuild 版本

使用 global.json 控制 SDK 版本

可以使用 global.json 文件固定项目或解决方案的 .NET SDK 版本。 此文件指定运行 .NET CLI 命令时要使用的 SDK 版本，并且独立于项目目标的运行时版本。

在解决方案根目录中创建 global.json 文件：

dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature

此命令创建以下 global.json 文件，该文件将 SDK 固定到版本 9.0.100 或更高版本的修补程序或功能带（在 9.0 主版本中）：

{
  "sdk": {
    "version": "9.0.100",
    "rollForward": "latestFeature"
  }
}

策略 rollForward 控制在确切版本不可用时如何选择 SDK 版本。 此配置可确保在升级 Visual Studio 或安装新 SDK 时，项目将继续使用 SDK 9.0.x，直到显式更新 global.json 文件。

有关详细信息，请参阅 global.json 概述。

控制分析器行为

代码分析器可以在版本之间引入新的警告或更改行为。 可以使用AnalysisLevel 属性控制分析器版本，以保持构建的一致性。 此属性允许锁定特定版本的分析器规则，从而防止升级 SDK 时引入新规则。

<PropertyGroup>
  <AnalysisLevel>9.0</AnalysisLevel>
</PropertyGroup>

当设置为 9.0 时，即使使用 .NET 10 SDK，也仅启用随 .NET 9 附带的分析器规则。 这可以防止 .NET 10 新的分析器规则影响构建，直到你准备好去处理它们。

有关详细信息，请参阅 AnalysisLevel。

控制 NuGet 包版本

通过跨项目一致地管理包版本，可以防止意外更新和维护可靠的生成。

• 包锁定文件
• 中央包管理
• 包源映射

包锁定文件

包锁定文件可确保包还原作在不同的环境中使用完全相同的包版本。 锁定文件 （packages.lock.json） 记录所有包及其依赖项的确切版本。

在项目文件中启用锁定文件：

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

确保在锁定文件未更新时，构建失败：

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode>true</RestoreLockedMode>
</PropertyGroup>

启用锁定文件后，运行 dotnet restore 以生成 packages.lock.json 文件。 将此文件提交到版本控制。

中央包管理

中央包管理（CPM）允许你在解决方案中的所有项目的单一位置管理包版本。 此方法简化了版本管理并确保项目之间的一致性。

在解决方案根目录中创建 Directory.Packages.props 文件：

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
  </ItemGroup>
</Project>

在项目文件中，引用包而不指定版本：

<ItemGroup>
  <PackageReference Include="Azure.Identity" />
  <PackageReference Include="Microsoft.Extensions.AI" />
</ItemGroup>

包源映射

通过包源映射，可以控制哪些 NuGet 源用于特定包，从而提高安全性和可靠性。

在 nuget.config 文件中配置源映射：

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://contoso.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

此配置可确保以 Contoso. 开头的所有包仅从 contoso 源中还原，而其他包来自 nuget.org。

有关详细信息，请参阅 NuGet 包还原。

控制 MSBuild 版本

Visual Studio 支持并行安装多个版本。 例如，可以在同一台计算机上安装 Visual Studio 2026 和 Visual Studio 2022。 每个 Visual Studio 版本都包含相应的 .NET SDK。 更新 Visual Studio 时，包含的 SDK 版本也会更新。 但是，你可以继续使用较旧的 SDK 版本，方法是将它们与 .NET 下载页分开安装。

MSBuild 版本对应于 Visual Studio 版本。 例如，Visual Studio 2022 版本 17.8 包括 MSBuild 17.8。 .NET SDK 还包括 MSBuild。 使用 dotnet build 时，您将使用由 global.json 指定的 SDK 或最新安装的 SDK 随附的 MSBuild 版本。

若要使用特定的 MSBuild 版本，

• 在 dotnet buildglobal.json中与固定的 SDK 版本一起使用。
• 启动相应的 Visual Studio 开发人员命令提示符，该提示为该 Visual Studio 版本的 MSBuild 设置环境。
• 直接从特定 Visual Studio 安装（例如， "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe"）调用 MSBuild。

有关详细信息，请参阅 .NET SDK、MSBuild 和 Visual Studio 版本控制。

更新持续集成 (CI)

CI 管道遵循与项目文件和 Dockerfile 类似的更新过程。 通常，只需更改版本值即可更新 CI 管道。

更新托管环境

有许多模式可用于托管应用程序。 如果托管环境包含 .NET 运行时，则需要安装新版本的 .NET 运行时。 在 Linux 上，需要安装依赖项，但它们通常不会随 .NET 版本的更改而更改。

对于容器，需要更改 FROM 语句，以包含新的版本号。

以下 Dockerfile 示例演示如何拉取 ASP.NET Core 9.0 映像。

FROM mcr.microsoft.com/dotnet/aspnet:9.0

在 Azure 应用服务等云服务中，需要更改配置。

另请参阅

• .NET 10 中的中断性变更
• 迁移 ASP.NET Core 应用