Código adaptativo de versão

Podes pensar em escrever código adaptativo de forma semelhante a como pensas em criar uma interface adaptativa. Desenhe o seu código base para correr na versão mais baixa do sistema operativo e depois adicione funcionalidades quando detetar que a sua aplicação corre numa versão superior onde uma nova funcionalidade está disponível.

Para informações de fundo sobre ApiInformation, contratos de API e configuração do Visual Studio, consulte Aplicações adaptativas de versão.

Pré-requisitos

Verificações de API em tempo de execução

Utilize a classe Windows.Foundation.Metadata.ApiInformation numa condição no código para verificar se a API que pretende chamar está disponível. Esta condição é avaliada em qualquer local onde a sua aplicação seja executada, mas tem o valor true apenas em dispositivos onde a API está presente e disponível para ser chamada.

Importante

ApiInformationAs verificações funcionam apenas para tipos de Windows Runtime no espaço de nomes Windows.*. Eles não detetam tipos WinUI (Microsoft.UI.Xaml.*) porque esses tipos fazem parte do pacote framework do SDK de Aplicações Windows, não do sistema operativo, e não estão registados como metadados WinRT que ApiInformation podem consultar. #if As diretivas de pré-processador também não ajudam aqui—são avaliadas em tempo de compilação com base no framework de destino, não em tempo de execução com base na versão do sistema operativo ou SDK onde a aplicação está realmente a correr. Para ativar uma funcionalidade do WinUI de forma condicional, verifique a versão do SDK de Aplicações Windows com a qual a sua aplicação foi compilada (consulte Aplicações adaptativas por versão) ou envolva a chamada num bloco try/catch e recorra a uma alternativa se esta falhar em tempo de execução.

Tip

Inúmeras verificações da API em tempo de execução podem afetar o desempenho da sua aplicação. Faça a verificação uma vez e armazene o resultado em cache, depois use o resultado em cache em toda a sua aplicação.

Opções de código adaptativo

Existem duas formas de criar código adaptativo:

  • Código da aplicação — Use verificações de API em tempo de execução no código por trás. Esta é a abordagem recomendada para a maioria dos cenários.
  • Gatilhos de estado — Use gatilhos de estado extensíveis que ativem estados visuais com base na presença de uma API. Use acionadores de estado quando existir uma alteração simples de uma propriedade ou de uma enumeração entre versões do sistema operativo associada a um estado visual.

Exemplo: Verifique um valor de enum

Este exemplo mostra como verificar se um valor específico de enum está presente antes de o usar. Se o valor não estiver presente, o código recorre a uma alternativa. EnergySaverStatus e PowerManager são tipos genuínos do Windows Runtime no espaço de nomes Windows.System.Power, pelo que ApiInformation os pode consultar corretamente.

if (ApiInformation.IsEnumNamedValuePresent(
    "Windows.System.Power.EnergySaverStatus", "On"))
{
    if (PowerManager.EnergySaverStatus == EnergySaverStatus.On)
    {
        // Reduce background work to save battery.
        ReduceBackgroundActivity();
    }
}
else
{
    // Energy Saver status isn't available on this OS version; skip the check.
}

void ReduceBackgroundActivity()
{
    // Pause non-essential timers, syncs, and animations here.
}

Importante

Quando guardar em cache o resultado de uma verificação da API, use esse valor em cache de forma consistente em toda a sua aplicação. Não repita a verificação em vários locais — verifique uma vez, guarde o resultado e consulte em todo o lado.

Exemplo: Verifique um método

Use IsMethodPresent para verificar se um método específico está disponível antes de o chamar:

DisplayRequest displayRequest = new DisplayRequest();

if (ApiInformation.IsMethodPresent(
    "Windows.System.Display.DisplayRequest", "RequestActive"))
{
    displayRequest.RequestActive();
}

Exemplo: Verificar se há um imóvel

Use IsPropertyPresent para verificar se uma propriedade específica está disponível antes de a ler:

if (ApiInformation.IsPropertyPresent(
    "Windows.System.Power.PowerManager", "RemainingChargePercent"))
{
    int chargePercent = PowerManager.RemainingChargePercent;
}

Melhores práticas

Practice Guidance
Use cordas estáticas Ao verificar nomes de API com ApiInformation, use cadeias de caracteres codificadas de forma fixa em vez de reflection do .NET para evitar problemas de carregamento de tipos em tempo de execução
Resultados do cache Realize cada verificação da API uma vez no arranque e armazene o resultado para reutilização
Mantenha a versão mínima baixa Defina a Versão Mínima do seu projeto o mais baixa possível para alcançar o maior público possível e use código adaptativo para iluminar funcionalidades nas versões mais recentes do sistema operativo
Teste na versão mínima Teste sempre na versão mínima do sistema operativo suportada para verificar se os mecanismos de recurso funcionam corretamente

Conteúdo relacionado

  • Last updated on