Partilhar via

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

Este tópico descreve como configurar seus projetos de aplicativos da área de trabalho para usar APIs do Tempo de Execução do Windows (WinRT) fornecidas pelo sistema operacional Windows e adicionar experiências modernas do Windows 11 e do Windows 10 aos seus aplicativos da área de trabalho.

Algumas APIs do Tempo de Execução do Windows (WinRT) não são suportadas em aplicativos da área de trabalho. Para obter mais informações, consulte APIs do Tempo de Execução do Windows não suportadas em aplicações de ambiente de trabalho.

Modificar um projeto .NET para usar APIs do Tempo de Execução do Windows

Há várias opções para projetos .NET:

  • A partir do .NET 6, você pode especificar o Target Framework Moniker (TFM) em seu arquivo de projeto para acessar APIs do WinRT. Esta opção é suportada em projetos destinados ao Windows 10, versão 1809 ou posterior.
  • Para versões anteriores do .NET, você pode instalar o Microsoft.Windows.SDK.Contracts pacote NuGet para adicionar todas as referências necessárias ao seu projeto. Esta opção é suportada em projetos destinados ao Windows 10, versão 1803 ou posterior.
  • Se o seu projeto tiver vários destinos .NET 6 (ou posterior) e versões anteriores do .NET, então você pode configurar o arquivo de projeto para usar ambas as opções.

.NET 6 e posterior: Use a opção Target Framework Moniker

Esta opção é suportada apenas em projetos que usam o .NET 6 (ou posterior) e visam o Windows 10, versão 1809 ou uma versão posterior do sistema operacional. Ao especificar um TFM específico da versão do sistema operacional Windows no arquivo de projeto, uma referência é adicionada ao pacote de destino apropriado do SDK do Windows. Para obter mais informações básicas sobre esse cenário, consulte a postagem de blog Chamando APIs do Windows no .NET.

  1. Com seu projeto aberto no Visual Studio, clique com o botão direito do mouse em seu projeto no Gerenciador de Soluções e escolha Editar Arquivo de Projeto. Seu arquivo de projeto será semelhante a este.

    Observação

    O exemplo abaixo mostra um OutputType de WinExe, que especifica um executável GUI do Windows (e impede que uma janela do console seja aberta quando o aplicativo é executado). Se seu aplicativo não tiver uma GUI, seu OutputType terá um valor diferente. Você pode chamar APIs do WinRT de aplicativos GUI do Windows, aplicativos de console e bibliotecas. Além disso, seu valor para TargetFramework pode não corresponder exatamente ao exemplo abaixo.

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

  2. Deixando todas as outras configurações como estão, substitua o valor do elemento TargetFramework por uma das seguintes cadeias de caracteres:

    • net8.0-windows10.0.17763.0: Se a sua aplicação se destina ao Windows 10, versão 1809.
    • net8.0-windows10.0.18362.0: Se o seu aplicativo tiver como alvo o Windows 10, versão 1903.
    • net8.0-windows10.0.19041.0: Se a sua aplicação se destina ao Windows 10, versão 2004.
    • net8.0-windows10.0.22000.0: Se o seu aplicativo tiver como alvo a versão inicial do Windows 11.
    • net8.0-windows10.0.22621.0: Se o seu aplicativo tem como alvo o Windows 11, versão 22H2.
    • net8.0-windows10.0.26100.0: Se a sua aplicação se destina ao Windows 11, versão 24H2.

    Por exemplo, o elemento a seguir é para um projeto destinado ao Windows 10, versão 2004.

    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>

    Em versões posteriores do .NET, você pode substituir o valor pela versão relevante, por exemplo, net8.0-windows10.0.19041.0.

  3. Salve as alterações e feche o arquivo de projeto.

APIs do WinRT não suportadas no .NET 6 ou posterior

