使用擴充功能 SDK 進行程式設計

為了瞭解Windows 10如何讓您的通用 Windows 平臺 (UWP) app 有效地以不同的裝置類別為目標，本主題將說明下列概念。

• 裝置系列
• 擴充功能 SDK
• API 合約

我們也示範如何在您的程式設計中使用它們。

影片- UWP 和裝置系列簡介

 

裝置系列，以及您應用程式的目標裝置系列

裝置系列會識別 API、系統特性以及您對於各種裝置系列可以預期的行為。

裝置系列是作業系統 (作業系統) 的基礎。 例如，電腦和平板電腦會執行桌上出版的作業系統，且以桌面裝置系列為基礎。 IoT 裝置會執行以 IoT 裝置系列為基礎的作業系統 IoT 版本。

每個子裝置系列都會將自己的 API 新增至繼承自通用裝置系列的 API。 子裝置系列中產生的 API 聯集保證存在於以該裝置系列為基礎的 OS 中，因此存在於執行該 OS 的每個裝置上。

應用程式的目標裝置系列 (或系列) 決定是您的 目標。 該決策會以這些重要的方式影響您的 app。 它會決定

• 提供您應用程式從 Microsoft Store (安裝之裝置系列，因此當您設計應用程式的 UI) 時，需要考慮的規格，以及
• 您可以在主機裝置) (執行應用程式的裝置上，依賴的特定 API 集合。

藉 由依賴存在，我們表示您可以呼叫這些 API，而不需要先進行測試，以查看它們是否存在於主機裝置上。 您鎖定的裝置系列可保證 (不同裝置系列) 的不同保證。

設定目標裝置系列

在應用程式套件資訊清單來源檔案中， (Package.appxmanifest 檔案 ) ，TargetDeviceFamily 元素具有 Name 屬性。 該屬性的值是應用程式目標裝置系列的名稱。 下列值有效。

• Windows.Desktop
• Windows.Holographic
• Windows.IoT
• Windows.Mobile
• Windows.Team
• Windows.Universal
• Windows.Xbox

根據預設，您的 UWP app 會以通用裝置系列 (為目標，也就是 Microsoft Visual Studio 指定 Windows.UniversalTargetDeviceFamily) 。 這表示您的應用程式可以安裝在所有Windows 10裝置上，而且您可以依賴主機裝置上存在的一組大型核心 API。 這類應用程式需要具有高度調適型 UI 和完整的輸入功能，因為它可以在各種裝置上執行。 請參閱本主題稍後 的不同螢幕大小預覽您的 UI 。

如果您想要限制應用程式提供給安裝 Microsoft Store 的裝置系列，您可以選擇以不同的裝置系列為目標，例如桌面裝置系列 (Windows.Desktop) ，或 IoT 裝置系列 (Windows.IoT) 。 當然，可以裝載應用程式的裝置較少，但您將能夠依賴這些裝置上存在的較大 API 集合， (這些裝置上將設定為通用裝置系列中的 API，以及目標裝置系列中的設定) 。 這類應用程式通常只需要適中調適型;它可以稍微特製化其 UI 和輸入功能，因為它只能在特定種類的裝置上執行。

提示

但您也可以擁有這兩個世界的最佳專案。 您可以將應用程式設定為在所有Windows 10裝置上執行，而且當您發現正在其中一個裝置上執行時，也可以存取特定系列裝置的特殊功能。 這兩個世界的最佳案例需要一些額外的工作，我們將在本主題稍後深入探討該案例的詳細資料。

設定目標裝置系列版本

API 會隨著時間新增至 Windows，因此選擇裝置系列的另一個維度是決定目標版本 (或版本) 。 Visual Studio 中的某些專案類型有屬性頁，您可以在其中設定目標平臺版本。 但對於所有專案類型，您可以直接在專案檔中設定目標平臺版本。

以下是顯示專案檔中相關屬性的範例。

<!-- MyProject.Xxxproj -->
<PropertyGroup Label="Globals">
    ...
    <WindowsTargetPlatformVersion>10.0.19041.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17134.0</WindowsTargetPlatformMinVersion>
    ...
</PropertyGroup>

在建置階段，這些值 (會與) Package.appxmanifestTargetDeviceFamily@Name的值一起複製到 AppxManifest.xml 專案輸出檔案夾中產生的檔案中。 以下為範例。

<!-- AppxManifest.xml -->
<Dependencies>
    <TargetDeviceFamily Name="Windows.Universal"
        MaxVersionTested="10.0.19041.0"
        MinVersion="10.0.17134.0" />
    ...
</Dependencies>

MaxVersionTested 會指定應用程式的目標裝置系列版本上限，且您已針對它進行測試。 MinVersion會指定您應用程式的目標裝置系列最低版本。 如需詳細資訊，請參閱 TargetDeviceFamily。

重要

您應該透過 Visual Studio 專案的屬性頁，或專案檔中的 WindowsTargetPlatformVersion 和 WindowsTargetPlatformMinVersion 值來設定這些版本號碼。 請勿編輯 AppxManifest.xml ，因為組建會覆寫該檔案。 而且請勿在應用程式套件資訊清單來源檔案 Package.appxmanifest 中編輯TargetDeviceFamily元素的MinVersion和MaxVersionTested屬性， (檔案) ，因為這些值會被忽略。

擴充功能 SDK，以及如何參考它們

如果您在 Visual Studio 專案中，將目標從通用裝置系列變更為一些其他裝置系列，則需要新增對應至該裝置系列之擴充功能 SDK 的參考。 這可讓裝置系列中的 API 可供您的專案使用。

例如，如果您以 IoT 裝置系列為目標，則 (方案總管) 按一下 [專案>新增參考...]>通用 Windows>延伸模組，然後選取適用于 UWP 的適當 Windows IoT 擴充功能版本。 例如，如果您想要呼叫的最新 IoT API 是在 10.0.17134.0 版中引進，請選取該版本。

這是該參考在專案檔中的外觀。

<ItemGroup>
    <SDKReference Include="WindowsIoT, Version=10.0.17134.0" />
</ItemGroup>

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

\Program Files (x86)\Windows Kits\10\Extension SDKs\WindowsIoT\10.0.17134.0

其他擴充功能 SDK 包括 適用于 UWP 的 Windows 傳統型擴充功能、適用于 UWP 的 Windows Mobile Extensions，以及 適用于 UWP 的 Windows Team Extensions。

如果您離開以通用裝置系列為目標的應用程式，您仍然可以新增一或多個擴充功能 SDK 的參考。 參考您想要呼叫的其他 API，以參考哪一個擴充功能 SDK。 請記住，您的目標是通用裝置系列，因此這些是您可以 依賴 的唯一 API。 如需擴充功能 SDK () 所參考的 API，您必須在執行時間測試它們是否存在於主機裝置上，再呼叫它們 (本主題稍後的 撰寫程式碼 一節中 (詳細資料) 。 當然，您不需要針對通用裝置系列中的 API 執行該測試。 這是我們在上一節中所提及的兩個世界最佳案例。

藉由使用擴充功能 SDK，您可以鎖定特定系列裝置的唯一 API，進而存取其特製化功能。 不論您是否以對應的裝置系列為目標，都可以這麼做。

API 合約，以及如何查閱它們

裝置系列中的 API 會細分為稱為 API 合約的群組。 發行新版本的裝置系列時，該新版本基本上只是代表屬於該裝置系列之所有 API 合約新版本的集合。

例如，名為 Windows.Foundation.UniversalApiContract 的 API 合約在 6.0 版隨附于通用裝置系列 10.0.17134.0 版時。 但是，該合約隨附于該相同裝置系列 10.0.19041.0 版時，其版本為 10.0。

查閱 WinRT API 的 API 合約

讓我們看看如何查閱任何指定Windows 執行階段 API 的 API 合約名稱和版本號碼。 在本主題稍後 的撰寫程式碼 一節中，您將會看到為何及如何使用該資訊。

作為第一個範例，我們將採用 StorageFolder.TryGetChangeTracker 方法。 在該主題的Windows 10需求一節中，我們可以看到StorageFolder.TryGetChangeTracker第一次引進版本 6.0 Windows.Foundation.UniversalApiContract 。

接下來，讓我們看看 StorageFolder.TryGetItemAsync 方法的主題。 該主題中沒有Windows 10需求一節。 請改為查看 StorageFolder 類別本身的主題。 有答案的Windows 10需求一節。 由於 StorageFolder.TryGetItemAsync 主題不會說出任何不同，因此我們可以認為其與父類別共用其需求。 因此，第一次引進 StorageFolder.TryGetItemAsync ，版本為 1.0 Windows.Foundation.UniversalApiContract 。

如何選擇要設為目標的裝置系列

以下是一些可協助您決定要設為目標的裝置系列的考慮事項。 如需詳細資訊，請參閱 TargetDeviceFamily。

最大化您的應用程式觸達範圍

若要使用您的應用程式達到各種裝置類型上限，因此若要盡可能在多個裝置上執行，您的應用程式應以通用裝置系列為目標。 具體而言，如我們所見，您會以通用裝置系列的範圍為目標。

將您的應用程式限制為一種裝置

您可能不想讓應用程式在各種裝置尺寸上執行;可能是針對桌上型電腦或 Xbox 主控台特製化。 在此情況下，您可以選擇以其中一個子裝置系列為目標。

將您的應用程式限制為所有可能裝置的子集

您可以改為以兩個 (或更多) 子裝置系列為目標，而不是以通用裝置系列為目標，或以其中一個子裝置系列為目標。 以傳統型和行動裝置為目標對您的應用程式而言可能很合理。 或桌面和小組。 或桌面、行動裝置和小組等等。

排除特定版本的裝置系列支援

在罕見的情況下，您可能會希望您的應用程式在具有特定裝置系列特定版本的裝置上執行。 例如，假設您的應用程式是以通用裝置系列 10.0.x.0 版為目標。 當作業系統版本在未來變更時，假設為 10.0.x.2，在該時間點，您可以指定您的應用程式在 Xbox 10.0.x.1 版以外的任何地方執行，方法是將您的應用程式設為 10.0.x.0，而 Xbox 的 10.0.x.2 版除外。 您的 App 將會無法適用 Xbox 10.0.x.1 (含) 和更舊版本的裝置系列版本集合。

撰寫程式碼

大部分的程式碼都會是通用的，因為它會在每部裝置上以相同方式執行。 但針對針對特定裝置系列量身打造的程式碼，您可以選擇使用調適型程式碼。 讓我們考慮這些不同的案例。

呼叫目標裝置系列所實作的 API

每當您想要在 UWP app 中呼叫 API 時，您會想要知道 API 是否由應用程式的目標裝置系列實作。 Visual Studio IntelliSense 會顯示通用裝置系列中的 API ，以及 可供您參考的任何擴充功能 SDK () 使用的 API。

Windows 執行階段 API 參考檔會告訴您 API 所屬的裝置系列。 如果您查閱Windows 執行階段 API 的 API 參考主題，並尋找Windows 10需求一節，您會看到實作裝置系列是什麼，以及 API 第一次出現的該裝置系列版本。 如果沒有Windows 10需求區段，請查看成員的擁有類別，並在該處查看Windows 10需求一節中的資訊。 該資訊也會套用至成員。

呼叫目標裝置系列未實作的 API

當您想要在已參考的擴充功能 SDK 中呼叫 API，但該 API 不屬於您目標裝置系列的情況。

例如，您可能以通用裝置系列為目標，但每當應用程式在桌面裝置上執行時，您都想要呼叫的桌面 API。

或者，您的應用程式可能支援舊版的裝置系列，但有一個 API 您想要呼叫，該 API 僅適用于相同裝置系列的最新版本。

在這種情況下，您可以選擇撰寫調適型程式碼，以便安全地呼叫這些 API。 下一節說明如何。

使用ApiInformation撰寫自適性程式碼

有兩個步驟涉及使用自適性程式碼來有條件地呼叫 API。 第一個步驟是讓 API 可供您的專案使用。 若要這樣做，請新增延伸模組 SDK 的參考，此 SDK 代表擁有 API 的裝置系列。

第二個步驟是在程式碼的條件中使用 ApiInformation 類別，以測試您要呼叫的 API 是否存在。 每當您的應用程式執行時，都會評估此條件。 但是它只會評估為 true API 存在且可供呼叫的裝置上。

如果您想要只呼叫少數 API，您可以使用 ApiInformation.IsTypePresent 方法，如下所示。

// Cache the value, instead of querying it multiple times.
bool isHardwareButtonsAPIPresent =
    Windows.Foundation.Metadata.ApiInformation.IsTypePresent("Windows.Phone.UI.Input.HardwareButtons");

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

在此情況下，確信 HardwareButtons 類別的存在表示 CameraPressed 事件的存在，因為 類別和成員的需求資訊相同。 但此時，新成員會新增至已導入的類別，而這些成員稍後會在版本號碼 中引進 。 在這種情況下，不是使用 IsTypePresent，您可以使用 IsEventPresent、IsMethodPresent、IsPropertyPresent 和類似方法，測試個別成員是否存在。 以下為範例。

bool isHardwareButtons_CameraPressedAPIPresent =
    Windows.Foundation.Metadata.ApiInformation.IsEventPresent
        ("Windows.Phone.UI.Input.HardwareButtons", "CameraPressed");

如我們所知，裝置系列內的 API 集合會進一步細分為稱為 API 合約的細分。 您可以使用 ApiInformation.IsApiContractPresent 方法以測試 API 協定是否存在。 這是執行單一條件的有效方式，可瞭解所有屬於相同 API 合約版本的大量 API 是否存在或其他情況。

如需如何判斷第一次介紹 API () 相關 API 的 API 合約的相關資訊，請參閱本主題稍早 的查閱 WinRT API 的 API 合約 一節。

一旦您擁有該資訊，您就可以將其插入調適型程式碼中。 例如，如果 API 合約的名稱是 Windows.Devices.Scanners.ScannerDeviceContract ，而且其主要和次要版本號碼分別為 1 和 0，則您的條件會如下所示。

bool isWindows_Devices_Scanners_ScannerDeviceContract_1_0Present =
    Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
        ("Windows.Devices.Scanners.ScannerDeviceContract", 1, 0);

在不同的螢幕大小上預覽您的 UI

我們建議您將應用程式的觸達範圍最大化。 但即使您只以一種裝置尺寸為目標，您的應用程式最終仍可能會顯示不同的螢幕大小。

當您準備好查看應用程式在特定大小的螢幕上外觀和配置時，請使用 Visual Studio 中的裝置預覽工具列，在小型或中型行動裝置、電腦上或大型電視螢幕上預覽 UI。 如此一來，如果您已使用 XAML 的調適型配置功能 (看到 具有視覺狀態和狀態觸發 程式的調適型配置) ，您也可以測試這一點。

您不需要事先決定您將支援的每個裝置類型。 您可以隨時將額外的裝置大小新增至您的專案。

另請參閱

• 裝置系列擴充功能 SDK 與 API 合約
• TargetDeviceFamily
• 什麼是通用 Windows 平臺 (UWP) app
• 版本調適型應用程式