Versão do tempo de execução do aplicativo, sysroots, e APIs Beta

Uma versão do SDK do Azure Sphere pode conter APIs de produção e APIs Beta. As APIs de produção são consideradas estáveis a longo prazo (LTS), enquanto as APIs Beta ainda estão em desenvolvimento e podem ser alteradas ou removidas de uma versão posterior. Na maioria dos casos, as novas APIs são marcadas como Beta em sua primeira versão e movidas para produção em uma versão subsequente. As APIs beta fornecem acesso antecipado a novos recursos, permitindo prototipagem e feedback antes de serem finalizados. Os aplicativos que usam APIs Beta geralmente exigirão modificações após versões futuras do sistema operacional Azure e SDK para continuar a funcionar corretamente.

Os recursos beta são rotulados como recurso BETA na documentação. Cada aplicativo de alto nível do Azure Sphere especifica se ele se destina apenas a APIs de produção ou a APIs de produção e Beta.

Conjuntos de API de destino, ARV e sysroots

O conjunto de APIs de destino indica quais APIs o aplicativo usa: somente APIs de produção ou APIs de produção e Beta. O valor do conjunto de API de destino é um inteiro que representa a versão de tempo de execução do aplicativo (ARV) ou o ARV mais uma cadeia de caracteres que identifica a versão da API Beta. O valor numérico por si só especifica apenas as APIs de produção no ARV, enquanto o "value+BetaNumber" especifica as APIs de produção e Beta em uma versão específica. Por exemplo, o ARV 8 indica a versão 21.01 e "8+Beta2101" especifica as APIs de produção e Beta na versão 20.01. Versões futuras adicionarão ARVs adicionais.

O SDK do Azure Sphere implementa vários conjuntos de API usando sysroots. Um sysroot especifica as bibliotecas, arquivos de cabeçalho e ferramentas que são usados para compilar e vincular um aplicativo destinado a um determinado conjunto de APIs. Os sysroots são instalados no diretório do SDK do Microsoft Azure Sphere na subpasta sysroots.

Definir ou atualizar a API de destino definida para um aplicativo de alto nível

Se você basear seu aplicativo em um exemplo do Azure Sphere, a API de destino definida por padrão será o conjunto de APIs que o exemplo usa. Se o exemplo usar apenas APIs de produção, o conjunto de APIs de destino será definido como o valor ARV atual. Se o exemplo usar APIs de produção e Beta para a versão atual, o conjunto de APIs de destino será "value+BetaNumber", para incluir as APIs Beta.

Se você não basear seu aplicativo em um exemplo, precisará definir a API de destino definida nas instruções de compilação para o aplicativo.

Se você já criou um aplicativo, talvez seja necessário alterar o conjunto de APIs de destino se reconstruir o aplicativo para uma nova versão do sistema operacional. Se o aplicativo usa APIs Beta, você deve atualizá-lo quando as opções do conjunto de APIs de destino mudarem, o que normalmente ocorre em cada versão de recurso. As APIs Beta podem ser movidas diretamente do status Beta para a produção, resultando em um novo ARV, ou podem ser alteradas e permanecer na Beta. Se você atualizar um aplicativo que usa APIs Beta para direcionar um conjunto de APIs de destino mais recente, poderá encontrar erros ou avisos sobre APIs removidas ou desativadas.

Sempre que você alterar o conjunto de APIs de destino, precisará excluir o arquivo CMakeCache.txt antes de criar o aplicativo. Esse arquivo é armazenado no diretório out\ARM-Debug ou out\ARM-Release do seu projeto.

Especificar conjunto de APIs de destino

Defina a API de destino definida em CMakePresets.json:

• Use "AZURE_SPHERE_TARGET_API_SET" para configurar o conjunto de APIs de destino. Por exemplo:

  "AZURE_SPHERE_TARGET_API_SET": "5" ou "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Se o seu aplicativo tiver como alvo o conjunto de API mais recente, você pode simplesmente definir essa variável como "latest-lts", se ainda não estiver. Se o seu aplicativo tiver como alvo o conjunto de APIs Beta mais recente, você pode simplesmente definir essa variável como "beta-mais recente", se ainda não estiver. No entanto, se seu aplicativo tiver como alvo um conjunto de APIs mais antigo, você precisará definir essa variável para corresponder ao valor específico que ele usa.

• Para especificar a variável AZURE_SPHERE_TARGET_API_SET externa em um projeto do Visual Studio, defina o seguinte no arquivo CMakeSettings.json, dentro das configurações ARM-Debug e ARM-Release:

  "variables": [
    {
      "name": "AZURE_SPHERE_TARGET_API_SET",
      "value": "latest-beta"
    }
  ]
  

• Para especificar a variável AZURE_SPHERE_TARGET_API_SET externa em um projeto do Visual Studio Code, defina o seguinte no arquivo .vscode/settings.json:

      "cmake.configureSettings": {
        "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
    },
  

• Para especificar a variável AZURE_SPHERE_TARGET_API_SET externa na linha de comando, inclua o parâmetro ao invocar CMake:

  -DAZURE_SPHERE_TARGET_API_SET="latest-lts"

  Substitua "latest-lts" por "latest-beta" ou um valor mais antigo específico, como "4" ou "5+Beta2004", como explicado anteriormente.

Conjuntos de APIs de destino e compatibilidade com SO

A compatibilidade de um aplicativo com o sistema operacional Azure Sphere depende do conjunto de APIs de destino com o qual o aplicativo foi criado e do ARV mais recente suportado pela versão do sistema operacional. Um aplicativo ou sistema operacional de nível inferior usa um ARV mais antigo (que tem um número menor) e um aplicativo ou sistema operacional de nível superior usa um ARV mais recente (que tem um número maior). As seções a seguir descrevem o que esperar em cada cenário possível.

Aplicativos de nível inferior com SO de nível superior

As imagens de nível inferior existentes que usam apenas APIs de produção são suportadas em versões de nível superior do sistema operacional Azure Sphere. Por exemplo, um aplicativo que foi criado com o Conjunto de APIs de destino 1 é executado com êxito em um sistema operacional Azure Sphere que dá suporte ao ARV 2. Assim, seus aplicativos implantados existentes continuarão a operar corretamente após as atualizações do sistema operacional na nuvem. Você pode fazer sideload ou implantar imagens somente de produção de nível inferior em um sistema operacional de nível superior sem erros.

Não há suporte para imagens de nível inferior que usam APIs Beta e podem não funcionar por design em versões de nível superior do sistema operacional Azure Sphere. Por exemplo, um aplicativo que foi criado com o conjunto de API de destino 1+Beta1902 pode falhar ao ser executado em um sistema operacional Azure Sphere que tenha ARV 2. As tentativas de sideload dessa imagem retornam um erro, a menos que você use o sinalizador --force no comando azsphere device sideload deploy . Da mesma forma, o comando azsphere image add requer que o --force sinalizador carregue essa imagem. Nenhuma verificação atual impede que uma imagem de nível inferior carregada anteriormente que usa APIs Beta seja implantada ao lado de um sistema operacional de nível superior que não suporta mais essas APIs Beta.

Aplicativos de nível superior com sistema operacional de nível inferior

Os aplicativos de nível superior não podem ser implantados em versões de nível inferior do sistema operacional Azure Sphere, independentemente de usarem APIs Beta. As tentativas de fazer sideload dessa imagem falharão com um erro. As tentativas de implantação over-the-air não são atualmente possíveis porque o SDK e o sistema operacional de nível superior são lançados simultaneamente.