Windows versões e visão geral do SDK

Ao começar a criar aplicativos Windows, você observará referências a vários números de versão diferentes: a versão do sistema operacional Windows, o SDK do Windows e o SDK do Aplicativo Windows. Não se preocupe: para a maioria dos novos projetos, Visual Studio define padrões sensatos e você não precisará pensar nisso. Mas quando você precisa direcionar uma versão específica do sistema operacional, entender por que uma API não está disponível ou configurar seu arquivo de projeto, este artigo explica como as partes se encaixam e quais opções fazer.

Definições

Nomenclatura de versões do sistema operacional Windows

Windows 11 fornece as principais atualizações de recursos usando o padrão de nomenclatura YYHX:

• YY = ano civil de dois dígitos
• H1 = primeiro semestre do ano; H2 = segundo semestre do ano

Historicamente, a maioria dos principais lançamentos ocorre no outono (H2), mas também há lançamentos no H1.

Regra: O número de build do sistema operacional no dispositivo do usuário determina quais APIs de plataforma estão disponíveis em runtime.

Mapeamento das versões do SDK do Windows para as versões do sistema operacional

Cada Windows família de versões do SDK corresponde a uma versão do sistema operacional Windows. O número de build principal do SDK normalmente corresponde ao número de build do sistema operacional, embora algumas atualizações de recursos do sistema operacional (entregues como pacotes de habilitação) compartilhem a mesma família de SDK que uma versão anterior.

Regra: A instalação de uma determinada Windows SDK concede acesso de tempo de compilação a todas as APIs dessa versão do sistema operacional e a todas as versões anteriores. As APIs são cumulativas.

SDK do Aplicativo Windows versões

O SDK do Aplicativo Windows é independente do sistema operacional Windows e do SDK do Windows. Ele é distribuído em seu próprio ritmo como um pacote NuGet.

Regra: Você pode usar o SDK do Aplicativo Windows mais recente em versões do sistema operacional mais antigas (de volta ao mínimo indicado). A versão SDK do Aplicativo Windows não precisa corresponder à versão do sistema operacional Windows ou Windows versão do SDK.

Para obter a matriz de suporte completa, consulte SDK do Aplicativo Windows versões de Windows com suporte.

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. SDK do Aplicativo Windows não substitui o SDK do Windows – você precisa de ambos.
2. A versão do SDK Windows pode ser mais recente do que o sistema operacional em que seu aplicativo é executado (use verificações de runtime para APIs mais recentes).
3. A versão SDK do Aplicativo Windows é completamente independente– atualize-a sem alterar mais nada.
4. Não é possível chamar uma API da plataforma em tempo de execução se o build do sistema operacional do usuário for mais antigo do que o build que a introduziu, independentemente do SDK com o qual você compilou.

Configuração do arquivo de projeto

As propriedades do MSBuild no arquivo do seu projeto controlam o direcionamento da plataforma. Os nomes de propriedade diferem ligeiramente entre C# e C++:

Arquivo de projeto C# (.csproj)

Em projetos .NET no formato SDK (usados nos modelos do WinUI 3 e do SDK do Aplicativo Windows), a versão da plataforma Windows fica incorporada ao 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>

Arquivo 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 em seu TFM como o SDK de Windows estável mais recente (por exemplo, net8.0-windows10.0.26100.0). Isso oferece a mais ampla superfície de API disponível em tempo de compilação e habilita avisos do analisador de compatibilidade da plataforma para APIs que não estão disponíveis no sistema operacional mínimo compatível.
2. Defina SupportedOSPlatformVersion (ou TargetPlatformMinVersion) com base em seu público-alvo:
   • Aplicativos empresariais com dispositivos gerenciados: correspondem ao sistema operacional mínimo com suporte da sua organização.
   • Aplicativos de consumidor (alcance mais amplo): 10.0.19041.0 (Windows 10 2004) ou 10.0.17763.0 (Windows 10 1809).
   • Aplicativos que usam recursos de uma versão específica do sistema operacional: definido como o número de build dessa versão.
3. Sempre use a SDK do Aplicativo Windows estável mais recente. Não há perda de compatibilidade; é compatível desde o Windows 10 1809.
4. Nunca use versões prévias/experimentais do SDK em produção.

Verificações de disponibilidade da API de runtime

Quando a versão da plataforma Windows em seu TFM é maior do queSupportedOSPlatformVersion, algumas APIs visíveis em tempo de compilação podem não existir no dispositivo do usuário. O analisador de compatibilidade da plataforma .NET avisa sobre eles em tempo de compilação, mas você também deve verificar a disponibilidade no runtime antes de chamá-los.

Padrão: Verificar o contrato de API (APIs do 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 há um tipo específico

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

Padrão: verificar se há um método específico

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

Regra: Se você ignorar essas verificações e chamar uma API indisponível, o aplicativo falhará em runtime. A falha exata depende do tipo de API — exceções comuns incluem TypeLoadException, MissingMethodExceptionou um erro específico da plataforma.

Perguntas comuns

"Qual Windows SDK devo usar?"

Use o SDK de Windows mais recente disponível (atualmente 10.0.26100). Você sempre pode compilar com um SDK mais recente do que a versão mínima de destino — isso afeta apenas o que fica visível em tempo de compilação.

"Preciso atualizar o SDK do Windows quando atualizar o SDK do Aplicativo Windows?"

Não. Eles são independentes. Você pode atualizar Microsoft.WindowsAppSDK da 1.7 para a 1.8 sem alterar a versão do SDK do Windows.

"Meu aplicativo tem como destino Windows 10. Posso usar o SDK do Aplicativo Windows?"

Sim. O SDK do Aplicativo Windows dá suporte a Windows 10 versão 1809 (build 17763) e posterior. Defina o seu SupportedOSPlatformVersion adequadamente.

O que acontece se eu compilar com o SDK 10.0.26100, mas o usuário estiver executando o Windows 11 22H2 (build 22621)?

As APIs introduzidas entre o build 22621 e 26100 estarão visíveis em seu código, mas falharão em runtime, a menos que você adicione verificações de disponibilidade de API. As APIs da versão 22621 e anteriores funcionarão normalmente.

"Como saber qual número de build introduziu uma API específica?"

Verifique a página de referência da API no Microsoft Learn. A seção Requisitos lista o build mínimo do sistema operacional (como uma versão de contrato de API ou Windows versão).

Resumo das regras

Conteúdo relacionado

• Versões do Windows com suporte pelo SDK do Aplicativo Windows
• Notas de versão do SDK do Aplicativo Windows
• arquivo do SDK do Windows
• Aplicativos adaptados à versão
• Configurar seu ambiente de desenvolvimento