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

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

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

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

—UWP 和裝置系列的影片簡介

 

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

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

裝置系列

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

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

您的應用程式將 鎖定 哪些裝置系列 (或) 系列的決策,是您要進行的。 該決策會以這些重要的方式影響您的 app。 它會決定

  • 您的應用程式提供給您的應用程式從 Microsoft Store (安裝的裝置系列,以及您在設計應用程式的 UI) 時需要考慮的外型規格,以及
  • 您可以依賴在執行應用程式的裝置上有一組特定的 Api, (主機裝置) 。

基於現狀,我們表示您可以呼叫這些 api,而不需要先進行測試,以查看它們是否存在於主機裝置上。 您所設定的裝置系列可保證 (不同裝置系列) 的不同保證。

設定您的目標裝置系列

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

  • Windows Desktop
  • Windows 全像
  • Windows IoT
  • Windows Mobile
  • Windows. Team
  • Windows 通用
  • Windows Xbox

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

如果您想要限制提供應用程式從 Microsoft Store 安裝的裝置系列,您可以選擇以不同的裝置系列為目標, — 例如,桌面裝置系列 (Windows.Desktop) 或 IoT 裝置系列 (Windows.IoT) 。 當然,可能會有較少的裝置可裝載您的應用程式,但您可以依賴在這些裝置上有較大量的 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>

在組建階段,這些值會 (,並將值 TargetDeviceFamily@NamePackage.appxmanifest) 複製到 AppxManifest.xml 專案輸出檔案夾中產生的檔案。 以下為範例。

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

MaxVersionTested 指定您的應用程式的目標裝置系列的最大版本,您已進行測試。 和 MinVersion 會指定您的應用程式設為目標之裝置系列的最小版本。 如需詳細資訊,請參閱 y

重要

您應該透過 Visual Studio 專案的屬性頁或專案檔中的 WindowsTargetPlatformVersionWindowsTargetPlatformMinVersion 值,來設定這些版本號碼。 請勿編輯 AppxManifest.xml ,因為組建會覆寫該檔案。 您也不會在檔案) (的應用程式套件資訊清單原始程式檔中編輯y元素的MinVersionMaxVersionTested屬性 Package.appxmanifest ,因為這些值會被忽略。

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

如果您在 Visual Studio 專案中,您將目標從通用裝置系列變更為其他裝置系列,則必須將參考新增至對應于該裝置系列的擴充功能 SDK。 這會讓該裝置家族中的 Api 可供您的專案使用。

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

選取 IoT 擴充功能 SDK

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

<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 延伸模組,以及適用于 Uwp 的 windows 小組擴充功能。

如果您將應用程式的目標設為通用裝置系列,您仍然可以新增一個或多個擴充功能 Sdk 的參考。 參考任何副檔名 Sdk 包含您想要呼叫的其他 Api。 請記住,您的目標是通用裝置系列,因此這些都是您可以 依賴 的唯一 api。 在您所參考的擴充功能 SDK () 中的 Api,您必須先測試它們是否存在於執行時間的主機裝置上,再呼叫它們 (更多詳細資料,請參閱本主題稍後的「 撰寫程式碼 」一節) 。 當然,您不需要針對通用裝置系列中的 Api 執行該測試。 這是我們在上一節中提到的最佳案例。

藉由使用擴充功能 SDK,您可以將特定裝置系列的唯一 Api 設為目標,進而存取其特殊功能。 無論您的目標是否為對應的裝置系列,您都可以這麼做。

API 合約,以及如何進行查詢

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

例如,名為的 API 合約在 Windows.Foundation.UniversalApiContract 隨附于通用裝置系列的版本10.0.17134.0 時為6.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 是第一次在1.0 版中引進的 Windows.Foundation.UniversalApiContract

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

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

最大化您的應用程式範圍

若要使用您的應用程式達到裝置類型的最大範圍,並讓它在盡可能多的裝置上執行,您的應用程式應該以通用裝置系列為目標。 具體來說,如我們所見,您將以一系列的通用裝置系列為目標。

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

您可能不想要讓應用程式在各種不同的裝置外型規格上執行;或許是針對桌上型電腦或 Xbox 主控台進行特製化。 在此情況下,您可以選擇將目標設定為其中一個子裝置系列。

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

您可以改為以兩個 (或多個) 子裝置系列為目標,而不是以通用裝置系列為目標,或以其中一個子裝置系列為目標。 以桌面和行動裝置為目標,對您的應用程式可能有意義。 或桌面和小組。 或桌上型電腦、行動裝置和團隊等等。

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

在罕見的情況下,您可能會想要讓應用程式在特定裝置系列特定版本的裝置 以外 的地方執行。 例如,假設您的應用程式是以通用裝置系列的 10.0. x. 0 為目標。 如果未來的作業系統版本變更為 10.0. 2,您可以將應用程式的目標設定為 10.0. x. x. x. x. — — 2 的 xbox,以指定您的應用程式在任何位置執行。 您的 App 將會無法適用 Xbox 10.0.x.1 (含) 和更舊版本的裝置系列版本集合。

撰寫程式碼

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

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

每當您想要在 UWP 應用程式中呼叫 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。 下一節將為您說明。

使用ApiInformation撰寫適應性程式碼

使用調適型程式碼來有條件地呼叫 API 時,有兩個相關步驟。 第一個步驟是讓 API 可供您的專案使用。 若要這樣做,請新增延伸模組 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,您可以使用 IsEventPresentIsMethodPresentIsPropertyPresent 和類似方法,測試個別成員是否存在。 以下為範例。

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

如我們所知,裝置系列內的一組 Api 會進一步細分為稱為 API 合約的細分。 您可以使用 ApiInformation.IsApiContractPresent 方法以測試 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 的自我調整版面配置功能 (請參閱 教學課程:建立適應性 配置) ,然後也可以進行測試。

Visual Studio 2015 裝置預覽工具列

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

另請參閱