将现有项目更新到 Windows 应用 SDK 的最新版本

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

注意

由于每个应用的单独场景的唯一性,这些说明可能会有问题。 请谨慎地遵循这些说明进行操作,如果发现问题,请在 GitHub 存储库上报告错误

从 0.8 稳定版更新到 1.0 稳定版

如果使用版本 0.8 稳定版(例如版本 0.8.4)创建了项目,则可以按照这些说明将项目更新到 1.0 稳定版。

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

Instructions

  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 稳定版或预览版更新到 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 App 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 App 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 App 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 App 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 App 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 App 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 文件。