通过

将现有项目更新为其他版本的 Windows 应用 SDK

  • 项目

如果使用早期版本的 Windows 应用 SDK（以前称为 Project Reunion）或 WinUI 3 创建了项目，则可更新此项目以使用较新的版本。 若要详细了解每个发布通道中当前提供的内容，请参阅 Windows 应用 SDK 发布通道。

注意

由于每个应用的单独场景的唯一性，这些说明可能会有问题。 请务必遵循它们；如果发现问题，则请针对 microsoft-ui-xaml GitHub 存储库提交 bug。

在 1.0 之后发布的版本之间进行更新

如果项目未引用所需的 Windows 应用 SDK NuGet 包的版本，则可在 Visual Studio 中使用 NuGet 包管理器来更新此项目的 NuGet 包引用。 例如，如果使用 Windows 应用 SDK VSIX 的稳定版本来创建新项目，此项目则会引用 Windows 应用 SDK 的稳定版本。 但是，你可轻松重新配置该项目以引用 Windows 应用 SDK 的试验版本（例如）。 或者，也可重新配置它以引用最新的稳定版本。

有关步骤，请参阅在现有项目中使用 Windows 应用 SDK 中的说明。

从 0.8 更新到 1.0

如果使用 0.8 版（例如，0.8.4 版）创建了项目，则可按以下说明将项目更新到 1.0 版本。

先决条件：下载并安装 Windows 应用 SDK 的最新版本。 有关详细信息，请参阅安装适用于 Windows 应用 SDK 的工具。

说明

  1. 在 .wapproj 文件中，如果 TargetPlatformMinVersion 低于 10.0.17763.0，则请将其更改为 10.0.17763.0。

  2. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。 此过程包括从 .csproj/.vcxproj 和 .wapproj 文件卸载现有 Project Reunion 包引用，然后在这些文件中安装 WindowsAppSDK 包引用。

  3. 输入以下命令，从 .csproj/.vcxproj 中卸载现有包 ProjectReunion

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject} 
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}

  4. 然后，运行以下命令，从 .wapproj 中卸载现有 ProjectReunion 包：

    uninstall-package Microsoft.ProjectReunion 
uninstall-package Microsoft.ProjectReunion.WinUI

  5. 现在，运行命令以安装稳定 WindowsAppSDK 包。

  6. 若要将 WindowsAppSDK 包引用添加到 .csproj/.vcxproj，请执行以下操作：

    install-package Microsoft.WindowsAppSDK -ProjectName {yourProject} -Version 1.0.0

  7. 若要将 WindowsAppSDK 包引用添加到 .wapproj，请执行以下操作：

    install-package Microsoft.WindowsAppSDK -Version 1.0.0

从 0.8 或 0.8 预览版更新到 1.0 试验版或预览版 3

重要

版本 1.0 预览版 1 和预览版 2 存在严重 bug。 如果已安装其中某一预览版，则请参阅影响 1.0 预览版 1 和预览版 2 的重要问题。 建议改用版本 1.0 预览版 3 (1.0.0-preview3)。

如果使用 0.8 预览版或任意 0.8 版（例如，0.8.1 版）创建了项目，则可按以下说明将项目更新为 1.0 预览版 3 或实验版。

在启动之前，请确保已安装所有先决条件里提到的 Windows 应用 SDK，包括最新的 VSIX 和 NuGet 包。 有关更多详细信息，请参阅为 Windows 应用 SDK 安装工具。

首先，执行以下操作：

  • 在 .wapproj 文件中，如果“TargetPlatformMinVersion”比 10.0.17763.0 旧，请将其更改为 10.0.17763.0。

