Programmieren mit Erweiterungs-SDKs

Um zu verstehen, wie Windows 10 Ihre Universelle Windows-Plattform -App (UWP) am effektivsten auf verschiedene Geräteklassen ausgerichtet ist, erläutert dieses Thema die folgenden Konzepte.

  • Gerätefamilie
  • Erweiterungs-SDK
  • API-Vertrag

Wir zeigen auch, wie sie in Ihrer Programmierung verwendet werden.

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 (Betriebssystem). Beispielsweise führen PCs und Tablets eine Desktop-Edition des Betriebssystems aus, und dies basiert auf der Desktopgerätefamilie. 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 daher auf jedem Gerät, auf dem dieses Betriebssystem ausgeführt wird.

Die Entscheidung darüber, welche Gerätefamilie (oder Familien) Ihre App angibt , ist Ihre Entscheidung. Und diese Entscheidung wirkt sich folgendermaßen auf Ihre App aus. Es bestimmt

  • die Familien von Geräten, die Ihre App zum Installieren aus dem Microsoft Store angeboten wird (und folglich die Formfaktoren, die Sie berücksichtigen müssen, wenn Sie die Benutzeroberfläche Ihrer App entwerfen) und
  • die bestimmte Gruppe von APIs, auf die Sie sich verlassen können, auf einem Gerät, auf dem Ihre App ausgeführt wird (das Hostgerät).

Wenn sie vorhanden sind, bedeutet dies, dass Sie diese APIs aufrufen können, ohne zuerst zu testen, ob sie auf dem Hostgerät vorhanden sind. Die Gerätefamilie, die Sie als Ziel festlegen, bietet diese Garantie (unterschiedliche Garantien für verschiedene Gerätefamilien).

Konfigurieren Ihrer Zielgerätefamilie

In der Quelldatei für das App-Paketmanifest (die Package.appxmanifest Datei) weist das TargetDeviceFamily-Element ein Name-Attribut auf. 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 (also Microsoft Visual Studio gibt Windows.Universal für TargetDeviceFamily an). Das bedeutet, dass Ihre App auf allen Windows 10 Geräten installiert werden kann und dass Sie sich auf einen großen Kernsatz von APIs verlassen können, die auf dem Hostgerät vorhanden sind. Eine App wie dies eine hochgradig adaptive Benutzeroberfläche und umfassende Eingabefunktionen benötigt, da sie auf einer Vielzahl von Geräten ausgeführt werden kann. Weitere Informationen finden Sie in der Vorschau ihrer Benutzeroberfläche auf verschiedenen Bildschirmgrößen weiter unten in diesem Thema.

Wenn Sie die Gerätefamilien einschränken möchten, die Ihre App für die Installation aus dem Microsoft Store angeboten wird, können Sie eine andere Gerätefamilie auswählen, z. B. die Desktopgerätefamilie () oder die IoT-Gerätefamilie (Windows.DesktopWindows.IoT). Natürlich gibt es weniger Geräte, die Ihre App hosten können, aber Sie können sich auf eine größere Gruppe von APIs verlassen, die auf diesen Geräten vorhanden sind (das ist der Satz in der universellen Gerätefamilie sowie der Satz in der Zielgerätefamilie). Eine App wie dies in der Regel nur moderat adaptive sein muss; es kann etwas spezialisiert auf seine UI- und Eingabefunktionen sein, da es nur auf einer bestimmten Art von Gerät ausgeführt werden kann.

Tipp

Aber Sie können 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. Dieses Szenario der besten beiden Welten erfordert ein wenig zusätzliche Arbeit, und wir werden die Besonderheiten dieses Szenarios später in diesem Thema durchlaufen.

Konfigurieren ihrer Zielgerätefamilienversion

APIs werden im Laufe der Zeit zu Windows hinzugefügt, sodass eine andere Dimension zum Auswählen einer Gerätefamilie entscheidet, welche Version (oder Versionen) zielt. Einige Projekttypen in Visual Studio verfügen über eine Eigenschaftenseite, auf der Sie Ihre Zielplattformversionen konfigurieren können. Aber für alle Projekttypen können Sie Ihre Zielplattformversionen direkt in der Projektdatei konfigurieren.

Hier sehen Sie ein Beispiel, in dem die relevanten Eigenschaften in einer Projektdatei angezeigt werden.

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