No .NET 6 e posterior, há várias APIs do Tempo de Execução do Windows (WinRT) no namespace Windows.UI que não são suportadas. Para as APIs listadas abaixo, existem versões equivalentes das APIs no namespace WinUI (Microsoft.UI) (por exemplo, Microsoft.UI.Text). As seguintes APIs do WinRT não são suportadas no .NET 6 e posterior:

  • Windows.UI.Colors classe
  • classe Windows.UI.ColorHelper
  • Windows.UI.Text (todas as classes nesta namespace, excetoWindows.UI.Text.FontStretch, Windows.UI.Text.FontStyle, Windows.UI.Text.FontWeight, Windows.UI.Text.UnderlineType e todas as classes no namespace Windows.UI.Text.Core)
  • Windows.UI.Xaml (todas as classes neste namespace)

Suporte a várias versões do sistema operacional Windows

A propriedade TargetFramework específica da versão do sistema operacional Windows determina a versão do SDK do Windows com a qual seu aplicativo é compilado. Essa propriedade determina o conjunto de APIs acessíveis no momento da compilação e fornece valores padrão para TargetPlatformVersion e TargetPlatformMinVersion (se não definido explicitamente). A propriedade TargetPlatformVersion não precisa ser explicitamente definida no arquivo de projeto, pois é definida automaticamente pela versão do sistema operacional TargetFramework .

O TargetPlatformMinVersion pode ser alterado para ser inferior ao TargetPlatformVersion (determinado pela versão na propriedade TargetFramework). Isso permite que um aplicativo seja executado em versões anteriores do sistema operacional. Por exemplo, você pode definir o seguinte em seu arquivo de projeto para dar suporte ao nível inferior do seu aplicativo para o Windows 10, versão 1809.

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

Observe que definir o TargetPlatformMinVersion para uma versão abaixo do TargetPlatformVersion cria o potencial para chamar APIs indisponíveis. Ao chamar APIs do WinRT que não estão disponíveis em todas as versões suportadas do sistema operativo, recomendamos proteger essas chamadas com verificações de ApiInformation. Para obter mais informações, consulte aplicações adaptativas de versão.

Versões anteriores do .NET: Instalar o pacote NuGet Microsoft.Windows.SDK.Contracts

Use essa opção se seu aplicativo usar o .NET Core 3.x ou o .NET Framework. Esta opção é suportada em projetos destinados ao Windows 10, versão 1803 ou posterior.

  1. Certifique-se de que as referências de pacote estejam habilitadas:

    1. No Visual Studio, clique em Ferramentas -> Gerenciador de Pacotes NuGet -> Configurações do Gerenciador de Pacotes.
    2. Certifique-se de que PackageReference esteja selecionado como formato de gestão de pacotes predefinido.

  2. Com seu projeto aberto no Visual Studio, clique com o botão direito do mouse em seu projeto no Gerenciador de Soluções e escolha Gerenciar Pacotes NuGet.

  3. Na janela Gestor de Pacotes NuGet, selecione o separador Procurar e efetue uma pesquisa por Microsoft.Windows.SDK.Contracts.

  4. Depois de encontrar o pacote , no painel direito da janela do Gerenciador de Pacotes NuGet do , selecione a Versão do pacote que pretende instalar com base na versão do Windows 10 ao qual se destina:

    • 10.0.19041.xxxx: Escolha esta opção para o Windows 10, versão 2004.
    • 10.0.18362.xxxx: Escolha esta opção para o Windows 10, versão 1903.
    • 10.0.17763.xxxx: Escolha esta opção para o Windows 10, versão 1809.
    • 10.0.17134.xxxx: Escolha esta opção para o Windows 10, versão 1803.

  5. Clique em Instalar.

Configurar projetos com múltiplas especificações de destino para diferentes versões do .NET

Se o seu projeto tiver vários destinos para o .NET 6 (ou posterior) e versões anteriores (incluindo o .NET Core 3.x e o .NET Framework), você poderá configurar o arquivo de projeto para usar o Target Framework Moniker (TFM) para obter automaticamente as referências da API do WinRT para .NET 6 (ou posterior) e usar o Microsoft.Windows.SDK.Contracts pacote NuGet para versões anteriores.

  1. Com seu projeto aberto no Visual Studio, clique com o botão direito do mouse em seu projeto no Gerenciador de Soluções e escolha Editar Arquivo de Projeto. O exemplo a seguir demonstra um arquivo de projeto para um aplicativo que usa o .NET Core 3.1.

    Observação

    O exemplo abaixo mostra um OutputType de WinExe, que especifica um executável GUI do Windows (e impede que uma janela do console seja aberta quando o aplicativo é executado). Se seu aplicativo não tiver uma GUI, seu OutputType terá um valor diferente. Você pode chamar APIs do WinRT de aplicativos GUI do Windows, aplicativos de console e bibliotecas. Além disso, seu valor para TargetFramework pode não corresponder exatamente ao exemplo abaixo.

    <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>
