Programmieren mit Erweiterungs-SDKs

Artikel
11/30/2023

In diesem Thema werden die folgenden Konzepte erläutert, um zu verstehen, wie Windows 10 Ihrer Universelle Windows-Plattform-App (UWP) ermöglicht, verschiedene Geräteklassen am effektivsten anzusprechen.

Gerätefamilie
Erweiterungs-SDK
API-Vertrag

Wir zeigen auch, wie Sie sie in Ihrer Programmierung einsetzen.

Video – Einführung in UWP und Gerätefamilien

Gerätefamilien und die Zielgerätefamilie Ihrer App

Eine Gerätefamilie identifiziert die APIs, Systemmerkmale und Verhaltensweisen, die Sie auf allen Geräteklassen erwarten können.

Gerätefamilien

Eine Gerätefamilie ist die Grundlage eines Betriebssystems. Beispielsweise wird auf PCs und Tablets eine Desktopedition des Betriebssystems ausgeführt, die auf der Desktopgerätefamilie basiert. IoT-Geräte führen eine IoT-Edition des Betriebssystems aus, die auf der IoT-Gerätefamilie basiert.

Jede untergeordnete Gerätefamilie fügt den APIs, die sie von der Universellen Gerätefamilie erbt, eigene APIs hinzu. Die resultierende Vereinigung von APIs in einer untergeordneten Gerätefamilie ist garantiert in einem Betriebssystem vorhanden, das auf dieser Gerätefamilie basiert, und somit auf jedem Gerät, auf dem dieses Betriebssystem ausgeführt wird.

Die Entscheidung darüber, auf welche Gerätefamilie (oder -familien) Ihre App ausgerichtet ist, liegt bei Ihnen. Und diese Entscheidung wirkt sich folgendermaßen auf Ihre App aus. Es bestimmt

die Gerätefamilien, denen Ihre App für die Installation aus dem Microsoft Store angeboten wird (und folglich die Formfaktoren, die Sie beim Entwerfen der Benutzeroberfläche Ihrer App berücksichtigen müssen) und
die spezifische Gruppe von APIs, auf die Sie sich verlassen können, wenn sie auf einem Gerät vorhanden sind, auf dem Ihre App ausgeführt wird (das Hostgerät).

Wenn Sie sich darauf verlassen, vorhanden zu sein, bedeutet das, dass Sie diese APIs aufrufen können, ohne zuerst testen zu müssen, ob sie auf dem Hostgerät vorhanden sind. Die Gerätefamilie, auf die Sie abzielen, bietet diese Garantie (unterschiedliche Garantien für verschiedene Gerätefamilien).

Konfigurieren Der Zielgerätefamilie

In der Quelldatei des App-Paketmanifests (der Package.appxmanifest Datei) verfügt das TargetDeviceFamily-Element über das Name-Attribut . Der Wert dieses Attributs ist der Name der Gerätefamilie, auf die Ihre App ausgerichtet ist. Die folgenden Werte sind gültig.

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

Standardmäßig zielt Ihre UWP-App auf die Universelle Gerätefamilie ab (d. a. Microsoft Visual Studio gibt für TargetDeviceFamily anWindows.Universal). Das bedeutet, dass Ihre App auf allen Windows 10 Geräten installiert werden kann und Sie sich darauf verlassen können, dass auf dem Hostgerät eine große Anzahl von APIs vorhanden ist. Eine solche App benötigt eine hochgradig adaptive Benutzeroberfläche und umfassende Eingabefunktionen, da sie auf einer Vielzahl von Geräten ausgeführt werden kann. Weitere Informationen finden Sie unter Vorschau der Benutzeroberfläche auf verschiedenen Bildschirmgrößen weiter unten in diesem Thema.

Wenn Sie die Gerätefamilien einschränken möchten, für die Ihre App zum Installieren aus dem Microsoft Store angeboten wird, können Sie eine andere Gerätefamilie verwenden, z. B. die Desktopgerätefamilie (Windows.Desktop) oder die IoT-Gerätefamilie (Windows.IoT). Natürlich gibt es weniger Geräte, die Ihre App hosten können, aber Sie können sich darauf verlassen, dass auf diesen Geräten eine größere Gruppe von APIs vorhanden ist (dies ist die Einstellung in der Universellen Gerätefamilie sowie die Gruppe in der Zielgerätefamilie). Eine solche App muss in der Regel nur mäßig anpassungsfähig sein. Es kann etwas spezialisiert auf seine Benutzeroberflächen- und Eingabefunktionen sein, da es nur auf einem bestimmten Gerät ausgeführt werden kann.

