將現有專案更新為不同版本的 Windows 應用程式 SDK

  • 發行項

如果您使用舊版 Windows 應用程式 SDK (以前稱為 Project Reunion) 或 WinUI 3 建立專案，則您可以更新專案以便使用較近期的版本。 若要深入瞭解每個發布通道目前可用的功能，請參閱 Windows 應用程式 SDK 發布通道。

注意

以下說明可能會因為每個應用程式個別情境的獨特性而發生問題。 請審慎循步驟操作，如果發現問題，請按照 microsoft-ui-xaml GitHub 存放庫申訴錯誤。

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 Preview 更新為 1.0 Experimental 或 Preview 3

重要

1.0 版 Preview 1 和 Preview 2 包含重大錯誤。 如果您已安裝其中一個預覽版，請參閱如何解決問題。 建議您改用 1.0 Preview 3 版。

如果您使用 0.8 版 Preview 或任何 0.8 版 !例如 0.8.1 版) 建立專案，您可以依照這些指示將專案更新為 1.0 Preview 3 或實驗版。

開始之前，請確定您已安裝所有 Windows 應用程式 SDK 先決條件，包括最新的 VSIX 和 NuGet 套件。 如需詳細資訊，請參閱安裝 Windows 應用程式 SDK 工具。

首先執行下列動作：

  • 在 .wapproj 檔案中，如果您的 TargetPlatformMinVersion 比 10.0.17763.0 更舊，請變更為 10.0.17763.0。

接下來，對您的專案進行下列變更：

  1. 在 Visual Studio 中，前往 [工具]>[NuGet 套件管理員]>[套件管理員主控台]。

  2. 針對 1.0 Preview 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 Experimental 則輸入下列命令：

    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 Preview 3：

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

      或新增此項目群組，取代為 1.0 Experimental：

      <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 Preview 3：

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

      或新增此項目群組，取代為 1.0 Experimental：

      <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 Preview 更新為 0.8 或穩定的 0.8 版之間的版本

如果您使用 0.8 版 Preview 建立專案，您可以依照這些指示將專案更新為穩定版的 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 Preview 以外的版本更新，您會在此項目群組中看到參照的對應版本編號)：

      <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 Preview 以外的版本更新，您會在此項目群組中看到參照的對應版本編號)：
      <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 版 Stable 建立專案，您可以依照這些指示將專案更新為 0.8 Stable 版本。

注意

您可以透過 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 Preview 更新到 0.8 Preview

如果您使用 0.5 版 Preview 建立專案，您可以依照這些指示將專案更新為使用 0.8 版 Preview。

注意

您可以透過 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 Preview 更新為 0.5

如果您使用 0.5 版 Preview 建立專案，您可以依照這些指示將專案更新為穩定版的 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 Preview 4 更新為 0.5

如果您使用 WinUI 3 Preview 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 檔案刪除。