</Project>

  2. Substitua o elemento TargetFramework no arquivo por um elemento TargetFrameworks (note o plural). Neste elemento, indique os Target Framework Monikers (TFMs) para todas as versões do .NET que pretende apontar, separadas por ponto-e-vírgula.

    • Para .NET 6 ou posterior, use um dos seguintes Target Framework Monikers (TFMs):
      • net6.0-windows10.0.17763.0: Se o seu aplicativo tiver como alvo o Windows 10, versão 1809.
      • net6.0-windows10.0.18362.0: Se a sua aplicação se destina ao Windows 10, versão 1903.
      • net6.0-windows10.0.19041.0: Se a sua aplicação se destina ao Windows 10, versão 2004.
      • net6.0-windows10.0.22000.0: Se o seu aplicativo tiver como alvo a versão inicial do Windows 11.
      • net6.0-windows10.0.22621.0: Se a sua aplicação se destina ao Windows 11, versão 22H2.
      • net6.0-windows10.0.26100.0: Se a sua aplicação se destina ao Windows 11, versão 24H2.
    • Para .NET Core 3.x, use netcoreapp3.0 ou netcoreapp3.1.
    • Para .NET Framework, use net46.

    O exemplo seguinte demonstra como direcionar multiplamente o .NET Core 3.1 e o .NET 6 (para Windows 10, versão 2004).

    <TargetFrameworks>netcoreapp3.1;net6.0-windows10.0.19041.0</TargetFrameworks>

  3. Após o elemento PropertyGroup, adicione um elemento PackageReference que inclua uma instrução condicional para instalar o pacote NuGet Microsoft.Windows.SDK.Contracts para todas as versões do .NET Core 3.x ou .NET Framework que o seu aplicativo destina. O elemento PackageReference deve ser filho de um elemento ItemGroup. O exemplo a seguir demonstra como fazer isso para o .NET Core 3.1.

    <ItemGroup>
  <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                    Include="Microsoft.Windows.SDK.Contracts"
                    Version="10.0.19041.0" />
</ItemGroup>

    Quando terminar, o arquivo de projeto deverá ser semelhante a este.

    <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFrameworks>netcoreapp3.1;net6.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>

  4. Salve as alterações e feche o arquivo de projeto.

Modificar um projeto de área de trabalho C++ (Win32) para usar APIs do Tempo de Execução do Windows

Use C++/WinRT para consumir APIs do WinRT. C++/WinRT é uma projeção de linguagem C++17 moderna totalmente padrão para APIs do WinRT, implementada como uma biblioteca baseada em arquivo de cabeçalho e projetada para fornecer acesso de primeira classe à API moderna do Windows.

Para configurar seu projeto para C++/WinRT:

Para obter mais detalhes sobre essas opções, consulte suporte do Visual Studio para C++/WinRT e o VSIX.

Adicionar experiências do Windows 10

Agora você está pronto para adicionar experiências modernas que se acendem quando os usuários executam seu aplicativo no Windows 10. Use este fluxo de design.

✅ Primeiro, decida quais experiências você deseja adicionar

Há muito por onde escolher. Por exemplo, pode simplificar o seu fluxo de ordem de compra usando as APIs de monetização , ou direcionar a atenção para a sua aplicação quando tiver algo interessante para partilhar, como uma nova imagem publicada por outro utilizador.

Notificação de aviso

Mesmo que os usuários ignorem ou descartem sua mensagem, eles podem vê-la novamente na central de ações e, em seguida, clicar na mensagem para abrir seu aplicativo. Isso aumenta o envolvimento com seu aplicativo e tem o bônus adicional de fazer seu aplicativo parecer profundamente integrado com o sistema operacional. Mostraremos o código dessa experiência um pouco mais adiante neste artigo.

