Versione del runtime dell'applicazione, sysroot e API betaApplication runtime version, sysroots, and Beta APIs

Una versione di Azure Sphere SDK potrebbe contenere sia API di produzione che API beta.An Azure Sphere SDK release may contain both production APIs and Beta APIs. Le API di produzione sono considerate stabili a lungo termine (LTS), mentre le API beta sono ancora in fase di sviluppo e possono cambiare in una versione successiva o essere rimosse.Production APIs are considered long-term stable (LTS), whereas Beta APIs are still in development and may change in or be removed from a later release. Nella maggior parte dei casi, le nuove API sono contrassegnate come beta nella prima versione e passano in produzione in una versione successiva.In most cases, new APIs are marked Beta in their first release and moved to production in a subsequent release. Le API beta consentono di accedere in anteprima alle nuove funzionalità e quindi di creare prototipi e fornire commenti e suggerimenti prima che vengano finalizzate.Beta APIs provide early access to new features, enabling prototyping and feedback before they are finalized. Le applicazioni che usano le API beta richiederanno solitamente modifiche dopo la pubblicazione di versioni future del sistema operativo e dell'SDK di Azure Sphere per continuare a funzionare correttamente.Applications that use Beta APIs will generally require modifications after future Azure OS and SDK releases to continue to work correctly.

Le funzionalità beta sono etichettate come funzionalità beta nella documentazione.Beta features are labeled BETA feature in the documentation. Ogni applicazione di alto livello di Azure Sphere specifica se è destinata solo alle API di produzione o sia alle API di produzione che alle API beta.Every Azure Sphere high-level application specifies whether it targets only production APIs or both production and Beta APIs.

Set di API di destinazione, versione di runtime dell'applicazione e sysrootTarget API sets, ARV, and sysroots

Il set di API di destinazione indica quali API usa l'applicazione, ovvero solo le API di produzione oppure le API di produzione e beta.The target API set indicates which APIs the application uses: either production APIs only or production and Beta APIs. Il valore del set di API di destinazione è un intero che rappresenta la versione di runtime dell'applicazione oppure la versione di runtime dell'applicazione più una stringa che identifica la versione API beta.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. Nella versione 19.09 la versione di runtime dell'applicazione è stata incrementata da 2 a 3 e nella versione 20.01 è stata incrementata a 4.At the 19.09 release, the ARV was incremented from 2 to 3, and at the 20.01 release it was increased again to 4. Il valore numerico da solo specifica esclusivamente le API di produzione nella versione di runtime dell'applicazione, mentre "valore+BetaNumero" specifica le API di produzione e beta in una particolare release.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. Ad esempio, la versione di runtime dell'applicazione 4 indica la versione 20.01 e "4+Beta2001" specifica le API di produzione e beta nella versione 20.01.For example, ARV 4 indicates the 20.01 release, and "4+Beta2001" specifies the production and Beta APIs in the 20.01 release. Nelle versioni future verranno aggiunte altre versioni del runtime dell'applicazione.Future releases will add additional ARVs.

Azure Sphere SDK implementa più set di API tramite sysroot.The Azure Sphere SDK implements multiple API sets by using sysroots. Un sysroot specifica le librerie, i file di intestazione e gli strumenti usati per compilare e collegare un'applicazione destinata a uno specifico set di API.A sysroot specifies the libraries, header files, and tools that are used to compile and link an application that targets a particular API set. I sysroot vengono installati nella sottocartella sysroots della directory Microsoft Azure Sphere SDK.The sysroots are installed in the Microsoft Azure Sphere SDK directory in the sysroots subfolder.

Impostare o aggiornare il set di API di destinazione per un'app di alto livelloSet or update the target API set for a high-level app

Se l'applicazione è basata su un esempio di Azure Sphere, il set di API di destinazione per impostazione predefinita è quello usato dall'esempio.If you base your application on an Azure Sphere sample, the target API set by default is the API set that the sample uses. Se l'esempio usa solo le API di produzione, il set di API di destinazione verrà impostato sul valore ARV corrente.If the sample uses only production APIs, the target API set will be set to the current ARV value. Se l'esempio usa sia le API di produzione che beta per la versione corrente, il set di API di destinazione sarà "valore+NumeroBeta" per includere le API beta.If the sample uses both production and Beta APIs for the current release, the target API set will be "value+BetaNumber", to include the Beta APIs.