Tipp

Sie können aber auch das Beste aus beiden Welten haben. Sie können Ihre App so konfigurieren, dass sie auf allen Windows 10 Geräten ausgeführt wird, und auch auf die speziellen Funktionen bestimmter Gerätefamilien zugreifen, wenn Sie feststellen, dass Sie auf einem gerät ausgeführt werden. Für dieses Szenario mit den besten beiden Welten ist ein wenig zusätzlicher Aufwand erforderlich, und wir gehen später in diesem Thema auf die Besonderheiten ein.

Konfigurieren der Version ihrer Zielgerätefamilie

APIs werden Im Laufe der Zeit zu Windows hinzugefügt, sodass eine weitere Dimension bei der Auswahl einer Gerätefamilie die Entscheidung ist, welche Version (oder Versionen) als Ziel verwendet werden soll. Einige Projekttypen in Visual Studio verfügen über eine Eigenschaftenseite, auf der Sie Ihre Zielplattformversionen konfigurieren können. Für alle Projekttypen können Sie ihre Zielplattformversionen jedoch direkt in der Projektdatei konfigurieren.

Hier sehen Sie ein Beispiel, das die relevanten Eigenschaften in einer Projektdatei zeigt.

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

Zur Buildzeit werden diese Werte (zusammen mit dem Wert von TargetDeviceFamily@Name von Package.appxmanifest) in die Datei kopiert, die AppxManifest.xml im Ausgabeordner Ihres Projekts generiert wird. Hier sehen Sie ein Beispiel.

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

MaxVersionTested gibt die maximale Version der Gerätefamilie an, für die Ihre App getestet wurde. Und MinVersion gibt die Mindestversion der Gerätefamilie an, auf die Ihre App abzielt. Weitere Informationen finden Sie unter TargetDeviceFamily.

Wichtig

Sie sollten diese Versionsnummern entweder über die Eigenschaftenseiten Ihres Visual Studio-Projekts oder über die Werte von WindowsTargetPlatformVersion und WindowsTargetPlatformMinVersion in Ihrer Projektdatei konfigurieren. Bearbeiten AppxManifest.xmlSie nicht , da diese Datei vom Build überschrieben wird. Bearbeiten Sie nicht die Attribute MinVersion und MaxVersionTested des TargetDeviceFamily-Elements in der Quelldatei des App-Paketmanifests (die Package.appxmanifest Datei), da diese Werte ignoriert werden.

Erweiterungs-SDKs und wie darauf verwiesen wird

Wenn Sie in Ihrem Visual Studio-Projekt Ihr Ziel von der Universellen Gerätefamilie in eine andere Gerätefamilie ändern, müssen Sie einen Verweis auf das Erweiterungs-SDK hinzufügen, das dieser Gerätefamilie entspricht. Dadurch werden die APIs in dieser Gerätefamilie für Ihr Projekt verfügbar.

Wenn Sie beispielsweise die IoT-Gerätefamilie als Ziel verwenden, klicken Sie (mit ausgewähltem Projektknoten in Projektmappen-Explorer) auf Projekt>Verweis hinzufügen...>Universelles Windows>Erweiterungen, und wählen Sie die entsprechende Version von Windows IoT-Erweiterungen für die UWP aus. Wenn beispielsweise die neueste IoT-API, die Sie aufrufen möchten, in Version 10.0.17134.0 eingeführt wurde, wählen Sie diese Version aus.

Auswählen des IoT-Erweiterungs-SDK

Und so würde dieser Verweis in Ihrer Projektdatei aussehen.

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

Name und Versionsnummer entsprechen den Ordnern am Installationsort Ihres SDKs. Die obigen Informationen entsprechen beispielsweise dem Ordner namens

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

Weitere Erweiterungs-SDKs sind Windows-Desktoperweiterungen für die UWP, Windows Mobile-Erweiterungen für die UWP und Windows Team-Erweiterungen für die UWP.