Zur Erstellungszeit werden diese Werte (zusammen mit dem Wert von TargetDeviceFamily@Name aus 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, auf die Ihre App ausgerichtet ist, für die Sie sie getestet haben. Und MinVersion gibt die Mindestversion der Gerätefamilie an, auf die Ihre App ausgerichtet ist. Weitere Informationen finden Sie unter TargetDeviceFamily.

Wichtig

Sie sollten diese Versionsnummern mithilfe der Eigenschaftenseiten Ihres Visual Studio-Projekts oder die Werte von WindowsTargetPlatformVersion und WindowsTargetPlatformMinVersion in Ihrer Projektdatei konfigurieren. Bearbeiten AppxManifest.xmlSie diese Datei nicht, da der Build diese Datei überschreibt. 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 Sie darauf verweisen

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. Dies macht die APIs in dieser Gerätefamilie für Ihr Projekt verfügbar.

Wenn Sie z. B. auf die IoT-Gerätefamilie abzielen, klicken Sie (mit dem in Projektmappen-Explorer ausgewählten Projektknoten) auf Project>Add Reference...>Universelle Windows-Geräte>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 dies ist, wie dieser Verweis in Ihrer Projektdatei aussehen würde.

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

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

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

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

Wenn Sie Ihre App für die Universelle Gerätefamilie verlassen, können Sie weiterhin einen Verweis auf eine 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 auf die universelle Gerätefamilie abzielen, sodass dies die einzigen APIs sind, auf die Sie sich verlassen können. Bei APIs im Erweiterungs-SDK(n), 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 ausführen. Dies ist das beste von beiden Welten szenario, das wir im vorherigen Abschnitt erwähnt haben.

Mithilfe eines Erweiterungs-SDK können Sie auf die eindeutigen APIs einer bestimmten Gerätefamilie abzielen und dadurch auf ihre speziellen Funktionen zugreifen. Sie können dies tun, ob Sie auf die entsprechende Gerätefamilie abzielen oder nicht.

API-Verträge und wie sie nachschlagen

Die APIs in einer Gerätefamilie werden 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 war der benannte Windows.Foundation.UniversalApiContract API-Vertrag bei Version 6.0, als er mit Version 10.0.17134.0 der Universellen Gerätefamilie ausgeliefert wurde. Dieser Vertrag war jedoch bei Version 10.0, als er mit Version 10.0.19041.0 der gleichen Gerätefamilie ausgeliefert wurde.

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

Sehen wir uns an, wie Sie den API-Vertragsnamen und die Versionsnummer für eine beliebige Windows-Runtime-API nachschlagen 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 können wir sehen, dass StorageFolder.TryGetChangeTracker mit Version 6.0 Windows.Foundation.UniversalApiContractvon .

Als Nächstes sehen wir uns das Thema für die StorageFolder.TryGetItemAsync-Methode an. In diesem Thema gibt es keinen abschnitt Windows 10 Anforderungen. Schauen Sie sich stattdessen das Thema für die StorageFolder-Klasse selbst an. Der Abschnitt "Windows 10 Anforderungen" enthält die Antwort. Da das Thema "StorageFolder.TryGetItemAsync " nicht anders sagt, können wir schließen, dass es seine Anforderungen mit seiner übergeordneten Klasse teilt. So StorageFolder.TryGetItemAsync wurde erstmals mit Version 1.0 von Windows.Foundation.UniversalApiContract.

So wählen Sie eine Gerätefamilie aus, auf die sie ausgerichtet werden soll

Hier sind einige Überlegungen, die Ihnen helfen, zu entscheiden, welche Gerätefamilie zielführen soll. Weitere Informationen finden Sie unter TargetDeviceFamily.

Maximieren der Reichweite Ihrer App

Um den maximalen Bereich von Geräten mit Ihrer App zu erreichen und daher so viele Geräte wie möglich auszuführen, sollte Ihre App auf die universelle Gerätefamilie ausgerichtet sein. Wie wir gesehen haben, werden Sie auf eine Reihe von Versionen der Universellen Gerätefamilie abzielen.

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 auf einen Desktop-PC oder auf eine Xbox-Konsole spezialisiert. In diesem Fall können Sie eine der untergeordneten Gerätefamilien auswählen.

Beschränken Ihrer App auf eine Teilmenge aller möglichen Geräte

Anstatt auf die universelle Gerätefamilie oder auf eine der untergeordneten Gerätefamilien zu abzielen, können Sie stattdessen zwei (oder mehr) untergeordnete Gerätefamilien verwenden. Die Ausrichtung von 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, dass Ihre App überall ausgeführt werden soll, außer auf Geräten mit einer bestimmten Version einer bestimmten Gerätefamilie. Angenommen, Ihre App zielt auf Version 10.0.x.0 der universellen Gerätefamilie ab. Wenn sich die Betriebssystemversion in Zukunft ändert – z. B. 10.0.x.2 – können Sie angeben, dass Ihre App überall ausgeführt wird, außer Version 10.0.x.1 von Xbox, 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 Des Codes ist universell, sodass er auf jedem Gerät auf dieselbe 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

Wann immer Sie eine API in einer UWP-App aufrufen möchten, möchten Sie wissen, ob die API von der Gerätefamilie implementiert wird, auf die Ihre App ausgerichtet ist. Visual Studio IntelliSense zeigt die APIs in der universellen Gerätefamilie sowie die APIs, auf die sie für alle Erweiterungs-SDK(n) verfügbar sind, auf die Sie verwiesen haben.

Die Windows-Runtime API-Referenzdokumentation informiert Sie darüber, welche Gerätefamilie eine API Teil ist. Wenn Sie das API-Referenzthema für eine Windows-Runtime-API nachschlagen und nach dem Abschnitt Windows 10 Anforderungen suchen, sehen Sie, was die Implementierungsgerätefamilie ist, und in welcher Version dieser Gerätefamilie die API zuerst angezeigt wird. Wenn kein Windows 10 Anforderungsabschnitt vorhanden ist, schauen Sie sich die eigene Klasse des Mitglieds an, und sehen Sie sich die Informationen im Abschnitt Windows 10 Anforderungen dort 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.

Sie können beispielsweise auf die universelle Gerätefamilie abzielen, 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 Fällen wie diesen können Sie adaptiven Code schreiben, damit Sie diese APIs sicher aufrufen können. Der nächste Abschnitt zeigt Ihnen, wie.

Schreiben von adaptivem Code mithilfe von ApiInformation

Es gibt zwei Schritte, die daran beteiligt sind, adaptiven Code zum bedingten Aufrufen einer API zu verwenden. 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 die Anwesenheit der API zu testen, die Sie aufrufen möchten. Diese Bedingung wird überall und immer dann ausgewertet, wenn Ihre App ausgeführt wird. Es wird true jedoch nur auf Geräten ausgewertet, auf denen die API vorhanden ist und daher aufrufbar ist.

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 das Vertrauen, dass die Anwesenheit der HardwareButtons-Klasse das Vorhandensein des CameraPressed-Ereignisses impliziert, da die Klasse und das Mitglied dieselben Anforderungen haben. Aber in der Zeit werden neue Mitglieder zu bereits eingeführten Klassen hinzugefügt, und diese Mitglieder 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 in 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 über die Anwesenheit oder anderweitig eine große Anzahl von APIs zu erfahren, die alle zur gleichen Version eines API-Vertrags gehören.

Informationen zum Ermitteln des API-Vertrags, der die API(en) von Interesse eingeführt hat, finden Sie im Abschnitt " Nachschlagen des API-Vertrags für einen WinRT-API-Abschnitt weiter oben in diesem Thema".

Sobald Sie über diese Informationen verfügen, können Sie sie in Ihren adaptiven Code einfügen. Wenn der Name des API-Vertrags beispielsweise lautet Windows.Devices.Scanners.ScannerDeviceContractund die Haupt- und Nebenversionsnummern 1 und 0 bzw. 0 sind, sieht ihre Bedingung wie das folgende 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. Selbst wenn Sie jedoch nur auf eine Art von Geräteformfaktor abzielen, gibt es wahrscheinlich noch unterschiedliche Bildschirmgrößen, auf denen Ihre App angezeigt werden könnte.

Wenn Sie bereit sind, zu sehen, wie Ihre App aussieht und auf einer bestimmten Bildschirmgröße auslegt, 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 FERNSEHbildschirm anzuzeigen. Wenn Sie die adaptiven Layoutfeatures von XAML verwendet haben (siehe Lernprogramm: Erstellen adaptiver Layouts), können Sie dies auch testen.

Geräte-Vorschauleiste in Visual Studio 2015

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

Siehe auch