應用程式運行時間版本、sysroots 和 Beta API

發行項
04/03/2024

Azure 球體 SDK 發行可能同時包含生產 API 和 Beta API。生產 API 被視為長期穩定的 (LTS) ，而 Beta API 仍在開發中，可能會在後續版本中變更或移除。在大多數情況下，新 API 會在第一個版本中標示為 Beta，並在後續版本中移至生產。 Beta API 可讓您提早存取新功能，在完成之前啟用前言和意見反應。使用 Beta API 的應用程式在日後的 Azure OS 和 SDK 版本之後通常會需要修改，才能繼續正確運作。

Beta 功能在檔中會標示為 BETA 功能 。每個 Azure 球體高層級應用程式都會指定它是否只針對生產 API 或生產 API 和 Beta API 進行指定。

目標 API 集、ARV 和 sysroots

目標 API 集會指出應用程式使用的 API：僅限生產 API 或生產 API，以及 Beta API。目標 API 集值是代表 ARV) (應用程式執行時間版本的整數，或 ARV 加上可識別 Beta API 版本的字串。數值只指定 ARV 中的生產 API，而「value+BetaNumber」則指定特定版本中的生產與 Beta API。例如，ARV 8 代表 21.01 版本，而 “8+Beta2101” 則指定 20.01 版本中的生產與 Beta API。未來版本將會新增其他ARV。

Azure 球體 SDK 會使用 sysroots 實作多個 API 集。 sysroot 會指定用來編譯和連結特定 API 集之應用程式的文檔庫、頁首檔案和工具。 sysroots 會安裝在 sysroots 子資料夾中的 Microsoft Azure 球體 SDK 目錄中。

設定或更新適用於高階應用程式的目標 API 集

如果您的應用程式是以 Azure 球體樣本為基礎，預設設定的目標 API 是樣本使用的 API 集。如果樣本只使用生產 API，則目標 API 集將設定為目前的 ARV 值。如果樣本同時使用目前版本的生產版和 Beta API，目標 API 集會是「value+BetaNumber」，以包含 Beta API。

如果您的應用程式不是以樣本為基礎，則必須在應用程式的組建指示中設定目標 API。

如果您已經建立應用程式，如果您為新的作業系統版本重建應用程式，您可能需要變更目標 API 集。如果應用程式使用 Beta API，您應該在目標 API 設定選項變更時更新它，這通常會在每個功能發行時發生。 Beta API 可能會直接從 Beta 狀態移到生產，產生新的 ARV，或者它們可能會變更並保留在 Beta 中。如果您更新使用 Beta 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 集，您可以將此變數設定為「最新 lts」，如果尚未設定。如果您的應用程式是以最新的 Beta API 集為目標，您可以將此變數設定為「最新 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 集和作業系統相容性

應用程式與 Azure 球體 OS 的相容性取決於建立應用程式的目標 API 集，以及作業系統版本支援的最新 ARV。下層應用程式或操作系統使用較舊的 ARV (，其數位) 較低，而上層應用程式或操作系統則使用較新的 ARV (具有較高的數位) 。下列各節說明每個可能案例的結果。

具有上層作業系統的下層應用程式

Azure 球體作業系統上層版本支援只使用生產 API 的現有下層影像。例如，使用目標 API 集 1 建置的應用程式在支援 ARV 2 的 Azure 球體作業系統上成功執行。因此，在雲端作業系統更新之後，您現有的已部署應用程式將會繼續正常運作。您可以在上層操作系統中側載或雲端部署的僅限生產層級影像，而不會發生錯誤。

在 Azure 球體 OS 的上層版本上，不支援使用 Beta API 的下層影像，而且可能無法依設計運作。例如，使用目標 API Set 1+Beta1902 建置的應用程式在具有 ARV 2 的 Azure 球體作業系統上可能無法執行。除非您使用 azsphere 裝置側載部署命令上的標幟，--force否則嘗試側載這類影像會傳回錯誤。同樣地， azsphere 圖像新增 命令需要 --force 旗標才能上傳這類影像。目前沒有目前的檢查會防止先前上傳的使用 Beta API 的下層影像與不再支持這些 Beta API 的上層作業系統一起部署。

具有下層操作系統之上層應用程式

無論上層應用程式是否使用 Beta API，都無法部署到 Azure 球體 OS 的下層版本。嘗試側載這類影像時會發生錯誤。目前無法嘗試透過空中部署，因為上層 SDK 和作業系統會同時發行。

共用方式為