Versões do Windows e visão geral do SDK

Quando começar a construir aplicações Windows, vai notar referências a vários números de versão diferentes — a versão do Windows OS, o Windows SDK e o SDK de Aplicações Windows. Não te preocupes: para a maioria dos projetos novos, o Visual Studio define padrões sensatos e nem precisas de pensar nisso. Mas quando precisas de direcionar uma versão específica do sistema operativo, perceber porque é que uma API não está disponível ou configurar o ficheiro do teu projeto, este artigo explica como as peças se encaixam e que escolhas fazer.

Definições

Nomeação das versões do Windows OS

O Windows 11 traz atualizações importantes de funcionalidades usando o padrão de nomenclatura YYHX:

• YY = ano civil de dois dígitos
• H1 = primeira metade do ano; H2 = segunda metade do ano

A maioria dos lançamentos principais historicamente foi lançada no outono (H2), mas também ocorrem lançamentos H1.

Regra: O número de compilação do sistema operativo no dispositivo do utilizador determina quais as APIs da plataforma disponíveis em tempo de execução.

Mapeamento do SDK do Windows para a versão do sistema operativo

Cada família de versões de SDK do Windows corresponde a uma versão do sistema operativo Windows. O número de compilação principal do SDK normalmente corresponde ao número de compilação do sistema operativo, embora algumas atualizações de funcionalidades do sistema operativo (entregues como pacotes de habilitação) partilhem a mesma família de SDKs de uma versão anterior.

Regra: Instalar um determinado SDK Windows concede acesso em tempo de compilação a todas as APIs dessa versão do sistema operativo e de todas as versões anteriores. As APIs são cumulativas.

Versões do SDK de Aplicações Windows

O SDK de Aplicações Windows é independente tanto do sistema operativo Windows como do Windows SDK. É disponibilizado ao seu próprio ritmo como um pacote NuGet.

Regra: Pode usar o mais recente SDK de Aplicações Windows em versões antigas do sistema operativo (de volta ao mínimo declarado). A versão do SDK de Aplicações Windows NÃO precisa de corresponder à versão do Windows OS ou ao Windows SDK.

Para a matriz completa de suporte, consulte versões Windows suportadas pelo SDK de Aplicações Windows.

Como os três componentes se relacionam

Your App (.exe / .msix)
  │
  ├── References: Windows App SDK (NuGet package, e.g., 2.2)
  │     • Provides: WinUI 3, app lifecycle, windowing, push notifications
  │     • Updated: independently via NuGet
  │     • Constraint: has a minimum supported OS version
  │
  ├── Compiled against: Windows SDK (e.g., 10.0.26100)
  │     • Provides: Win32, WinRT, COM API declarations
  │     • Updated: with Visual Studio or standalone installer
  │     • Constraint: determines which APIs are visible at compile time
  │
  └── Runs on: Windows OS (e.g., Windows 11 24H2, build 26100)
        • Provides: actual API implementations at runtime
        • Updated: Windows Update
        • Constraint: determines which APIs are callable at runtime

Relações-chave:

1. O SDK de Aplicações Windows não substitui o Windows SDK — precisa de ambos.
2. A versão do SDK do Windows pode ser mais recente do que o sistema operativo onde a tua aplicação corre (usa verificações de runtime para APIs mais recentes).
3. A versão do SDK de Aplicações Windows é completamente independente — atualize-a sem alterar mais nada.
4. Não podes chamar uma API de plataforma em tempo de execução se a build do sistema operativo do utilizador for mais antiga do que a build que a introduziu, independentemente do SDK contra o qual compilaste.

Configuração do arquivo de projeto

As propriedades do MSBuild no ficheiro de projeto controlam a plataforma de destino. Os nomes das propriedades diferem ligeiramente entre C# e C++:

Ficheiro de projeto C# (.csproj)

Em projetos .NET ao estilo SDK (usados pelos modelos WinUI 3 e SDK de Aplicações Windows), a versão da plataforma Windows está incorporada no Target Framework Moniker (TFM):

<PropertyGroup>
    <!-- The TFM includes the Windows SDK version you compile against -->
    <TargetFramework>net8.0-windows10.0.26100.0</TargetFramework>

    <!-- The minimum OS version your app supports -->
    <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

    <!-- Or equivalently: -->
    <!-- <TargetPlatformMinVersion>10.0.19041.0</TargetPlatformMinVersion> -->
</PropertyGroup>