Consulte a documentação da UWP para obter mais ideias.

✅ Decida se deseja melhorar ou estender

Você ouvirá frequentemente que usamos os termos melhorar e ampliar, então vamos reservar um momento para explicar exatamente o que cada um desses termos significa.

Usamos o termo melhorar para descrever as APIs do WinRT que você pode chamar diretamente da sua aplicação da área de trabalho, independentemente de ser ou não uma aplicação empacotada. Quando tiver escolhido uma experiência com o Windows 10, identifique as APIs de que necessita para a criar e, em seguida, veja se essa API aparece em esta lista. Esta é uma lista de APIs que você pode chamar diretamente do seu aplicativo da área de trabalho. Se sua API não aparecer nessa lista, é porque a funcionalidade associada a essa API só pode ser executada dentro de um processo UWP. Muitas vezes, isso inclui APIs que processam XAML UWP, como um controle de mapa UWP ou um prompt de segurança do Windows Hello.

Observação

Embora as APIs que processam UWP XAML normalmente não possam ser chamadas diretamente da área de trabalho, você poderá usar abordagens alternativas. Se quiser hospedar controles UWP XAML ou outras experiências visuais personalizadas, você pode usar Ilhas XAML (a partir do Windows 10, versão 1903) e a camada Visual (a partir do Windows 10, versão 1803). Esses recursos podem ser usados em aplicativos de desktop empacotados ou não empacotados.

Se você optou por empacotar seu aplicativo da área de trabalho, outra opção é estender o aplicativo adicionando um projeto UWP à sua solução. O projeto de área de trabalho ainda é o ponto de entrada do seu aplicativo, mas o projeto UWP lhe dá acesso a todas as APIs que não aparecem em esta lista. O aplicativo de desktop pode se comunicar com o processo UWP usando um serviço de aplicativo e temos muitas orientações sobre como configurar isso. Se você quiser adicionar uma experiência que exija um projeto UWP, consulte Estender com componentes UWP.

✅ Contratos de API de referência

Se você puder chamar a API diretamente do seu aplicativo da área de trabalho, abra um navegador e procure o tópico de referência para essa API. Abaixo do resumo da API, você encontrará uma tabela que descreve o contrato de API para essa API. Aqui está um exemplo dessa tabela:

Tabela de contratos API

Se tiver uma aplicação de ambiente de trabalho baseada em .NET, adicione uma referência a esse contrato de API e, em seguida, defina a propriedade Copy Local desse ficheiro como False. Se tiver um projeto baseado em C++, adicione aos seus Diretórios de inclusão adicionais, um caminho para a pasta que contém este contrato.

✅ Chame as APIs para adicionar sua experiência

Aqui está o código que você usaria para mostrar a janela de notificação que vimos anteriormente. Essas APIs aparecem nesta lista para que você possa adicionar esse código ao seu aplicativo da área de trabalho e executá-lo agora.

using Windows.Foundation;
using Windows.System;
using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;
...

private void ShowToast()
{
    string title = "featured picture of the day";
    string content = "beautiful scenery";
    string image = "https://picsum.photos/360/180?image=104";
    string logo = "https://picsum.photos/64?image=883";

    string xmlString =
    $@"<toast><visual>
       <binding template='ToastGeneric'>
       <text>{title}</text>
       <text>{content}</text>
       <image src='{image}'/>
       <image src='{logo}' placement='appLogoOverride' hint-crop='circle'/>
       </binding>
      </visual></toast>";

    XmlDocument toastXml = new XmlDocument();
    toastXml.LoadXml(xmlString);

    ToastNotification toast = new ToastNotification(toastXml);

    ToastNotificationManager.CreateToastNotifier().Show(toast);
}

#include <sstream>
#include <winrt/Windows.Data.Xml.Dom.h>
#include <winrt/Windows.UI.Notifications.h>

using namespace winrt::Windows::Foundation;
using namespace winrt::Windows::System;
using namespace winrt::Windows::UI::Notifications;
using namespace winrt::Windows::Data::Xml::Dom;

