共用方式為

將 Windows Phone Silverlight 專案移植到 UWP 專案

  • 發行項

上一個主題是命名空間與類別對應。

您可以在 Visual Studio 中建立新的 Windows 10 專案並將檔案複製到其中，以此開始移植程序。

建立專案並將檔案複製到其中

  1. 啟動 Microsoft Visual Studio 2015，並建立新的空白應用程式 (Windows 通用) 專案。 有關詳細信息，請參閱使用範本快速啟動 Windows 執行階段 8.x 應用程式 (C#、C++、Visual Basic)。 您的新專案將會建置一個可在所有裝置系列上執行的應用程式套件 (appx 檔案)。
  2. 在您的 Windows Phone Silverlight 應用程式專案中，確認您要重複使用的所有原始程式碼檔案和視覺資產檔案。 使用「檔案總管」，將資料模型、檢視模型、視覺資產、資源字典、資料夾結構，以及您希望重複使用的任何其他內容複製到新專案中。 根據需要在磁碟上複製或建立子資料夾。
  3. 將檢視 (例如 MainPage.xaml 和 MainPage.xaml.cs) 也複製到新的專案節點。 同樣地，根據需要建立新的子資料夾，並從專案中移除現有檢視。 但是，在覆寫或移 Visual Studio 產生的檢視之前，請保留一份副本，因為稍後可能會參考它。 移植 Windows Phone Silverlight 應用程式的第一階段重點在於，使其在一個裝置系列上看起來美觀且運作良好。 稍後，您將把注意力轉向確保檢視能順暢適應所有外形規格，並可選擇性地新增任何調適型程式碼，以充分利用特定裝置系列。
  4. 在 [方案總管] 中，確定 [顯示所有檔案] 已切換成開啟。 選擇您複製的檔案，對其按右鍵，然後按一下加入至專案。 這將自動加入其包含的資料夾。 您可以視需要關閉顯示所有檔案。 如果您想要的話，另一個工作流程是使用新增現有項目命令，並在 Visual Studio 方案總管中建立必要的子資料夾。 仔細檢查您的視覺資產是否已將建置動作設為內容，並將複製到輸出目錄設為不要複製。
  5. 在此階段，命名空間和類別名稱的差異會造成大量建置錯誤。 例如，如果開啟 Visual Studio 產生的檢視，您會看到其類型為 Page，而不是 PhoneApplicationPage。 本移植指南中的以下主題會詳細介紹許多 XAML 標記和命令式程式碼的差異。 但是，只需遵循以下常規步驟，即可快速進行移植：在 XAML 標記中的命名空間前置詞宣告中，將「clr-namespace」變更為「using」；使用命名空間和類別對應主題以及 Visual Studio 的尋找及取代命令，對原始程式碼進行大量變更 (例如，將「System.Windows」取代為「Windows.UI.Xaml」) ；在 Visual Studio 的命令式程式碼編輯器中，使用操作功能表上的解析和組織使用命令進行更有針對性的變更。

擴充功能 SDK

移植的應用程式呼叫的大部分通用 Windows 平台 (UWP) API 都會在稱為通用裝置系列的 API 集中實作。 但是，有些是在擴充 SDK 中實作的，而 Visual Studio 只會識別由應用程式的目標裝置系列，或您所參考任何擴充 SDK 實作的 API。

如果您遇到無法找到命名空間、類型或成員的編譯錯誤，那麼這可能就是原因。 開啟 API 參考文件中的 API 主題，並瀏覽至「要求」一節：您將在此知道實作的裝置系列為何。 如果這不是您的目標裝置系列，那麼要讓 API 可用於您的裝置，您將需要參考該裝置系列的擴充 SDK。

按一下專案>新增參考>Windows 通用>擴充功能，並選擇適當的擴充 SDK。 例如，如果要呼叫的 API 僅可在行動裝置系列中使用，且它們是在版本 10.0.x.y 中引入的，則為 UWP 選擇 Windows 行動擴充功能。

這會將以下參考新增到您的專案檔案中：

<ItemGroup>
    <SDKReference Include="WindowsMobile, Version=10.0.x.y">
        <Name>Windows Mobile Extensions for the UWP</Name>
    </SDKReference>
</ItemGroup>

名稱和版本號碼與 SDK 安裝位置中的資料夾相符。 例如，上述資訊符合此資料夾名稱：

\Program Files (x86)\Windows Kits\10\Extension SDKs\WindowsMobile\10.0.x.y

除非您的應用程式面向實作 API 的裝置系列，否則您需要在呼叫 API 之前使用 ApiInformation 類別來測試 API 是否存在 (這稱為調適型程式碼)。 然後，無論您的應用程式在何處執行，都會評估此條件，但僅在存在 API 並因此可供呼叫的裝置上評估為 True。 僅在先檢查通用 API 是否存在後，才使用擴充 SDK 和調適型程式碼。 下一節會提供一些範例。

另請參閱應用程式套件資訊清單。

盡量重複使用標記和程式碼

您會發現，稍微重構和/或新增調適型程式碼 (如下所述) 可最大化適用於所有裝置系列的標記和程式碼。 以下是詳細資料。

  • 不需要特別考慮適用於所有裝置系列的檔案。 應用程式將在其執行的所有裝置系列上使用這些檔案。 這包括 XAML 標記檔案、命令式原始程式碼檔案和資產檔案。
  • 您的應用程式可以偵測正在執行的裝置系列，並瀏覽到專為該裝置系列設計的檢視。 如需詳細資訊，請參閱偵測應用程式執行的平台。
  • 如果沒有其他選擇，您可能會發現有用的類似技術是為標記檔案或ResourceDictionary 檔案 (或包含該檔案的資料夾) 指定一個特殊名稱，讓您的應用程式在特定裝置系列上執行時，才會在執行階段自動載入該名稱。 這項技術於 Bookstore1 案例研究中說明。
  • 若要使用的功能並非所有裝置系列都可用 (例如印表機、掃描器或相機按鈕)，您可以編寫調適型程式碼。 請參閱本主題中的條件式編譯和調適型程式碼中的第三個範例。
  • 如果您想同時支援 Windows Phone Silverlight 和 Windows 10，則可以在專案之間共用原始程式碼檔案。 作法如下：在 Visual Studio 中，右鍵按一下方案總管中的專案，選取新增現有項目，選擇要共用的檔案，然後按一下新增為連結。 將原始程式碼檔案儲存在檔案系統上的公共資料夾中，連結到它們的專案可以在其中看到它們，也別忘了將它們新增至原始檔控制中。 如果您可以分解命令式原始程式碼，讓大部分的檔案能在兩個平台上執行，那麼您就不需要為其準備兩個副本。 您可以盡量將檔案中的特定平台邏輯包裝在條件式編譯指示詞內，或在必要時包裝執行階段條件。 請參閱下方的下一節和 C# 前置處理器指示詞。
  • 為了在二進位層級 (而非原始程式碼層級) 重複使用，可移植類別庫支援 Windows Phone Silverlight 中提供的 .NET API 子集以及 Windows 10 應用程式 (.NET Core) 子集。 可移植類別庫組件與這些 .NET 平台等二進位相容。 使用 Visual Studio 建立一個面向可移植類別庫的專案。 請參閱使用可移植類別庫進行跨平台開發。

條件式編譯和調適型程式碼

如果您想在單一程式碼檔案中同時支援 Windows Phone Silverlight 和 Windows 10，那麼您可以這樣做。 如果您查看 Windows 10 專案的專案屬性頁面，您將看到該專案將 WINDOWS_UAP 定義為條件式編譯符號。 一般來說，可以使用以下邏輯來進行條件式編譯。

#if WINDOWS_UAP
    // Code that you want to compile into the Windows 10/11 app.
#else
    // Code that you want to compile into the Windows Phone Silverlight app.
#endif // WINDOWS_UAP

如果您有可在 Windows Phone Silverlight 應用程式和 Windows Runtime 8.x 應用程式之間共用的程式碼，那麼您可能已經擁有具有以下邏輯的原始程式碼：

#if NETFX_CORE
    // Code that you want to compile into the Windows Runtime 8.x app.
#else
    // Code that you want to compile into the Windows Phone Silverlight app.
#endif // NETFX_CORE

如果是這樣，而您現在也想支援 Windows 10，那麼您也可以這樣做。

#if WINDOWS_UAP
    // Code that you want to compile into the Windows 10/11 app.
#else
#if NETFX_CORE
    // Code that you want to compile into the Windows Runtime 8.x app.
#else
    // Code that you want to compile into the Windows Phone Silverlight app.
#endif // NETFX_CORE
#endif // WINDOWS_UAP

您可能已使用條件式編譯來限制 Windows Phone 對硬體返回按鈕的處理。 在 Windows 10 中，返回按鈕事件是通用概念。 在硬體或軟體中實作的返回按鈕都會引發 BackRequested 事件，因此必須要進行處理。

       Windows.UI.Core.SystemNavigationManager.GetForCurrentView().BackRequested +=
            this.ViewModelLocator_BackRequested;

...

    private void ViewModelLocator_BackRequested(object sender, Windows.UI.Core.BackRequestedEventArgs e)
    {
        // Handle the event.
    }

您可能已使用條件式編譯來限制 Windows Phone 對硬體相機按鈕的處理。 在 Windows 10 中，硬體相機按鈕是行動裝置系列的特有概念。 由於我們要讓一個應用程式套件能在所有裝置上執行，因此使用所謂的調適型程式碼將編譯階段條件變更為執行階段條件。 若要這麼做，我們使用 ApiInformation 類別在執行階段查詢 HardwareButtons 類別是否存在。 HardwareButtons 是在行動擴充 SDK 中定義的，因此我們需要將對該 SDK 的參考新增到專案中，以便編譯此程式碼。 但請注意，處理常式只會在實作行動擴充 SDK 中所定義類型的裝置上執行，即行動裝置系列。 因此，以下程式碼只會謹慎使用現有的功能，儘管它實現的方式與條件式編譯不同。

       // Note: Cache the value instead of querying it more than once.
        bool isHardwareButtonsAPIPresent = Windows.Foundation.Metadata.ApiInformation.IsTypePresent
            ("Windows.Phone.UI.Input.HardwareButtons");

        if (isHardwareButtonsAPIPresent)
        {
            Windows.Phone.UI.Input.HardwareButtons.CameraPressed +=
                this.HardwareButtons_CameraPressed;
        }

    ...

    private void HardwareButtons_CameraPressed(object sender, Windows.Phone.UI.Input.CameraEventArgs e)
    {
        // Handle the event.
    }

另請參閱偵測應用程式執行的平台。

應用程式套件資訊清單

專案中的設定 (包括任何擴充 SDK 參考) 決定了您的應用程式可以呼叫的 API 介面區。 但是，您的應用程式套件資訊清單決定了客戶可從商店安裝您應用程式的實際裝置集。 有關詳細資訊，請參閱 TargetDeviceFamily 中的範例。

請務必了解如何編輯應用程式套件資訊清單，因為後續主題會將其用於某些功能所需的各種宣告、功能和其他設定。 您可以使用 Visual Studio 應用程式套件資訊清單編輯器來進行編輯。 如果方案總管沒有顯示，請從檢視功能表中選擇它。 按兩下 Package.appxmanifest。 這將開啟資訊清單編輯器視窗。 選取適當的索引標籤進行變更，然後儲存變更。 您可能需要確認已移植應用程式資訊清單中的 pm:PhoneIdentity 元素，與您所要移植應用程式的應用程式資訊清單中的內容相符 (有關完整詳細資訊，請參閱 pm:PhoneIdentity 主題)。

請參閱 Windows 10 的套件資訊清單結構描述參考。

下一個主題是疑難排解。