Chamar APIs do Windows Runtime em aplicações de ambiente de trabalho

Configurar um projeto .NET

.NET 6 e versões posteriores: Use a opção Target Framework Moniker

Especifique uma versão específica do sistema operativo Windows do Target Framework Moniker (TFM) no ficheiro de projeto. Isto adiciona uma referência ao pacote de direcionamento Windows SDK apropriado durante a compilação.

1. No Visual Studio, selecione Project > [Nomedo do Projeto] Propriedades.

2. Na página de propriedades, encontre Aplicação > Geral selecionando-a na navegação do lado esquerdo ou deslizando até ela.

3. Escolha definições para:

   1. Target - Isto está inicialmente definido para a versão .NET que selecionou quando o projeto foi criado, mas pode alterá-la aqui.
   2. Target OS - Deixe isto definido para Windows.
   3. Versão do sistema operativo alvo - Selecione a versão do conjunto de APIs que pretende usar, normalmente a mais recente.
   4. Versão do SO suportada (Opcional) - Consulte a secção seguinte para mais informações.

No Target Framework Moniker, estes valores traduzem-se assim:

• Estrutura de alvo - net10.0
• Sistema operativo alvo - -windows
• Versão do sistema operativo de destino - 10.0.22621.0

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

Também pode definir os valores editando manualmente o ficheiro do projeto.

1. No Visual Studio, clique com o botão direito no seu projeto em Explorador de Soluções e escolha Editar Ficheiro de Projeto.

2. Substitua o valor TargetFramework por um TFM específico de uma versão do 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 (lançamento 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

   Observação

   Os valores apresentados correspondem ao .NET 10. Atualização conforme necessário para outras versões do .NET: net8.0, net9.0.

   Example:

   <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 para Windows

Para permitir que a sua aplicação corra numa versão Windows mais antiga do que o seu destino TFM, defina o SupportedOSVersion (SupportedOSPlatformVersion), como mostrado na secção anterior. Para mais informações, veja Frameworks Target: Suportar versões antigas do sistema operativo.

Quando direcionas uma variedade de versões do sistema operativo, guarda chamadas para APIs que não estão disponíveis em todas as versões usando verificações ApiInformation . Para obter mais informações, consulte aplicações adaptativas de versão.

Quando SupportedOSVersion está definido, Visual Studio dará um aviso para APIs que necessitem de uma verificação em tempo de execução. Por exemplo, se a versão alvo for 19041 e a versão mínima for 17763, verá um aviso deste tipo ao 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>

APIs WinRT não suportadas no .NET 6 e versões posteriores

Em .NET 6 e posteriores, várias APIs WinRT presentes no espaço de nomes Windows.UI não são suportadas. Utilize as APIs equivalentes no Microsoft.UI namespace (fornecido pelo SDK de Aplicações Windows) em vez disso.

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

Se a sua aplicação tem como objetivo .NET Core 3.x ou .NET Framework, instale o pacote NuGet Microsoft.Windows.SDK.Contracts:

1. No Visual Studio, clique com o botão direito no seu projeto e escolha Gerir Pacotes NuGet.

2. Procure por Microsoft.Windows.SDK.Contracts.

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

   Versão do pacote	Destino do Windows
   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.

Compatibilidade múltipla com .NET 6+ e versões anteriores de .NET

Configure o ficheiro do 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 multidirecionar entre versões .NET 6+ e anteriores, use compilação condicional para escrever código específico de uma única versão. Para mais informações, veja Frameworks 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 WinRT de aplicações de ambiente de trabalho em C++.

• Instala o Microsoft.Windows. CppWinRT Pacote NuGet.
• Como o C++/WinRT utiliza funcionalidades do padrão C++17, certifique-se de que a propriedade do projeto C/C++ > Language > C++ Language Standard esteja definida para ISO C++17 Standard (/std:c++17) ou posteriormente em Visual Studio.

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