<ItemGroup>
    <!-- Windows App SDK (independent of the above) -->
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="2.2.0" />
</ItemGroup>

Ficheiro de projeto C++ (.vcxproj)

<PropertyGroup>
    <!-- Note: C++ uses "WindowsTargetPlatform" prefix -->
    <WindowsTargetPlatformVersion>10.0.26100.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
</PropertyGroup>

Guia de decisão: escolher versões

Use as seguintes regras para selecionar versões para um novo projeto:

1. Defina a versão da plataforma Windows no seu TFM para o mais recente SDK estável do Windows (por exemplo, net8.0-windows10.0.26100.0). Isto dá-lhe a superfície mais ampla de APIs em tempo de compilação e permite avisos de análise de compatibilidade de plataforma para APIs indisponíveis no seu sistema operativo mínimo.
2. Define SupportedOSPlatformVersion (ou TargetPlatformMinVersion) com base no teu público:
   • Aplicações empresariais com dispositivos geridos: correspondam ao sistema operativo mínimo suportado pela sua organização.
   • Aplicações de consumo (maior alcance): 10.0.19041.0 (Windows 10 2004) ou 10.0.17763.0 (Windows 10 1809).
   • Aplicações que usam funcionalidades de uma versão específica do sistema operativo: definidas para o número de compilação dessa versão.
3. Use sempre o mais recente SDK de Aplicações Windows estável. Não há penalização de compatibilidade; suporta até ao Windows 10 1809.
4. Nunca uses versões de pré-visualização/SDK experimentais em produção.

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

Quando a versão da plataforma Windows no seu TFM é superior a SupportedOSPlatformVersion, algumas APIs visíveis em tempo de compilação podem não existir no dispositivo do utilizador. O analisador de compatibilidade da plataforma .NET alerta para estas situações em tempo de compilação, mas tem de verificar também a disponibilidade em tempo de execução antes de as invocar.

Padrão: Verifique o contrato da API (APIs WinRT)

using Windows.Foundation.Metadata;

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 15))
{
    // Safe to call APIs introduced in this contract version.
    // For example, use a newer composition API:
}
else
{
    // Fallback for older OS versions
}

Padrão: Verificar se existe um tipo específico

if (ApiInformation.IsTypePresent("Windows.UI.Composition.SceneVisual"))
{
    // Safe to use SceneVisual
}

Padrão: Verifique um método específico

if (ApiInformation.IsMethodPresent("Windows.Storage.StorageFile", "GetFileFromPathForUserAsync"))
{
    // Safe to call this method
}

Regra: Se saltar estas verificações e chamar uma API indisponível, a aplicação falhará em tempo de execução. A falha exata depende do tipo de API — exceções comuns incluem TypeLoadException, MissingMethodException, ou um erro específico da plataforma.

Perguntas frequentes

"Que SDK do Windows devo usar?"

Use o mais recente SDK do Windows disponível (atualmente 10.0.26100). Podes sempre compilar contra um SDK mais recente do que o teu mínimo alvo — isso só afeta o que está visível em tempo de compilação.

Preciso de atualizar o SDK do Windows quando atualizo o SDK de Aplicações Windows?

Não. São independentes. Podes atualizar Microsoft.WindowsAppSDK da versão 1.7 para a 1.8 sem mudar a versão do SDK do Windows.

"A minha aplicação tem como alvo o Windows 10. Posso usar o SDK de Aplicações Windows?"

Yes. O SDK de Aplicações Windows suporta o Windows 10 versão 1809 (versão 17763) e posteriores. Ajusta o teu SupportedOSPlatformVersion em conformidade.

O que acontece se eu compilar com o SDK 10.0.26100, mas o utilizador estiver a executar o Windows 11 22H2 (build 22621)?

As APIs introduzidas entre a build 22621 e a 26100 estarão visíveis no teu código, mas falharão em tempo de execução a menos que adiciones verificações de disponibilidade de API. APIs de 22621 e anteriores funcionam normalmente.

"Como é que sei qual o número de build que introduziu uma API específica?"

Consulte a página de referência da API no Microsoft Learn. A secção de Requisitos lista a construção mínima do sistema operativo (como uma versão do contrato API ou versão do Windows).

Resumo das regras

Conteúdo relacionado

• Versões do Windows suportadas pelo SDK de Aplicações Windows
• Notas de lançamento do SDK de Aplicações Windows
• Arquivo do SDK do Windows
• Aplicações adaptativas de versão
• Configure seu ambiente de desenvolvimento