Version der Anwendungsruntime, Sysroots und Beta-APIs

Artikel
11/05/2024

Wichtig

Dies ist die Dokumentation zu Azure Sphere (Legacy). Azure Sphere (Legacy) wird am 27. September 2027 eingestellt, und Benutzer müssen bis zu diesem Zeitpunkt zu Azure Sphere (integriert) migrieren. Verwenden Sie die Versionsauswahl oberhalb des Inhaltsverzeichniss, um die Dokumentation zu Azure Sphere (Integriert) anzuzeigen.

Ein Azure Sphere SDK-Release kann sowohl Produktions-APIs als auch Beta-APIs enthalten. Produktions-APIs werden als langfristig stabil (Long-Term Stable, LTS) betrachtet, während sich Beta-APIs noch in der Entwicklungsphase befinden und in einem späteren Release geändert oder entfernt werden können. In den meisten Fällen sind neue APIs im ersten Release als „Beta“ gekennzeichnet und werden in einem nachfolgenden Release zu Produktions-APIs. Mit Beta-APIs erhalten Sie vorab Zugriff auf neue Features und können vor deren Fertigstellung Prototypen erstellen und Feedback senden. Für Anwendungen, die Beta-APIs verwenden, sind nach künftigen Releases für Betriebssysteme und SDKs von Azure im Allgemeinen Änderungen erforderlich, damit die Anwendungen weiterhin ordnungsgemäß funktionieren.

Betafeatures werden in der Dokumentation als BETA-Feature bezeichnet. Für jede allgemeine Azure Sphere-Anwendung wird angegeben, ob sie nur auf Produktions-APIs oder auch auf Beta-APIs ausgerichtet ist.

API-Zielsatz, Version der Anwendungsruntime und Systemstamm (sysroot)

Der API-Zielsatz gibt an, welche APIs von der Anwendung verwendet werden: nur Produktions-APIs oder Produktions- und Beta-APIs. Beim Wert des API-Zielsatzes handelt es sich entweder um einen Integerwert, der für die Version der Anwendungsruntime (Application Runtime Version, ARV) steht, oder um die ARV sowie eine mit einem Pluszeichen angeschlossene Zeichenfolge zur Angabe des Beta-API-Release. Der numerische Wert allein gibt nur die Produktions-APIs in der ARV an, während „Wert+Betaversion“ die Produktions- und Beta-APIs in einem bestimmten Release angibt. Beispielsweise gibt ARV 8 die Version 21.01 an, und "8+Beta2101" gibt die Produktions- und Beta-APIs in der Version 20.01 an. In zukünftigen Releases werden weitere ARVs hinzugefügt.

Das Azure Sphere SDK implementiert mithilfe von Sysroots mehrere API-Sätze. Ein Systemstamm (sysroot) dient zum Angeben der Bibliotheken, Headerdateien und Tools, die verwendet werden, um eine Anwendung zu kompilieren und mit einem bestimmten API-Satz zu verknüpfen. Die sysroot-Ordner werden im Microsoft Azure Sphere SDK-Verzeichnis im Unterordner „sysroots“ installiert.

Festlegen oder Aktualisieren des API-Zielsatzes für eine allgemeine App

Wenn Ihre Anwendung auf einem Azure Sphere-Beispiel basiert, wird als API-Zielsatz standardmäßig der API-Satz des Beispiels verwendet. Wenn in dem Beispiel nur Produktions-APIs verwendet werden, wird der API-Zielsatz auf den aktuellen ARV-Wert festgelegt. Wenn in dem Beispiel sowohl Produktions- als auch Beta-APIs für das aktuelle Release verwendet werden, wird als API-Zielsatz „Wert+Betanummer“ verwendet, um die Beta-APIs einzuschließen.

Wenn Ihre Anwendung nicht auf einem Beispiel basiert, muss der API-Zielsatz in den Erstellungsanweisungen für die App festgelegt werden.

Wenn Sie bereits eine Anwendung erstellt haben, müssen Sie bei der Neuerstellung für ein neues Betriebssystemrelease unter Umständen den API-Zielsatz ändern. Wenn die App Beta-APIs verwendet, müssen Sie sie aktualisieren, wenn sich die Optionen für den API-Zielsatz ändern (in der Regel bei jedem Featurerelease). Beta-APIs können direkt in den Produktionsstatus überführt werden, was eine neue ARV zur Folge hat. Sie können aber auch geändert werden und ihren Betastatus behalten. Wenn Sie eine Anwendung aktualisieren, die Beta-APIs verwendet, um auf einen neueren Ziel-API-Satz zu abzielen, treten möglicherweise Fehler oder Warnungen zu entfernten oder eingestellten APIs auf.

Bei jeder Änderung des API-Zielsatzes müssen Sie die Datei „CMakeCache.txt“ löschen, bevor Sie die Anwendung erstellen. Diese Datei ist in einem der Verzeichnisse „out\ARM-Debug“ oder „out\ARM-Release“ für Ihr Projekt gespeichert.

Angeben des API-Zielsatzes