接下来，对项目进行以下更改：

  1. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。

  2. 对 1.0 预览版 3 输入以下命令：

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}
install-package Microsoft.WindowsAppSDK -Version 1.0.0-preview3 -ProjectName {yourProjectName}

    或者对 1.0 试验版输入以下命令：

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}
install-package Microsoft.WindowsAppSDK -Version 1.0.0-experimental1 -ProjectName {yourProjectName}

  3. 在应用程序 (package).wapproj 中进行以下更改：

    1. 删除此项组（如果从不同于 0.8.0 的版本进行更新，会看到此项组中引用的相应版本号）：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.8.0]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.8.0]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

    2. 添加此项组以将其替换为 1.0 预览版 3：

      <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="[1.0.0-preview3]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

      或者添加此项组以将其替换为 1.0 试验版：

      <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="[1.0.0-experimental1]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.WindowsAppSDK.WinUI" Version="[1.0.0-experimental1]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

  4. 对项目（.csproj 或 .vcproj）进行以下更改：

    1. 删除此项组（如果从不同于 0.8.0 的版本进行更新，会看到此项组中引用的相应版本号）：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="0.8.0" />
    <PackageReference Include="Microsoft.ProjectReunion.Foundation" Version="0.8.0" />
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="0.8.0" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>

    2. 添加此项组以将其替换为 1.0 预览版 3：

      <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.0.0-preview3" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>

      或者添加此项组以将其替换为 1.0 试验版：

      <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.0.0-experimental1" />
    <PackageReference Include="Microsoft.WindowsAppSDK.Foundation" Version="1.0.0-experimental1" />
    <PackageReference Include="Microsoft.WindowsAppSDK.WinUI" Version="1.0.0-experimental1" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>

  5. 如果无法生成解决方案，请清理生成输出，重启 Visual Studio 并尝试重新运行应用。

从 0.8 预览版更新到 0.8，或在稳定版 0.8 版之间进行更新

如果使用版本 0.8 预览版创建了项目，可以按照这些说明将项目更新为 0.8 稳定版本。 如果创建了一个较旧的 0.8 稳定版本（例如 0.8.0）的项目，并且想要将项目更新到较新的稳定版本（例如 0.8.2），则这些说明也适用。

注意

可通过 Visual Studio 扩展管理器自动更新项目，而无需执行以下手动步骤。 在 Visual Studio 2019 中，单击扩展>管理扩展，然后从左侧菜单栏中选择更新。 从列表中选择“Project Reunion”，然后单击“更新”。

在启动之前，请确保已安装所有先决条件里提到的 Windows 应用 SDK，包括最新的 VSIX 和 NuGet 包。 有关更多详细信息，请参阅为 Windows 应用 SDK 安装工具。

首先，执行以下操作：

  • 在 .wapproj 文件中，如果“TargetPlatformMinVersion”比 10.0.17763.0 旧，请将其更改为 10.0.17763.0。

接下来，对项目进行以下更改：

  1. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。

  2. 输入以下命令：

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}
install-package Microsoft.ProjectReunion -Version 0.8.2 -ProjectName {yourProjectName}

  3. 在应用程序 (package).wapproj 中进行以下更改：

    1. 删除此项组（如果从不同于 0.8 预览版的版本进行更新，会看到此项组中引用的相应版本号）：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.8.0-preview]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.8.0-preview]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

    2. 添加此项组以替换它：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.8.2]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.8.2]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

  4. 对项目（.csproj 或 .vcproj）进行以下更改：

    1. 删除此项组（如果从不同于 0.8 预览版的版本进行更新，会看到此项组中引用的相应版本号）：
      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="0.8.0-preview" />
    <PackageReference Include="Microsoft.ProjectReunion.Foundation" Version="0.8.0-preview" />
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="0.8.0-preview" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>
    2. 添加此项组以替换它：
      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="0.8.2" />
    <PackageReference Include="Microsoft.ProjectReunion.Foundation" Version="0.8.2" />
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="0.8.2" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>

  5. 如果无法生成解决方案，请清理生成输出，重启 Visual Studio 并尝试重新运行应用。

从 0.5 更新到 0.8

如果使用版本 0.5 稳定版创建了项目，可以按照这些说明将项目更新为 0.8 稳定版的版本。

注意

可通过 Visual Studio 扩展管理器自动更新项目，而无需执行以下手动步骤。 在 Visual Studio 2019 中，单击扩展>管理扩展，然后从左侧菜单栏中选择更新。 从列表中选择“Project Reunion”，然后单击“更新”。

在启动之前，请确保已安装所有先决条件里提到的 Windows 应用 SDK，包括最新的 VSIX 和 NuGet 包。 有关更多详细信息，请参阅为 Windows 应用 SDK 安装工具。

首先，执行以下操作：

  • 在 .wapproj 文件中，如果“TargetPlatformMinVersion”比 10.0.17763.0 旧，请将其更改为 10.0.17763.0。