Wenn Sie Ihre App für die Universelle Gerätefamilie verwenden, können Sie dennoch einen Verweis auf ein oder mehrere Erweiterungs-SDKs hinzufügen. Verweisen Sie darauf, welche Erweiterungs-SDKs die zusätzlichen APIs enthalten, die Sie aufrufen möchten. Denken Sie daran, dass Sie die Universelle Gerätefamilie als Ziel verwenden, sodass dies die einzigen APIs sind, auf die Sie sich verlassen können. Für APIs in den Erweiterungs-SDKs, auf die Sie verwiesen haben, müssen Sie testen, dass sie zur Laufzeit auf dem Hostgerät vorhanden sind, bevor Sie sie aufrufen (weitere Details im Abschnitt Schreiben von Code weiter unten in diesem Thema). Natürlich müssen Sie diesen Test für APIs in der universellen Gerätefamilie nicht durchführen. Dies ist das Beste aus beiden Welten, das wir im vorherigen Abschnitt erwähnt haben.

Mithilfe eines Erweiterungs-SDK können Sie die eindeutigen APIs einer bestimmten Gerätefamilie als Ziel verwenden und dadurch auf deren spezielle Funktionen zugreifen. Sie können dies unabhängig davon tun, ob Sie die entsprechende Gerätefamilie als Ziel verwenden oder nicht.

API-Verträge und deren Nachschlagen

Die APIs in einer Gerätefamilie sind in Gruppen unterteilt, die als API-Verträge bezeichnet werden. Wenn eine neue Version einer Gerätefamilie veröffentlicht wird, stellt diese neue Version im Wesentlichen nur die Sammlung neuer Versionen aller API-Verträge dar, die zu dieser Gerätefamilie gehören.

Beispielsweise befand sich der API-Vertrag mit dem Namen Windows.Foundation.UniversalApiContract in Version 6.0, als er mit Version 10.0.17134.0 der Universellen Gerätefamilie ausgeliefert wurde. Der gleiche Vertrag wurde jedoch in Version 10.0 ausgeführt, als er mit Version 10.0.19041.0 derselben Gerätefamilie ausgeliefert wurde.

Suchen des API-Vertrags für eine WinRT-API

Sehen Wir uns an, wie Sie den Namen und die Versionsnummer des API-Vertrags für alle Windows-Runtime API suchen können. Im Abschnitt Schreiben von Code weiter unten in diesem Thema erfahren Sie, warum und wie Sie diese Informationen verwenden können.

Als erstes Beispiel verwenden wir die StorageFolder.TryGetChangeTracker-Methode . Im Abschnitt Windows 10 Anforderungen dieses Themas ist zu sehen, dass StorageFolder.TryGetChangeTracker erstmals mit Version 6.0 von Windows.Foundation.UniversalApiContracteingeführt wurde.

Als Nächstes sehen wir uns das Thema für die StorageFolder.TryGetItemAsync-Methode an. In diesem Thema gibt es keinen Abschnitt zu Windows 10 Anforderungen. Sehen Sie sich stattdessen das Thema für die StorageFolder-Klasse selbst an. Die Antwort wird im Abschnitt Windows 10 Anforderungen angezeigt. Da das Thema StorageFolder.TryGetItemAsync nichts anderes sagt, können wir daraus schließen, dass es seine Anforderungen mit seiner übergeordneten Klasse teilt. Daher wurde StorageFolder.TryGetItemAsync erstmals mit Version 1.0 von Windows.Foundation.UniversalApiContracteingeführt.

Auswählen einer Gerätefamilie für das Ziel

Im Folgenden finden Sie einige Überlegungen, die Ihnen bei der Entscheidung helfen, welche Gerätefamilie als Ziel verwendet werden soll. Weitere Informationen finden Sie unter TargetDeviceFamily.

Maximieren der Reichweite Ihrer App

Um die maximale Anzahl von Gerätetypen mit Ihrer App zu erreichen und damit sie auf so vielen Geräten wie möglich ausgeführt werden kann, sollte Ihre App auf die Universelle Gerätefamilie ausgerichtet sein. Insbesondere, wie wir gesehen haben, werden Sie eine Reihe von Versionen der Universellen Gerätefamilie als Ziel verwenden.

Beschränken Ihrer App auf eine Art von Gerät