Festlegen des Ziel-API-Satzes in CMakePresets.json:

Verwenden Sie "AZURE_SPHERE_TARGET_API_SET", um den Ziel-API-Satz zu konfigurieren. Zum Beispiel:

"AZURE_SPHERE_TARGET_API_SET": "5" oder "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Wenn Ihre App auf den neuesten API-Satz ausgerichtet ist, können Sie diese Variable einfach auf "latest-lts" festlegen, sofern sie noch nicht vorhanden ist. Wenn Ihre App auf den neuesten Beta-API-Satz abzielt, können Sie diese Variable einfach auf "latest-beta" festlegen, sofern sie noch nicht vorhanden ist. Wenn Ihre App jedoch auf einen älteren API-Satz abzielt, müssen Sie diese Variable so festlegen, dass sie dem verwendeten Wert entspricht.

Um die externe Variable AZURE_SPHERE_TARGET_API_SET in einem Visual Studio-Projekt anzugeben, legen Sie in der Datei „CMakeSettings.json“ innerhalb der Konfigurationen sowohl für „ARM-Debug“ als auch für „ARM-Release“ Folgendes fest:
```
"variables": [
  {
    "name": "AZURE_SPHERE_TARGET_API_SET",
    "value": "latest-beta"
  }
]
```
Um die externe Variable AZURE_SPHERE_TARGET_API_SET in einem Visual Studio Code-Projekt anzugeben, legen Sie in der Datei „.vscode/settings.json“ Folgendes fest:
```
    "cmake.configureSettings": {
      "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
  },
```
Um die externe Variable AZURE_SPHERE_TARGET_API_SET in der Befehlszeile anzugeben, schließen Sie den Parameter ein, wenn Sie CMake aufrufen:

-DAZURE_SPHERE_TARGET_API_SET="latest-lts"

Ersetzen Sie „latest-lts“ durch „latest-beta“ bzw. einen älteren Wert, wie etwa „4“ oder „5+Beta2004“, wie bereits erläutert.

API-Zielsätze und Betriebssystemkompatibilität

Die Kompatibilität einer Anwendung mit dem Azure Sphere-Betriebssystem hängt von dem API-Zielsatz ab, mit dem die Anwendung erstellt wurde, sowie von der neuesten ARV, die von der Betriebssystemversion unterstützt wird. Downlevel-Anwendungen und -Betriebssysteme verwenden eine ältere ARV (niedrigere Zahl). Uplevel-Anwendungen und Betriebssysteme verwenden eine neuere ARV (höhere Zahl). Im Anschluss werden die möglichen Szenarien beschrieben.

Downlevel-Anwendungen mit Uplevel-Betriebssystem

Vorhandene Downlevel-Images, die nur Produktions-APIs verwenden, werden für Uplevel-Versionen des Azure Sphere-Betriebssystems unterstützt. So kann beispielsweise eine Anwendung, die mit dem API-Zielsatz 1 erstellt wurde, problemlos unter einem Azure Sphere-Betriebssystem ausgeführt werden, das die ARV 2 unterstützt. Bereits vorhandene und bereitgestellte Anwendungen werden somit nach Updates für das Cloudbetriebssystem weiterhin ordnungsgemäß ausgeführt. Reine Downlevel-Produktionsimages können in einem Uplevel-Betriebssystem fehlerfrei genutzt werden – entweder mittels Querladen oder per Cloudbereitstellung.

Downlevel-Images, die Beta-APIs verwenden, werden nicht unterstützt und funktionieren unter Umständen entwurfsbedingt nicht mit Uplevel-Versionen des Azure Sphere-Betriebssystems. So kann beispielsweise eine Anwendung, die mit dem API-Zielsatz „1+Beta1902“ erstellt wurde, unter einem Azure Sphere-Betriebssystem mit ARV 2 unter Umständen nicht ausgeführt werden. Versuche, ein solches Image querzuladen, geben einen Fehler zurück, es sei denn, Sie verwenden das --force Flag auf dem Azsphere-Gerät querladen Bereitstellungsbefehl. Ebenso erfordert das Hinzufügen des Azsphere-Bildbefehls das --force Flag, um ein solches Bild hochzuladen. Aktuell gibt es keine Überprüfungen, die nachträglich verhindern, dass ein bereits hochgeladenes Downlevel-Image, das Beta-APIs verwendet, zusammen mit einem Uplevel-Betriebssystem bereitgestellt wird, das diese Beta-APIs nicht mehr unterstützt.

Uplevel-Anwendungen mit Downlevel-Betriebssystem

Uplevel-Anwendungen können unabhängig von der Verwendung von Beta-APIs nicht für Downlevel-Versionen des Azure Sphere-Betriebssystems bereitgestellt werden. Beim Versuch, ein solches Image querzuladen, tritt ein Fehler auf. Eine drahtlose Bereitstellung ist derzeit nicht möglich, da das Uplevel-SDK und das Uplevel-Betriebssystem gleichzeitig veröffentlicht werden.

Teilen über