接下来，对项目进行以下更改：

  1. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。

  2. 输入以下命令：

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}
install-package Microsoft.ProjectReunion -Version 0.8.0 -ProjectName {yourProjectName}

  3. 将以下行添加到项目（.csproj 或 .vcproj）文件，使其位于第一个 <PropertyGroup> 中：

    <UseWinUI>true</UseWinUI>

  4. 在应用程序 (package).wapproj 中进行以下更改：

    1. 添加以下部分：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.8.0]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.8.0]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

    2. 找到以下行：

      <AssetTargetFallback>net5.0-windows$(TargetPlatformVersion);$(AssetTargetFallback)</AssetTargetFallback>

      移动此行，将其放在 <TargetPlatformVersion> 标记正下方的新行上。

    3. 删除此项组（如果从早于 0.5.7 的版本进行更新，会看到此项组中引用的较早版本号）：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.5.7]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.5.7]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

  5. 如果无法生成解决方案，请清理生成输出，重启 Visual Studio 并尝试重新运行应用。

从 0.5 预览版更新到 0.8 预览版

如果使用版本 0.5 预览版创建了项目，可以按照这些说明更新项目，以使用 0.8 预览版的版本。

注意

可通过 Visual Studio 扩展管理器自动更新项目，而无需执行以下手动步骤。 在 Visual Studio 2019 中，单击扩展>管理扩展，然后从左侧菜单栏中选择更新。 从列表中选择“Project Reunion”，然后单击“更新”。

在启动之前，请确保已安装所有先决条件里提到的 Windows 应用 SDK，包括最新的 VSIX 和 NuGet 包。 有关更多详细信息，请参阅为 Windows 应用 SDK 安装工具。

首先，执行以下操作：

  • 在 .wapproj 文件中，如果“TargetPlatformMinVersion”比 10.0.17763.0 旧，请将其更改为 10.0.17763.0。

  • C++ 和 C# 应用的默认项目模板包含以下行。 不再为桌面应用调用 Application.Suspending 事件，因此，如果这些行仍存在于代码中，请确保删除它们（以及此事件的任何其他用法）：

    this.Suspending += OnSuspending;

    Suspending({ this, &App::OnSuspending });

接下来，对项目进行以下更改：

  1. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。

  2. 输入以下命令：

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}
install-package Microsoft.ProjectReunion -Version 0.8.0-preview -ProjectName {yourProjectName}

  3. 在应用程序 (package).wapproj 中进行以下更改：

    1. 添加以下部分：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.8.0-preview]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.8.0-preview]">
    <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

    2. 将以下行添加到 <TargetPlatformVersion> 标记正下方的新行。

      <AssetTargetFallback>net5.0-windows$(TargetPlatformVersion);$(AssetTargetFallback)</AssetTargetFallback>

    3. 删除以下行：

      <AppxTargetsLocation Condition="'$(AppxTargetsLocation)'==''">$(MSBuildThisFileDirectory)build\</AppxTargetsLocation>

      还有这些行：

      <Import Project="$(Microsoft_ProjectReunion_AppXReference_props)" />
<Import Project="$(Microsoft_WinUI_AppX_targets)" />

      以及此项组：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.5.0]" GeneratePathProperty="true">
      <ExcludeAssets>all</ExcludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.5.0]" GeneratePathProperty="true">
      <ExcludeAssets>all</ExcludeAssets>
    </PackageReference>
</ItemGroup>

  4. 对项目（.csproj 或 .vcproj）进行以下更改：

    1. 删除此项组：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="0.5.0-prerelease" />
    <PackageReference Include="Microsoft.ProjectReunion.Foundation" Version="0.5.0-prerelease" />
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="0.5.0-prerelease" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>

    2. 添加此项组：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="0.8.0-preview" />
    <PackageReference Include="Microsoft.ProjectReunion.Foundation" Version="0.8.0-preview" />
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="0.8.0-preview" />
    <Manifest Include="$(ApplicationManifest)" />
</ItemGroup>

  5. 如果无法生成解决方案，请清理生成输出，重启 Visual Studio 并尝试重新运行应用。

从 0.5 预览版更新到 0.5

如果使用版本 0.5 预览版创建了项目，可以按照这些说明将项目更新为稳定版本 0.5.7。

在启动之前，请确保已安装所有先决条件里提到的 Windows 应用 SDK，包括最新的 VSIX 和 NuGet 包。 有关更多详细信息，请参阅为 Windows 应用 SDK 安装工具。