Möglicherweise möchten Sie nicht, dass Ihre App auf einer Vielzahl von Geräteformfaktoren ausgeführt wird. Vielleicht ist es für einen Desktop-PC oder für eine Xbox-Konsole spezialisiert. In diesem Fall können Sie eine der untergeordneten Gerätefamilien als Ziel auswählen.

Beschränken Sie Ihre App auf eine Teilmenge aller möglichen Geräte.

Anstatt die Universelle Gerätefamilie oder eine der untergeordneten Gerätefamilien als Ziel zu verwenden, können Sie stattdessen zwei (oder mehr) untergeordnete Gerätefamilien als Ziel verwenden. Die Ausrichtung auf Desktop und Mobile kann für Ihre App sinnvoll sein. Oder Desktop und Team. Oder Desktop, Mobile und Team usw.

Ausschließen der Unterstützung für eine bestimmte Version einer Gerätefamilie

In seltenen Fällen möchten Sie möglicherweise, dass Ihre App überall ausgeführt wird , außer auf Geräten mit einer bestimmten Version einer bestimmten Gerätefamilie. Angenommen, Ihre App ist auf Version 10.0.x.0 der universellen Gerätefamilie ausgerichtet. Wenn sich die Betriebssystemversion in Zukunft ändert ( z. B. 10.0.x.2), können Sie an diesem Punkt angeben, dass Ihre App überall außer Version 10.0.x.1 von Xbox ausgeführt wird, indem Sie Ihre App auf 10.0.x.0 von Universal und 10.0.x.2 von Xbox ausrichten. Ihre App ist dann für die Gruppe von Gerätefamilienversionen innerhalb von Xbox 10.0.x.1 (einschließlich) und älteren Versionen nicht mehr verfügbar.

Schreiben von Code

Ein Großteil Ihres Codes ist in dem Sinne universell, dass er auf jedem Gerät auf die gleiche Weise ausgeführt wird. Für Code, der auf eine bestimmte Gerätefamilie zugeschnitten ist, haben Sie jedoch die Möglichkeit, adaptiven Code zu verwenden. Betrachten wir diese verschiedenen Fälle.

Aufrufen einer API, die von Ihrer Zielgerätefamilie implementiert wird

Wenn Sie eine API in einer UWP-App aufrufen möchten, sollten Sie wissen, ob die API von der Gerätefamilie implementiert wird, auf die Ihre App abzielt. Visual Studio IntelliSense zeigt ihnen die APIs in der Universellen Gerätefamilie sowie die APIs an, die für alle Erweiterungs-SDK verfügbar sind, auf die Sie verwiesen haben.

In der Windows-Runtime-API-Referenzdokumentation erfahren Sie, zu welcher Gerätefamilie eine API gehört. Wenn Sie das API-Referenzthema für eine Windows-Runtime-API nachschlagen und nach dem Abschnitt Windows 10 Anforderungen suchen, sehen Sie, was die implementierenden Gerätefamilie ist und in welcher Version dieser Gerätefamilie die API zuerst angezeigt wird. Wenn kein Windows 10 Anforderungsabschnitt vorhanden ist, sehen Sie sich die besitzereigene Klasse des Members an, und sehen Sie sich dort die Informationen im Abschnitt Windows 10 Anforderungen an. Diese Informationen gelten auch für das Mitglied.

Aufrufen einer API, die nicht von Ihrer Zielgerätefamilie implementiert ist

Es gibt Fälle, in denen Sie eine API in einem Erweiterungs-SDK aufrufen möchten, auf das Sie verwiesen haben, aber diese API ist nicht Teil der Gerätefamilie, auf die Sie abzielen.

Beispielsweise können Sie die Universelle Gerätefamilie als Ziel verwenden, aber es gibt eine Desktop-API, die Sie aufrufen möchten, wenn Ihre App auf einem Desktopgerät ausgeführt wird.

Oder Ihre App unterstützt möglicherweise frühe Versionen einer Gerätefamilie, aber es gibt eine API, die Sie aufrufen möchten, die nur in sehr aktuellen Versionen derselben Gerätefamilie verfügbar ist.

In solchen Fällen können Sie adaptiven Code schreiben, damit Sie diese APIs sicher aufrufen können. Im nächsten Abschnitt erfahren Sie, wie das geht.

