Azure Sphere SDK リリースには、運用 API とベータ API の両方が含まれている場合があります。 運用 API は長期的に安定した (LTS) と見なされますが、ベータ API はまだ開発中であり、後のリリースで変更されたり、削除されたりする可能性があります。 ほとんどの場合、新しい API は最初のリリースでベータ版としてマークされ、後続のリリースで運用環境に移行されます。 ベータ API を使用すると、新機能に早期にアクセスできるため、プロトタイプの作成とフィードバックが最終処理される前に可能になります。 ベータ API を使用するアプリケーションでは、通常、OS と SDK の今後のリリースAzure後も正しく動作し続けるために変更が必要になります。
ベータ機能には、ドキュメントの BETA 機能 というラベルが付けられます。 すべてのAzure Sphere高レベルアプリケーションでは、運用 API のみを対象とするか、運用 API とベータ API の両方を対象にするかを指定します。
ターゲット API セット、ARV、および sysroot
ターゲット API セットは、アプリケーションが使用する API (運用 API のみまたは運用 API とベータ API) を示します。 ターゲット API の設定値は、アプリケーション ランタイム バージョン (ARV) を表す整数か、ARV にベータ API リリースを識別する文字列を加えた整数です。 数値のみでは ARV の運用 API のみを指定し、"value+BetaNumber" は特定のリリースの運用 API とベータ API を指定します。 たとえば、ARV 8 は 21.01 リリースを示し、"8+ Beta2101" は 20.01 リリースの運用 API とベータ API を指定します。 今後のリリースでは、ARV が追加される予定です。
Azure Sphere SDK は、sysroots を使用して複数の API セットを実装します。 sysroot は、特定の API セットを対象とするアプリケーションのコンパイルとリンクに使用されるライブラリ、ヘッダー ファイル、およびツールを指定します。 sysroots は、sysroots サブフォルダーの Microsoft Azure Sphere SDK ディレクトリにインストールされます。
高度なアプリのターゲット API セットを設定または更新する
Azure Sphere サンプルに基づいてアプリケーションを作成する場合、既定で設定されるターゲット API は、サンプルが使用する API セットです。 サンプルで運用 API のみを使用している場合、ターゲット API セットは現在の ARV 値に設定されます。 サンプルで現在のリリースで運用 API とベータ API の両方を使用している場合、ターゲット API セットは "value+BetaNumber" になり、ベータ API が含まれます。
サンプルに基づいてアプリケーションを作成しない場合は、アプリのビルド手順でターゲット API セットを設定する必要があります。
アプリケーションを既に作成している場合は、新しい OS リリース用にアプリをリビルドする場合に、ターゲット API セットの変更が必要になる場合があります。 アプリでベータ API を使用する場合は、ターゲット API セットのオプションが変更されたときに更新する必要があります。これは通常、各機能リリースで発生します。 ベータ API は、ベータ状態から運用環境に直接移動され、新しい ARV が発生する場合や、変更されてベータ版のままになる場合があります。 ベータ API を使用するアプリケーションを更新して、より新しいターゲット API セットをターゲットにすると、削除または廃止された API に関するエラーや警告が発生する可能性があります。
ターゲット API セットを変更するたびに、アプリケーションをビルドする前に、CMakeCache.txt ファイルを削除する必要があります。 このファイルは、プロジェクトの out\ARM-Debug または out\ARM-Release ディレクトリに格納されます。
ターゲット API セットを指定する
CMakePresets.jsonでターゲット API セットを設定します。
"AZURE_SPHERE_TARGET_API_SET" を使用して、ターゲット API セットを構成します。 例えば次が挙げられます。
"AZURE_SPHERE_TARGET_API_SET": "5"または"AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"
アプリが最新の API セットを対象とする場合は、この変数を "latest-lts" に設定できます (まだ設定していない場合)。 アプリが最新のベータ API セットを対象とする場合は、この変数を "latest-beta" に設定できます (まだ設定していない場合)。 ただし、アプリが古い API セットを対象とする場合は、使用する特定の値と一致するようにこの変数を設定する必要があります。
Visual Studio プロジェクトで外部AZURE_SPHERE_TARGET_API_SET変数を指定するには、ARM-Debug 構成と ARM-Release 構成の両方で、CMakeSettings.json ファイルで次のように設定します。
"variables": [ { "name": "AZURE_SPHERE_TARGET_API_SET", "value": "latest-beta" } ]Visual Studio Code プロジェクトで外部AZURE_SPHERE_TARGET_API_SET変数を指定するには、.vscode/settings.json ファイルで次のように設定します。
"cmake.configureSettings": { "AZURE_SPHERE_TARGET_API_SET": "latest-lts" },コマンド ラインで外部AZURE_SPHERE_TARGET_API_SET変数を指定するには、CMake を呼び出すときにパラメーターを含めます。
-DAZURE_SPHERE_TARGET_API_SET="latest-lts"前に説明したように、"latest-lts" を "latest-beta" または "4" や "5+Beta2004" などの特定の古い値に置き換えます。
ターゲット API セットと OS の互換性
Azure Sphere OS とのアプリケーションの互換性は、アプリケーションがビルドされたターゲット API セットと、OS バージョンがサポートする最新の ARV によって異なります。 下位レベルのアプリケーションまたは OS では古い ARV (数値が小さい) が使用され、上位レベルのアプリケーションまたは OS では、より新しい ARV (より高い数値を持つ) が使用されます。 次のセクションでは、考えられる各シナリオで想定される内容について説明します。
上位レベルの OS を使用する下位レベルのアプリケーション
実稼働 API のみを使用する既存の下位レベルのイメージは、Azure Sphere OS のアップレベル バージョンでサポートされています。 たとえば、ターゲット API セット 1 でビルドされたアプリケーションは、ARV 2 をサポートするAzure Sphere OS で正常に実行されます。 そのため、既存のデプロイ済みアプリケーションは、クラウド OS の更新後も引き続き正常に動作します。 ダウンレベルの実稼働専用イメージを、エラーなしで上位 OS にサイドロードまたはクラウドデプロイできます。
ベータ API を使用する下位レベルのイメージは、Azure Sphere OS の上位バージョンではサポートされておらず、設計上は機能しない可能性があります。 たとえば、ターゲット API セット 1 + Beta1902 を使用してビルドされたアプリケーションは、ARV 2 を持つAzure Sphere OS で実行できない場合があります。
--force
コマンドで フラグを使用しない限り、このようなイメージをサイドロードしようとするとエラーが返されます。 同様に、 az sphere image add コマンドでは、そのようなイメージをアップロードするために --force フラグが必要です。 現在のチェックでは、ベータ API を使用する以前にアップロードされた下位レベルのイメージが、それらのベータ API をサポートしなくなった上位レベルの OS と共にデプロイされるのを防ぐ必要はありません。
下位レベルの OS を使用する上位レベルのアプリケーション
上位レベルのアプリケーションは、ベータ API を使用しているかどうかに関係なく、Azure Sphere OS の下位バージョンに展開することはできません。 このようなイメージをサイドロードしようとすると、エラーが発生して失敗します。 アップレベルの SDK と OS が同時にリリースされるため、現在、オンプレミスでデプロイを試みることはできません。