Se l'applicazione non è basata su un esempio, sarà necessario impostare il set di API di destinazione nelle istruzioni di compilazione per l'app.If you don't base your application on a sample, you'll need to set the target API set in the build instructions for the app.

Se è già stata creata un'applicazione, potrebbe essere necessario cambiare il set di API di destinazione se l'app viene ricompilata per una nuova versione del sistema operativo.If you've already created an application, you might need to change the target API set if you rebuild the app for a new OS release. Se l'app usa API beta, è necessario aggiornarla quando cambiano le opzioni del set di API di destinazione, cosa che si verifica in genere a ogni rilascio di funzionalità.If the app uses Beta APIs, you should update it when the target API set options change, which typically occurs at each feature release. Le API beta possono passare direttamente dallo stato beta a quello di produzione, determinando la creazione di una nuova versione di runtime dell'applicazione, oppure possono essere modificate e mantenute nello stato beta.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. Se si aggiorna un'applicazione che usa le API beta per specificare come destinazione un set di API di destinazione più recente, potrebbero essere visualizzati errori o avvisi relativi ad API rimosse o deprecate.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.

Ogni volta che si cambia il set di API di destinazione, è necessario eliminare il file CMakeCache.txt prima di compilare l'applicazione.Any time you change the target API set, you need to delete the CMakeCache.txt file before you build the application. Questo file è archiviato nella directory out\ARM-Debug o out\ARM-Release per il progetto.This file is stored in the out\ARM-Debug or out\ARM-Release directory for your project.

Specificare il set di API di destinazioneSpecify target API set

Impostare il set di API di destinazione nel file CMakeLists.txt:Set the target API set in CMakeLists.txt:

  • Usare azsphere_configure_tools per configurare la versione di Azure Sphere SDK Tools.Use azsphere_configure_tools to configure the Azure Sphere SDK Tools version. Ad esempio:For example:

    azsphere_configure_tools(TOOLS_REVISION "20.04")

  • Usare azsphere_configure_api per configurare il set di API di destinazione.Use azsphere_configure_api to configure the target API set. Ad esempio:For example:

    azsphere_configure_api(TARGET_API_SET "5") o azsphere_configure_api(TARGET_API_SET "5+Beta2004")azsphere_configure_api(TARGET_API_SET "5") or azsphere_configure_api(TARGET_API_SET "5+Beta2004")

Può anche essere necessario aggiornare la variabile esterna AZURE_SPHERE_TARGET_API_SET passata in CMake.You may also need to update the external AZURE_SPHERE_TARGET_API_SET variable that is passed into CMake. Se l'app è destinata al set di API più recente, è possibile impostare questa variabile su "latest-lts", se non lo è già.If your app targets the latest API set, you can just set this variable to "latest-lts" if it isn't already. Se l'app è destinata al set di API beta più recente, è possibile impostare questa variabile su "latest-beta", se non lo è già.If your app targets the latest Beta API Set, you can just set this variable to "latest-beta" if it isn't already. Tuttavia, se l'app è destinata a un set di API meno recente, è necessario impostare questa variabile in modo che corrisponda al valore specifico che usa.However, if your app targets an older API set, you need to set this variable to match the specific value it uses.

  • Per specificare la variabile esterna AZURE_SPHERE_TARGET_API_SET in un progetto di Visual Studio, impostare quanto segue nel file CMakeSettings.json, all'interno delle configurazioni ARM-Debug e ARM-Release:To specify the external AZURE_SPHERE_TARGET_API_SET variable in a Visual Studio project, set the following in the CMakeSettings.json file, within both the ARM-Debug and ARM-Release configurations:

    "variables": [
      {
        "name": "AZURE_SPHERE_TARGET_API_SET",
        "value": "latest-beta"
      }
    ]
    
  • Per specificare la variabile esterna AZURE_SPHERE_TARGET_API_SET in un progetto di Visual Studio Code, impostare quanto segue nel file .vscode/settings.json:To specify the external AZURE_SPHERE_TARGET_API_SET variable in a Visual Studio Code project, set the following in the .vscode/settings.json file:

        "cmake.configureSettings": {
          "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
      },
    
  • Per specificare la variabile esterna AZURE_SPHERE_TARGET_API_SET sulla riga di comando, includere il parametro quando si richiama CMake:To specify the external AZURE_SPHERE_TARGET_API_SET variable on the command line, include the parameter when invoking CMake:

    -DAZURE_SPHERE_TARGET_API_SET="latest-lts"

    Sostituire "latest-lts" con "latest-beta" o con un valore specifico meno recente, ad esempio "4" o "5+Beta2004" come descritto prima.Replace "latest-lts" with "latest-beta" or a specific older value such as "4" or "5+Beta2004" as explained earlier.