Schreiben von adaptivem Code mithilfe von ApiInformation

Bei der Verwendung von adaptivem Code zum bedingten Aufrufen einer API sind zwei Schritte erforderlich. Der erste Schritt besteht darin, die API für Ihr Projekt verfügbar zu machen. Fügen Sie dazu einen Verweis auf das Erweiterungs-SDK hinzu, das die Gerätefamilie darstellt, die die API besitzt.

Der zweite Schritt besteht darin, die ApiInformation-Klasse in einer Bedingung in Ihrem Code zu verwenden, um zu testen, ob die API vorhanden ist, die Sie aufrufen möchten. Diese Bedingung wird unabhängig davon ausgewertet, wo und wann Ihre App ausgeführt wird. Es wird jedoch nur auf Geräten ausgewertet true , auf denen die API vorhanden und daher aufgerufen werden kann.

Wenn Sie nur eine kleine Anzahl von APIs aufrufen möchten, können Sie die ApiInformation.IsTypePresent-Methode wie folgt verwenden.

// 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;
}

In diesem Fall besteht die Gewissheit, dass das Vorhandensein der HardwareButtons-Klasse das Vorhandensein des CameraPressed-Ereignisses impliziert, da die Klasse und der Member die gleichen Anforderungsinformationen aufweisen. Mit der Zeit werden jedoch neue Member zu bereits eingeführten Klassen hinzugefügt, und diese Member werden später in Versionsnummern eingeführt . In diesen Fällen können Sie mithilfe von Methoden wie IsEventPresent, IsMethodPresent, IsPropertyPresent und ähnlichen Methoden testen, ob die einzelnen Member vorhanden sind, anstatt IsTypePresent zu verwenden. Hier sehen Sie ein Beispiel.

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

Wie wir wissen, wird der Satz von APIs innerhalb einer Gerätefamilie weiter in Unterteilungen unterteilt, die als API-Verträge bezeichnet werden. Sie können die ApiInformation.IsApiContractPresent-Methode verwenden, um zu testen, ob ein API-Vertrag vorhanden ist. Dies ist eine effiziente Möglichkeit, eine einzelne Bedingung auszuführen, um das Vorhandensein oder anderweitige Vorhandensein einer großen Anzahl von APIs zu erfahren, die alle zu derselben Version eines API-Vertrags gehören.

Informationen dazu, wie Sie den API-Vertrag bestimmen, der zuerst die interessanten APIs eingeführt hat, finden Sie weiter oben in diesem Thema im Abschnitt Suchen des API-Vertrags für eine WinRT-API .

Sobald Sie über diese Informationen verfügen, können Sie sie in Ihren adaptiven Code einfügen. Wenn beispielsweise der Name des API-Vertrags lautet Windows.Devices.Scanners.ScannerDeviceContractund die Haupt- und Nebenversionsnummern 1 bzw. 0 sind, sieht Ihre Bedingung wie im folgenden Beispiel aus.

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

Vorschau der Benutzeroberfläche auf verschiedenen Bildschirmgrößen

Es wird empfohlen, die Reichweite Ihrer App zu maximieren. Aber auch wenn Sie nur einen Geräteformfaktor als Ziel verwenden, gibt es wahrscheinlich immer noch unterschiedliche Bildschirmgrößen, auf denen Ihre App angezeigt wird.

Wenn Sie sehen möchten, wie Ihre App auf einer bestimmten Bildschirmgröße aussieht und aussieht, verwenden Sie die Symbolleiste für die Gerätevorschau in Visual Studio, um eine Vorschau Ihrer Benutzeroberfläche auf einem kleinen oder mittleren mobilen Gerät, auf einem PC oder auf einem großen TV-Bildschirm anzuzeigen. Wenn Sie die adaptiven Layoutfeatures von XAML verwendet haben (siehe Adaptive Layouts mit visuellen Zuständen und Zustandstriggern), können Sie dies auch testen.

Geräte-Vorschauleiste in Visual Studio 2015

Sie müssen nicht im Voraus eine Entscheidung über jeden Gerätetyp treffen, den Sie unterstützen. Sie können Ihrem Projekt jederzeit eine zusätzliche Gerätegröße hinzufügen.