共用方式為


將現有專案更新為不同版本的 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 檔案中,如果您的 TargetPlatformMinVersion10.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 預覽 1 和預覽 2 的重大問題。 建議改用版本 1.0 預覽 3 (1.0.0-preview3)

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