Compatibilità con i set di API di destinazione e il sistema operativoTarget API sets and OS compatibility

La compatibilità di un'applicazione con il sistema operativo di Azure Sphere dipende dal set di API di destinazione con cui è stata compilata l'applicazione e dalla versione di runtime dell'applicazione più recente supportata dal sistema operativo.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. Un'applicazione o un sistema operativo di livello inferiore usa una versione di runtime dell'applicazione precedente (con un numero inferiore), mentre un'applicazione o un sistema operativo di livello superiore usa una versione di runtime dell'applicazione più recente (con un numero superiore).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). Le sezioni seguenti descrivono cosa accade in ogni scenario possibile.The following sections describe what to expect in each possible scenario.

Applicazioni di livello inferiore con sistema operativo di livello superioreDown-level applications with up-level OS

Le immagini di livello inferiore esistenti che usano solo API di produzione sono supportate nelle versioni di livello superiore del sistema operativo Azure Sphere.Existing down-level images that use only production APIs are supported on up-level versions of the Azure Sphere OS. Ad esempio, un'applicazione compilata con il set di API di destinazione 1 viene eseguita correttamente in un sistema operativo Azure Sphere che supporta la versione di runtime dell'applicazione 2.For example, an application that was built with target API Set 1 runs successfully on an Azure Sphere OS that supports ARV 2. Di conseguenza, le applicazioni distribuite esistenti continueranno a funzionare correttamente dopo gli aggiornamenti del sistema operativo.Thus, your existing deployed applications will continue to operate properly after cloud OS updates. È possibile trasferire localmente o distribuire sul cloud immagini di livello inferiore, solo di produzione, a un sistema operativo di livello superiore senza errori.You can either sideload or cloud-deploy down-level, production-only images to an up-level OS without error.

Le immagini di livello inferiore che usano API beta non sono supportate e potrebbero non funzionare per progettazione nelle versioni di livello superiore del sistema operativo Azure Sphere.Down-level images that use Beta APIs are not supported, and may not work by design, on up-level versions of the Azure Sphere OS. Ad esempio, un'applicazione compilata con il set di API di destinazione 1+Beta1902 potrebbe non essere eseguita correttamente in un sistema operativo Azure Sphere con la versione di runtime dell'applicazione 2.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. I tentativi di sideload di tale immagine restituiscono un errore a meno che non si usi il --force flag nel comando azsphere Device sideload deploy .Attempts to sideload such an image return an error unless you use the --force flag on the azsphere device sideload deploy command. Analogamente, il comando azsphere Image Add richiede il --force flag per caricare un'immagine di questo tipo.Similarly, the azsphere image add command requires the --force flag to upload such an image. I controlli correnti non impediscono di distribuire un'immagine di livello inferiore caricata in precedenza che usa le API beta insieme a un sistema operativo di livello superiore che non supporta tali API beta.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.

Applicazioni di livello superiore con sistema operativo di livello inferioreUp-level applications with down-level OS

È impossibile distribuire applicazioni di livello superiore in versioni di livello inferiore del sistema operativo Azure Sphere, indipendentemente dal fatto che usino o meno le API beta.Up-level applications cannot be deployed to down-level versions of the Azure Sphere OS, regardless of whether they use Beta APIs. Il tentativo di trasferire localmente un'immagine di questo tipo avrà esito negativo con un errore.Attempts to sideload such an image will fail with an error. I tentativi di distribuzione in modalità over-the-air non sono attualmente possibili, in quanto l'SDK e il sistema operativo di livello superiore vengono rilasciati contemporaneamente.Attempts to deploy over-the-air are not currently possible because the up-level SDK and OS are released simultaneously.