void UWP::ShowToast()
{
    std::wstring const title = L"featured picture of the day";
    std::wstring const content = L"beautiful scenery";
    std::wstring const image = L"https://picsum.photos/360/180?image=104";
    std::wstring const logo = L"https://picsum.photos/64?image=883";

    std::wostringstream xmlString;
    xmlString << L"<toast><visual><binding template='ToastGeneric'>" <<
        L"<text>" << title << L"</text>" <<
        L"<text>" << content << L"</text>" <<
        L"<image src='" << image << L"'/>" <<
        L"<image src='" << logo << L"'" <<
        L" placement='appLogoOverride' hint-crop='circle'/>" <<
        L"</binding></visual></toast>";

    XmlDocument toastXml;

    toastXml.LoadXml(xmlString.str().c_str());

    ToastNotificationManager::CreateToastNotifier().Show(ToastNotification(toastXml));
}

using namespace Windows::Foundation;
using namespace Windows::System;
using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;

void UWP::ShowToast()
{
    Platform::String ^title = "featured picture of the day";
    Platform::String ^content = "beautiful scenery";
    Platform::String ^image = "https://picsum.photos/360/180?image=104";
    Platform::String ^logo = "https://picsum.photos/64?image=883";

    Platform::String ^xmlString =
        L"<toast><visual><binding template='ToastGeneric'>" +
        L"<text>" + title + "</text>" +
        L"<text>"+ content + "</text>" +
        L"<image src='" + image + "'/>" +
        L"<image src='" + logo + "'" +
        L" placement='appLogoOverride' hint-crop='circle'/>" +
        L"</binding></visual></toast>";

    XmlDocument ^toastXml = ref new XmlDocument();

    toastXml->LoadXml(xmlString);

    ToastNotificationManager::CreateToastNotifier()->Show(ref new ToastNotification(toastXml));
}

Para saber mais sobre notificações, consulte notificações toast adaptáveis e interativas.

Suporta bases de instalação do Windows XP, Windows Vista e Windows 7/8

Você pode modernizar seu aplicativo para Windows 10 sem ter que criar uma nova ramificação e manter bases de código separadas.

Se você quiser criar binários separados para usuários do Windows 10, use a compilação condicional. Se preferir criar um conjunto de binários que você implanta para todos os usuários do Windows, use verificações de tempo de execução.

Vamos dar uma olhada rápida em cada opção.

Compilação condicional

Você pode manter uma base de código e compilar um conjunto de binários apenas para usuários do Windows 10.

Primeiro, adicione uma nova configuração de compilação ao seu projeto.

Configuração de Compilação

Para essa configuração de compilação, crie uma constante para identificar o código que chama APIs do WinRT.

Para projetos baseados em .NET, a constante é chamada de constante de compilação condicional.

Constante de compilação condicional

Para projetos baseados em C++, a constante é chamada de Definição de Pré-processador.

Constante de definição do pré-processador

Adicione essa constante antes de qualquer bloco de código UWP.

[System.Diagnostics.Conditional("_UWP")]
private void ShowToast()
{
 ...
}

#if _UWP
void UWP::ShowToast()
{
 ...
}
#endif

O compilador cria esse código somente se essa constante for definida em sua configuração de compilação ativa.

Verificações de tempo de execução

Você pode compilar um conjunto de binários para todos os seus usuários do Windows, independentemente da versão do Windows que eles executam. Seu aplicativo chama APIs do WinRT somente se o usuário estiver executando seu aplicativo como um aplicativo empacotado no Windows 10.

A maneira mais fácil de adicionar verificações de tempo de execução ao seu código é instalar este pacote Nuget: Desktop Bridge Helpers e, em seguida, usar o método para bloquear todo o IsRunningAsUWP() código que chama APIs do WinRT. Consulte esta postagem do blog para obter mais detalhes: Desktop Bridge - Identifique o contexto do aplicativo.

Encontre respostas para as suas perguntas

Tem dúvidas? Pergunte-nos sobre Stack Overflow. Nossa equipe monitora essas etiquetas . Você também pode perguntar em nossos fóruns.

  • Last updated on