首先，执行以下操作：

  • [仅桌面应用] 在 .wapproj 文件中，如果“TargetPlatformMinVersion”比 10.0.17763.0 旧，请将其更改为 10.0.17763.0。

  • C++ 和 C# 应用的默认项目模板包含以下行。 不再为桌面应用调用 Application.Suspending 事件，因此，如果这些行仍存在于代码中，请确保删除它们（以及此事件的任何其他用法）：

    this.Suspending += OnSuspending;

    Suspending({ this, &App::OnSuspending });

接下来，对项目进行以下更改：

  1. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。

  2. 输入以下命令：

    uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.Foundation -ProjectName {yourProject}
uninstall-package Microsoft.ProjectReunion.WinUI -ProjectName {yourProject}
install-package Microsoft.ProjectReunion -Version 0.5.7 -ProjectName {yourProjectName}

  3. 如果有 UWP 应用，则应在此阶段完成更新过程。 如果有桌面应用，请在应用程序 (package).wapproj 中进行以下更改：

    1. 添加以下部分：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.5.7]">
        <IncludeAssets>build</IncludeAssets>
    </PackageReference>
</ItemGroup>

    2. 找到 <TargetPlatformVersion> 标记，并将以下项添加到该标记正下方的新行上

      <AssetTargetFallback>net5.0-windows$(TargetPlatformVersion);$(AssetTargetFallback)</AssetTargetFallback>

    3. 删除以下行：

      <AppxTargetsLocation Condition="'$(AppxTargetsLocation)'==''">$(MSBuildThisFileDirectory)build\</AppxTargetsLocation>

      还有这些行：

      <Import Project="$(Microsoft_ProjectReunion_AppXReference_props)" />
<Import Project="$(Microsoft_WinUI_AppX_targets)" />

      以及此项组：

      <ItemGroup>
    <PackageReference Include="Microsoft.ProjectReunion" Version="[0.5.0-prerelease]" GeneratePathProperty="true">
      <ExcludeAssets>all</ExcludeAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.ProjectReunion.WinUI" Version="[0.5.0-prerelease]" GeneratePathProperty="true">
      <ExcludeAssets>all</ExcludeAssets>
    </PackageReference>
</ItemGroup>

从 WinUI 3 预览版 4 更新到 0.5

如果使用 WinUI 3 预览版 4 创建了桌面应用，则可按以下说明将项目更新为 Project Reunion 0.5。

在启动之前，请确保已安装所有先决条件里提到的 Windows 应用 SDK，包括最新的 VSIX 和 NuGet 包。 有关更多详细信息，请参阅为 Windows 应用 SDK 安装工具。

首先，执行以下操作：

  • 在 .wapproj 文件中，如果“TargetPlatformMinVersion”比 10.0.17763.0 旧，请将其更改为 10.0.17763.0。

  • C++ 和 C# 应用的默认项目模板包含以下行。 不再为桌面应用调用 Application.Suspending 事件，因此，如果这些行仍存在于代码中，请确保删除它们（以及此事件的任何其他用法）：

    this.Suspending += OnSuspending;

    Suspending({ this, &App::OnSuspending });

接下来，对项目进行以下更改：

  1. 在 Visual Studio 中，转到工具>Nuget 包管理器>包管理器控制台。

  2. 输入以下命令：

    uninstall-package Microsoft.WinUI -ProjectName {yourProject}
install-package Microsoft.ProjectReunion -Version 0.5.7 -ProjectName {yourProjectName}

  3. 在应用程序 (package).wapproj 中进行以下更改：

    1. 添加以下部分：

      <ItemGroup>
  <PackageReference Include="Microsoft.ProjectReunion" Version="[0.5.7]">
    <IncludeAssets>build</IncludeAssets>
  </PackageReference>
</ItemGroup>

    2. 删除以下各行：

      <AppxTargetsLocation Condition="'$(AppxTargetsLocation)'==''">$(MSBuildThisFileDirectory)build\</AppxTargetsLocation>

      <Import Project="$(AppxTargetsLocation)Microsoft.WinUI.AppX.targets" />

  4. 在项目的 {YourProject}(package)/build/ 文件夹下，删除现有的 Microsoft.WinUI.AppX.targets 文件。