Código adaptável de versão

Você pode pensar em escrever código adaptável de forma semelhante à maneira como você pensa em criar uma interface do usuário adaptável. Crie seu código base para ser executado na versão mais baixa do sistema operacional e adicione recursos quando detectar que seu aplicativo é executado em uma versão mais alta em que um novo recurso está disponível.

Para obter informações em segundo plano sobre ApiInformationcontratos de API e configuração de Visual Studio, consulte aplicativos adaptáveis de versão.

Pré-requisitos

  • Um projeto SDK do Aplicativo Windows (empacotado ou não empacotado). Veja o início rápido: crie seu primeiro aplicativo WinUI 3.
  • Familiaridade com o sistema de tipos do Windows Runtime (WinRT), já que as verificações se aplicam somente aos tipos do espaço de nomes Windows.*.

Verificações de API de runtime

Use a classe Windows.Foundation.Metadata.ApiInformation em uma condição no seu código para verificar se a API que você deseja chamar está disponível. Essa condição é avaliada onde quer que o aplicativo seja executado, mas resulta em true apenas em dispositivos nos quais a API está presente e disponível para ser chamada.

Importante

ApiInformationAs verificações funcionam apenas para tipos de Windows Runtime no namespace Windows.*. Eles não detectam tipos WinUI (Microsoft.UI.Xaml.*) porque esses tipos fazem parte do pacote de estrutura SDK do Aplicativo Windows, não do sistema operacional e não são registrados como metadados do WinRT que ApiInformation podem consultar. #if As diretivas de pré-processador também não ajudam aqui: elas são avaliadas em tempo de compilação com base na estrutura de destino, não em runtime com base na versão do sistema operacional ou do SDK na qual o aplicativo está realmente em execução. Para habilitar um recurso do WinUI condicionalmente, verifique a versão do SDK do Aplicativo Windows com a qual seu aplicativo foi compilado (consulte aplicativos adaptáveis à versão) ou envolva a chamada em um bloco try/catch e recorra a uma alternativa caso ela falhe em tempo de execução.

Dica

Várias verificações de API de runtime podem afetar o desempenho do aplicativo. Execute a verificação uma vez e armazene o resultado em cache e use o resultado armazenado em cache em todo o aplicativo.

Opções de código adaptável

Há duas maneiras de criar código adaptável:

  • Código do aplicativo — use verificações da API em tempo de execução no código subjacente. Essa é a abordagem recomendada para a maioria dos cenários.
  • Gatilhos de estado — Use gatilhos de estado extensíveis que ativam estados visuais com base na presença de uma API. Use gatilhos de estado quando houver uma propriedade simples ou uma alteração em um enum entre versões do sistema operacional que esteja vinculada a um estado visual.

Exemplo: verificar um valor de enumeração

Este exemplo mostra como verificar se um valor de enumeração específico está presente antes de usá-lo. Se o valor não estiver presente, o código retornará a uma alternativa. EnergySaverStatus e PowerManager são tipos genuínos do Windows Runtime no namespace Windows.System.Power, portanto ApiInformation pode consultá-los 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

Ao armazenar em cache o resultado de uma verificação de API, use esse valor armazenado em cache consistentemente em todo o aplicativo. Não repita a verificação em vários locais – verifique uma vez, armazene o resultado e faça referência a ele em todos os lugares.

Exemplo: verificar se há um método

Use IsMethodPresent para verificar se um método específico está disponível antes de chamá-lo:

DisplayRequest displayRequest = new DisplayRequest();

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

Exemplo: verificar se há uma propriedade

Use IsPropertyPresent para verificar se uma propriedade específica está disponível antes de lê-la:

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

Práticas recomendadas

Prática Orientações
Usar cadeias de caracteres estáticas Ao verificar nomes de API com ApiInformation, use strings codificadas explicitamente em vez de usar reflexão do .NET para evitar problemas de carregamento de tipos em tempo de execução
Resultados do cache Executar cada verificação de API uma vez na inicialização e armazenar o resultado para reutilização
Manter a versão mínima baixa Defina a Versão Mínima do projeto tão baixa quanto prática para alcançar o público mais amplo e use o código adaptável para iluminar os recursos em versões mais recentes do sistema operacional
Testar na versão mínima Sempre teste na versão mínima do sistema operacional com suporte para verificar se os caminhos de fallback funcionam corretamente

Conteúdo relacionado

  • Last updated on