Chamar APIs de Windows Runtime em aplicativos da área de trabalho

Configurar um projeto de .NET

.NET 6 e posterior: Use a opção Moniker do Framework de Destino

Especifique um Target Framework Moniker (TFM) específico de versão do Windows no arquivo de projeto. Isso adiciona uma referência ao pacote de direcionamento adequado do Windows SDK no tempo de compilação.

1. Em Visual Studio, selecione Project > [ProjectName] Propriedades.

2. Na página de propriedades, localize o Application > General selecionando-o na navegação do lado esquerdo ou rolando até ele.

3. Escolha as configurações para:

   1. Target framework – inicialmente está definido como a versão .NET selecionada quando o projeto foi criado, mas você pode alterá-lo aqui.
   2. Target OS – deixe isso configurado como Windows.
   3. Versão do sistema operacional de destino – selecione a versão do conjunto de API que você deseja usar, normalmente a mais recente.
   4. Versão do sistema operacional com suporte (opcional) – consulte a próxima seção para obter mais informações.

configurações da estrutura

No Moniker de Framework de Destino, esses valores são traduzidos da seguinte forma:

• Estrutura de destino - net10.0
• Sistema Operacional de Destino - -windows
• Versão do sistema operacional de destino - 10.0.22621.0

<TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
<!-- If set... -->
<SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

Você também pode definir os valores editando manualmente o arquivo de projeto.

1. Em Visual Studio, clique com o botão direito do mouse no project em Gerenciador de Soluções e escolha Edit Project File.

2. Substitua o valor TargetFramework por um TFM específico da versão Windows.

   Target	TFM
   Windows 11, versão 24H2	net10.0-windows10.0.26100.0
   Windows 11, versão 22H2	net10.0-windows10.0.22621.0
   Windows 11 (versão inicial)	net10.0-windows10.0.22000.0
   Windows 10, versão 2004	net10.0-windows10.0.19041.0
   Windows 10, versão 1903	net10.0-windows10.0.18362.0
   Windows 10, versão 1809	net10.0-windows10.0.17763.0

   Note

   Os valores mostrados são para .NET 10. Atualizar conforme necessário para outras versões do .NET: net8.0, net9.0.

   Exemplo:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     </PropertyGroup>
   </Project>
   

3. Salve e feche o arquivo de projeto.

Suportar uma versão mínima do Windows

Para permitir que seu aplicativo seja executado em uma versão Windows mais antiga que o destino do TFM, defina o SupportedOSVersion (SupportedOSPlatformVersion), conforme mostrado na seção anterior. Para obter mais informações, consulte estruturas de destino: dar suporte a versões mais antigas do sistema operacional.

Quando você direciona um intervalo de versões do sistema operacional, proteja chamadas para APIs que não estão disponíveis em todas as versões usando verificações de ApiInformation . Para obter mais informações, confira Aplicativos de versão adaptável.

Quando SupportedOSVersion estiver definido, Visual Studio fornecerá um aviso para APIs que precisam de uma verificação de runtime. Por exemplo, se a versão de destino for 19041 e a versão mínima for 17763, você verá um aviso como este quando chamar AppInfo.Current.

CA1416	Using platform dependent API on a component makes the code no longer work across all platforms.

This call site is reachable on: 'Windows' 10.0.17763.0 and later. 'AppInfo.Current' is only supported on: 'Windows' 10.0.19041.0 and later.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <SupportedOSPlatformVersion>10.0.17763.0</SupportedOSPlatformVersion>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
  </PropertyGroup>
</Project>

NÃO há suporte para APIs do WinRT no .NET 6 e posterior

No .NET 6 e posterior, várias APIs do WinRT no namespace Windows.UI não são suportadas. Use as APIs equivalentes no namespace Microsoft.UI (fornecido pelo SDK do Aplicativo Windows) em vez disso:

.NET Core 3.x ou .NET Framework: instalar o pacote NuGet

Se o aplicativo for desenvolvido para .NET Core 3.x ou .NET Framework, instale o pacote NuGet Microsoft.Windows.SDK.Contracts.

1. Em Visual Studio, clique com o botão direito do mouse em seu projeto e escolha Manage Pacotes NuGet.

2. Pesquise por Microsoft.Windows.SDK.Contracts.

3. Selecione a versão do pacote que corresponde ao seu destino mínimo de Windows:

   Versão do pacote	Windows alvo
   10.0.19041.xxxx	Windows 10, versão 2004
   10.0.18362.xxxx	Windows 10, versão 1903
   10.0.17763.xxxx	Windows 10, versão 1809
   10.0.17134.xxxx	Windows 10, versão 1803

4. Clique em Instalar.

Multidestino .NET 6+ e versões anteriores do .NET

Configure o arquivo de projeto para usar a abordagem TFM para .NET 6+ e o pacote NuGet para versões anteriores:

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFrameworks>netcoreapp3.1;net8.0-windows10.0.19041.0</TargetFrameworks>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                     Include="Microsoft.Windows.SDK.Contracts"
                     Version="10.0.19041.0"/>
  </ItemGroup>
</Project>

Compilação condicional

Ao direcionar várias versões do .NET 6+ e versões anteriores, use a compilação condicional para gravar código específico de versão em um único projeto. Para obter mais informações, consulte estruturas de destino: símbolos de pré-processador.

#if NET6_0_OR_GREATER
    // Code that uses .NET 6+ APIs or TFM-available WinRT APIs
#else
    // Fallback code for .NET Core 3.x / .NET Framework
#endif

Configurar um projeto C++ (Win32)

Use C++/WinRT para consumir APIs do WinRT em aplicativos de desktop em C++.

• Instale o Microsoft.Windows. CppWinRT pacote NuGet.
• Como o C++/WinRT usa recursos do padrão C++17, verifique se a propriedade do projeto C/C++ > Language > C++ Language Standard está definida como ISO C++17 Standard (/std:c++17) ou posterior em Visual Studio.

Para obter mais detalhes, consulte Visual Studio suporte para C++/WinRT.