通过

将现有项目更新到不同版本的 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）创建了项目（例如版本 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. 在应用程序（包）中进行以下更改。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. 在应用程序（包）中进行以下更改。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. 在应用程序（包）中进行以下更改。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. 在应用程序（包）中进行以下更改。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 应用，更新过程应在此阶段完成。 如果你有桌面应用，请在应用程序（包）中进行以下更改。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. 在应用程序（包）中进行以下更改。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 文件。