Aplicativos adaptáveis de versão: usar novas APIs mantendo a compatibilidade com versões anteriores

Cada versão do SDK do Windows 10 adiciona novas funcionalidades interessantes que você desejará aproveitar. No entanto, nem todos os seus clientes atualizarão seus dispositivos para a versão mais recente do Windows 10 ao mesmo tempo e você deseja garantir que seu aplicativo funcione no intervalo mais amplo possível de dispositivos. Aqui, mostramos como projetar seu aplicativo para que ele seja executado em versões anteriores do Windows 10, mas também aproveita os novos recursos sempre que seu aplicativo é executado em um dispositivo com a atualização mais recente instalada.

Há três etapas a serem tomadas para garantir que seu aplicativo dê suporte à maior variedade de dispositivos Windows 10.

• Primeiro, configure seu projeto de Visual Studio para direcionar as APIs mais recentes. Isso afeta o que acontece quando você compila seu aplicativo.
• Em segundo lugar, execute verificações de tempo de execução para garantir que você chame apenas as APIs disponíveis no dispositivo em que seu aplicativo está sendo executado.
• Em terceiro lugar, teste seu aplicativo na Versão Mínima e na Versão de Destino do Windows 10.

Configurar seu projeto de Visual Studio

A primeira etapa para dar suporte a várias versões de Windows 10 é especificar as versões Target e Minimum com suporte do SISTEMA OPERACIONAL/SDK em seu projeto de Visual Studio.

• Target: a versão do SDK que Visual Studio compila o código do aplicativo e executa todas as ferramentas. Todas as APIs e recursos nesta versão do SDK estão disponíveis no código do aplicativo no momento da compilação.
• Minimum: a versão do SDK compatível com a versão mais antiga do sistema operacional em que seu aplicativo pode ser executado (que será implantada pela loja) e a versão em relação à qual o Visual Studio compila o código de marcação do aplicativo.

Durante o runtime, seu aplicativo será executado na versão do sistema operacional na qual ele é implantado, portanto, seu aplicativo gerará exceções se você usar recursos ou chamar APIs que não estão disponíveis nessa versão. Mostramos como usar verificações de runtime para chamar as APIs corretas mais adiante neste artigo.

As configurações Alvo e Mínimo especificam os limites de um intervalo de versões do sistema operacional/SDK. No entanto, se você testar seu aplicativo na versão mínima, poderá ter certeza de que ele será executado em todas as versões entre a Mínima e a Alvo.

Ao criar um novo projeto no Visual Studio 2015, atualização 2 ou posterior, você será solicitado a definir as versões Destino e Mínimo compatíveis com seu aplicativo. Por padrão, a Versão de Destino é a versão mais alta do SDK instalada e a Versão Mínima é a versão mais baixa do SDK instalada. Você pode escolher "Target" e "Minimum" somente entre versões do SDK que estão instaladas no seu computador.

Normalmente, recomendamos que você mantenha as configurações padrão. No entanto, se você tiver uma versão prévia do SDK instalada e estiver escrevendo o código de produção, deverá alterar a Versão de Destino do SDK de Visualização para a versão oficial mais recente do SDK.

Para alterar a versão mínima e de destino de um projeto que já foi criado no Visual Studio, acesse a guia Project -> Properties -> Application -> Targeting.

Para referência, a tabela a seguir mostra os números de build para cada SDK.

Você pode baixar qualquer versão lançada do SDK no arquivo do Windows SDK e emulador. Você pode baixar o SDK mais recente do Windows Insider Preview na seção de desenvolvedores do site Windows Insider.

Para obter mais informações sobre atualizações do Windows 10, consulte informações de versão do Windows 10. Para obter informações importantes sobre o ciclo de vida de suporte do Windows 10, consulte a folha de dados do ciclo de vida do Windows.

Executar verificações de API

A chave para aplicativos adaptáveis de versão é a combinação de contratos de API e a classe ApiInformation . Essa classe permite detectar se um contrato, tipo ou membro de API especificado está presente para que você possa fazer chamadas à API com segurança em uma variedade de dispositivos e versões do sistema operacional.

Contratos de API

