将现有项目更新为不同版本的Windows 应用 SDK

  • 项目

如果使用以前称为 Project Reunion) 或 WinUI 3 的早期版本的Windows 应用 SDK (创建了项目，则可以更新项目以使用最新版本。 若要详细了解每个发布通道中当前提供的内容，请参阅 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 预览版 3。

如果使用版本 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 文件。