Use Beta API features

An Azure Sphere SDK release may contain both production APIs and Beta APIs. Beta APIs are still in development and may change in or be removed from a later release. In most cases, new APIs are marked Beta in their first release and moved to production in a subsequent release. Beta APIs provide early access to new features, enabling prototyping and feedback before they are finalized. Applications that use Beta APIs will generally require modifications after future Azure OS and SDK releases to continue to work correctly.

Beta features are labeled BETA feature in the documentation. Every Azure Sphere high-level application specifies whether it targets only production APIs or both production and Beta APIs.

Target API sets, ARV, and sysroots

The target API set indicates which APIs the application uses: either production APIs only or production and Beta APIs. The Target API Set value is either an integer that represents the application runtime version (ARV) or the ARV plus a string that identifies the Beta API release. At the 19.05 release, the ARV was incremented from 1 to 2, and at the 19.09 release it was increased again to 3. The numeric value alone specifies only the production APIs in the ARV, whereas the "value+BetaNumber" specifies the production and Beta APIs in a particular release. For example, ARV 2 indicates the 19.05 release, and "2+Beta1905" specifies the production and Beta APIs in the 19.05 release.

The Azure Sphere SDK implements multiple API sets by using sysroots. A sysroot specifies the libraries, header files, and tools that are used to compile and link an application that targets a particular API set. The sysroots are installed in the Microsoft Azure Sphere SDK directory in the sysroots subfolder.

Develop applications that use Beta APIs

If you start with an Azure Sphere sample that uses a Beta API, the Target API Set by default is set to the production and Beta APIs for the current release.

If you do not base your application on one of the samples, or if you base it on a sample that uses only production APIs, follow these steps to use Beta APIs.

Use Beta APIs in a Visual Studio project

To set the target API set in a Visual Studio project, set the Project Properties.

  1. Open the Azure Sphere project in Visual Studio.

  2. On the Project menu, select Project Properties...

  3. Ensure that the Configuration is set to either All Configurations or Active (Debug).

  4. In the list of General properties, select Target API Set.

  5. In the drop-down menu, select the target API set and then click OK.

    Project Property Page

Use Beta APIs in a CMake project

To set the target API set in a CMake project, update AzureSphereTargetApiSet in CMakeSettings.json. The easiest way to do this is to edit the JSON file directly and change the following field:

"AzureSphereTargetApiSet": API-set

Replace API-set with the required ARV value: either an integer or an integer plus a string. For example, to target the production and Beta APIs in the 19.09 release, you would update the JSON as follows:

      "AzureSphereTargetApiSet": "3+Beta1909"

Update applications that use Beta APIs

If you've already created an application that uses Beta APIs, you should update it when the Target API Set options change, which typically occurs at each feature release. Beta APIs may be moved directly from Beta status to production, resulting in a new ARV, or they might be changed and remain in Beta. If you update an application that uses Beta APIs to target a more recent target API set, you may encounter errors or warnings about removed or deprecated APIs.

Beta APIs and OS compatibility

The compatibility of an application with the Azure Sphere OS depends on the target API set with which the application was built and the latest ARV that the OS version supports. A down-level application or OS uses an older ARV (which has a lower number), and an up-level application or OS uses a more recent ARV (which has a higher number). The following sections describe what to expect in each possible scenario.

Down-level applications with up-level OS

Existing down-level images that use only production APIs are guaranteed to work successfully with up-level versions of the Azure Sphere OS. For example, an application that was built with Target API Set 1 runs successfully on an Azure Sphere OS that supports ARV 2. Thus, your existing deployed applications will continue to operate properly after cloud OS updates. You can either sideload or cloud-deploy down-level, production-only images to an up-level OS without error.

Down-level images that use Beta APIs are not guaranteed to work successfully with up-level versions of the Azure Sphere OS. For example, an application that was built with Target API Set 1+Beta1902 might fail to run on an Azure Sphere OS that has ARV 2. Attempts to sideload such an image return an error unless you use the --force flag on the azure sphere device sideload deploy command. Similarly, the azsphere device-group deployment create command requires the --force flag to upload such an image. No current checks subsequently prevent a previously uploaded down-level image that uses Beta APIs from being deployed alongside an up-level OS that no longer supports those Beta APIs.

Up-level applications with down-level OS

Up-level applications cannot be deployed to down-level versions of the Azure Sphere OS, regardless of whether they use Beta APIs. Attempts to sideload such an image will fail with an error. Attempts to deploy over-the-air are not currently possible because the up-level SDK and OS are released simultaneously.