O conjunto de APIs dentro de uma família de dispositivos é dividido em subdivisões conhecidas como contratos de API. Você pode usar o método ApiInformation.IsApiContractPresent para testar a presença de um contrato de API. Isso é útil se você quiser testar a presença de muitas APIs que existem na mesma versão de um contrato de API.

    bool isScannerDeviceContract_1_Present =
        Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
            ("Windows.Devices.Scanners.ScannerDeviceContract", 1);

O que é um contrato de API? Essencialmente, um contrato de API representa um recurso – um conjunto de APIs relacionadas que juntas fornecem algumas funcionalidades específicas. Um contrato hipotético de API pode representar um conjunto de APIs que contém duas classes, cinco interfaces, uma estrutura, duas enumes e assim por diante.

Tipos logicamente relacionados são agrupados em um contrato de API e, começando com Windows 10, cada API Windows Runtime é membro de algum contrato de API. Com contratos de API, você está verificando a disponibilidade de um recurso ou API específico no dispositivo, verificando efetivamente os recursos de um dispositivo em vez de verificar se há um dispositivo ou sistema operacional específico. Uma plataforma que implementa qualquer API em um contrato de API é necessária para implementar todas as API nesse contrato de API. Isso significa que você pode testar se o sistema operacional em execução dá suporte a um contrato de API específico e, se isso acontecer, chamar qualquer uma das APIs nesse contrato de API sem verificar cada uma individualmente.

O maior e mais comumente usado contrato de API é o Windows. Foundation.UniversalApiContract. Ele contém a maioria das APIs no Universal Windows Platform. A documentação de SDKs de extensão da família de dispositivos e de contratos de API descreve a variedade de contratos de API disponíveis. Você verá que a maioria delas representa um conjunto de APIs relacionadas funcionalmente.

Código adaptável de versão e XAML condicional

Em todas as versões do Windows 10, você pode usar a classe ApiInformation em uma condição em seu código para testar a presença da API que deseja chamar. Em seu código adaptável, você pode usar vários métodos da classe, como IsTypePresent, IsEventPresent, IsMethodPresent e IsPropertyPresent, para testar APIs na granularidade necessária.

Para obter mais informações e exemplos, consulte o código adaptável de versão.

Se a versão mínima de seus aplicativos for build 15063 (Atualização de Criadores) ou posterior, você poderá usar XAML condicional para definir propriedades e instanciar objetos na marcação sem precisar usar o code behind. O XAML condicional fornece uma maneira de usar o método ApiInformation.IsApiContractPresent na marcação.

Para obter mais informações e exemplos, consulte XAML condicional.

APIs carregadas com atraso

A função QueryOptionalDelayLoadedAPI permite que os aplicativos da Store (que não são permitidos pela política chamem LoadLibrary) para detectar se a função carregada por atraso realmente foi encontrada.

#include <windows.h>
#include <commdlg.h>
#include <libloaderapi2.h>
#include <stdio.h>

EXTERN_C IMAGE_DOS_HEADER __ImageBase;
#define HMODULE_THISCOMPONENT reinterpret_cast<HMODULE>(&__ImageBase)

int __cdecl main(int argc, char** argv)
{
    if (QueryOptionalDelayLoadedAPI(HMODULE_THISCOMPONENT,
          "comdlg32.dll", "GetOpenFileNameW", 0))
    {
        printf("GetOpenFileNameW can be called!\n");
    }
    return 0;
}

Teste seu aplicativo adaptável a versões

Quando você usa código adaptável de versão ou XAML condicional para gravar um aplicativo adaptável de versão, é necessário testá-lo em um dispositivo executando a Versão Mínima e em um dispositivo executando a versão de destino do Windows 10.

Não é possível testar todos os caminhos de código condicional em um único dispositivo. Para garantir que todos os caminhos de código sejam testados, você precisa implantar e testar seu aplicativo em um dispositivo remoto (ou máquina virtual) executando a versão mínima do sistema operacional com suporte. Para obter mais informações sobre depuração remota, consulte Implantação e depuração de aplicativos UWP.

Artigos relacionados

• O que é um aplicativo UWP