Compartilhar via

Introdução ao C++/WinRT

 

 

O C++/WinRT é uma projeção de linguagem C++17 totalmente padrão para APIs do WinRT (Windows Runtime), implementada como uma biblioteca baseada em arquivo de cabeçalho e projetada para fornecer acesso de primeira classe à API moderna do Windows. Com o C++/WinRT, você pode criar e consumir APIs do Windows Runtime usando qualquer compilador C++17 compatível com padrões. O SDK do Windows inclui C++/WinRT; foi introduzido na versão 10.0.17134.0 (Windows 10, versão 1803).

C++/WinRT é a substituição recomendada da Microsoft para a projeção de linguagem C++/CX e a wrl (Biblioteca de Modelos C++) do Windows Runtime. A lista completa de tópicos sobre o C++/WinRT inclui informações sobre interoperação e portabilidade de C++/CX e WRL.

Importante

Algumas das partes mais importantes do C++/WinRT, que devem ser observadas, são descritas nas seções sobre o suporte ao SDK para C++/WinRT, e sobre o suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e o pacote NuGet.

Veja também Onde posso encontrar aplicativos de exemplo do C++/WinRT?.

Projeções de linguagem

O Windows Runtime é baseado em APIs COM (Component Object Model) e foi projetado para ser acessado por meio projeções de linguagem. Uma projeção oculta os detalhes do COM e fornece uma experiência de programação mais natural para um determinado idioma.

A projeção de linguagem C++/WinRT no conteúdo de referência da API do Windows Runtime

Quando estiver navegando APIs do Windows Runtime, clique na caixa de combinação idioma no canto superior direito e selecione C++/WinRT para exibir blocos de sintaxe de API conforme eles aparecem na projeção de linguagem C++/WinRT.

Suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e o pacote NuGet

Para obter suporte do Visual Studio, você precisará do Visual Studio 2022 ou do Visual Studio 2019 ou do Visual Studio 2017 (pelo menos a versão 15.6; recomendamos pelo menos 15.7). No Instalador do Visual Studio, instale a carga de trabalho de desenvolvimento da Plataforma Universal do Windows . Em Detalhes de Instalação>para desenvolvimento na Plataforma Universal do Windows, marque a opção Ferramentas C++ (v14x) para Plataforma Universal do Windows se ainda não tiver feito isso. E, em Windows Configurações>Privacidade e segurança (Windows 10: Atualização e Segurança) >para desenvolvedores, habilite a opção modo Desenvolvedor (Windows 10: não a opção Carregar aplicativos em modo livre).

Embora seja recomendável desenvolver com as versões mais recentes do Visual Studio e do SDK do Windows, se você estiver usando uma versão do C++/WinRT que foi enviada com o SDK do Windows antes da 10.0.17763.0 (Windows 10, versão 1809), então, para usar os cabeçalhos de namespaces do Windows mencionados acima, você precisará de uma versão de destino mínima do SDK do Windows em seu projeto de 10.0.17134.0 (Windows 10, versão 1803).

O Visual Studio 2022 é fornecido com modelos de projeto e item do C++/WinRT integrados, para que você possa começar a usar o desenvolvimento do C++/WinRT imediatamente. Ele também oferece visualização de depuração nativa (natvis) dos tipos projetados do C++/WinRT no Visual Studio, proporcionando uma experiência semelhante à depuração de C#. O Natvis é automático para compilações de depuração. Para obter mais informações, consulte visualização de depuração nativa do Visual Studio para C++/WinRT.

Para versões mais antigas do Visual Studio, você desejará baixar e instalar a versão mais recente do do VSIX (C++/WinRT Visual Studio Extension) do do Visual Studio Marketplace.

  • A extensão VSIX fornece modelos de projeto e de itens do C++/WinRT no Visual Studio.
  • Além disso, ele oferece visualização nativa de depuração (natvis) dos tipos projetados C++/WinRT no Visual Studio.

Os modelos de projeto do Visual Studio para C++/WinRT são descritos nas seções abaixo. Quando você cria um novo projeto C++/WinRT com a versão mais recente da extensão VSIX instalada, o novo projeto C++/WinRT instala automaticamente o pacote NuGet Microsoft.Windows.CppWinRT. O pacote NuGet Microsoft.Windows.CppWinRT fornece suporte à compilação do C++/WinRT (propriedades e alvos do MSBuild), tornando seu projeto portátil entre um computador de desenvolvimento e um agente de build (no qual apenas o pacote NuGet, e não a extensão VSIX, está instalado).

Como alternativa, você pode converter um projeto existente instalando manualmente o pacote NuGet Microsoft.Windows.CppWinRT. Depois de instalar (ou atualizar para) a versão mais recente da extensão VSIX, abra o projeto existente no Visual Studio, clique em Projeto>Gerenciar Pacotes NuGet...>Procurar, digite ou cole Microsoft.Windows.CppWinRT na caixa de pesquisa, selecione o item nos resultados da pesquisa e clique em Instalar para instalar o pacote para esse projeto. Depois de adicionar o pacote, você obterá suporte do C++/WinRT MSBuild para o projeto, incluindo a invocação da ferramenta cppwinrt.exe.

Importante

Se você tiver projetos que foram criados com (ou atualizados para trabalhar com) uma versão da extensão VSIX anterior à 1.0.190128.4, então consulte a seção Versões anteriores da extensão VSIX. Essa seção contém informações importantes sobre a configuração de seus projetos, que você precisará saber para atualizá-los para usar a versão mais recente da extensão VSIX.

  • Como o C++/WinRT usa recursos do padrão C++17, o pacote NuGet define a propriedade do projeto C/C++LanguageC++ Language StandardISO C++17 Standard (/std:c++17) no Visual Studio.
  • Ele também adiciona a opção do compilador /bigobj.
  • Ele adiciona a opção do compilador /await para habilitar co_await.
  • Ele instrui o compilador XAML a emitir o codegen C++/WinRT.
  • Você também pode querer definir modo de conformidade: sim (/permissive-), o que restringe ainda mais seu código para ser compatível com os padrões.
  • Outra propriedade do projeto a ser observada é >Geral do C/C++>Tratar avisos como erros. Defina isso como Sim(/WX) ou não (/WX-) a gosto. Às vezes, os arquivos de origem gerados pela ferramenta cppwinrt.exe geram avisos até que você adicione sua implementação a eles.

Com o sistema configurado conforme descrito acima, você poderá criar e criar ou abrir um projeto C++/WinRT no Visual Studio e implantá-lo.

A partir da versão 2.0, o pacote NuGet Microsoft.Windows.CppWinRT inclui a ferramenta cppwinrt.exe. Você pode apontar a ferramenta cppwinrt.exe para um arquivo de metadados do Windows Runtime (.winmd) para gerar uma biblioteca padrão C++ baseada em arquivos de cabeçalho que projeta as APIs descritas nos metadados para serem consumidas pelo código C++/WinRT em projetos . Os arquivos de metadados do Windows Runtime (.winmd) fornecem uma maneira canônica de descrever uma superfície da API do Windows Runtime. Ao apontar cppwinrt.exe para metadados, você pode gerar uma biblioteca para uso com qualquer classe de runtime implementada em um componente do Windows Runtime de segunda ou terceira parte, ou implementada em seu próprio aplicativo. Para obter mais informações, consulte Consumir APIs com C++/WinRT.

Com o C++/WinRT, você também pode implementar suas próprias classes de runtime usando C++padrão, sem recorrer à programação no estilo COM. Para uma classe de runtime, basta descrever seus tipos em um arquivo IDL e midl.exe e cppwinrt.exe gerar seus arquivos de código-fonte clichê de implementação para você. Como alternativa, você pode apenas implementar interfaces derivando de uma classe base C++/WinRT. Para obter mais informações, consulte Criar APIs com C++/WinRT.

Para obter uma lista de opções de personalização para a ferramenta cppwinrt.exe, configuradas através das propriedades do projeto, consulte o arquivo readme do pacote NuGet Microsoft.Windows.CppWinRT .

Você pode identificar um projeto que usa o suporte do MSBuild do C++/WinRT pela presença do Microsoft.Windows.CppWinRT pacote NuGet instalado no projeto.

Aqui estão os modelos de projeto do Visual Studio fornecidos pela extensão VSIX.

Aplicativo em branco (C++/WinRT)

Um modelo de projeto para um aplicativo UWP (Plataforma Universal do Windows) que tem uma interface do usuário XAML.

O Visual Studio fornece suporte ao compilador XAML para gerar stubs de implementação e cabeçalho do arquivo IDL (Linguagem de Definição de Interface) (.idl) que fica atrás de cada arquivo de marcação XAML. Em um arquivo IDL, defina as classes de runtime locais que você deseja referenciar nas páginas XAML do aplicativo e crie o projeto uma vez para gerar modelos de implementação em Generated Filese definições de tipo stub em Generated Files\sources. Em seguida, use essas definições de tipo stub para referência para implementar suas classes de runtime locais. Consulte as classes de runtime do Factoring em arquivos Midl (.idl).

O suporte à superfície de design XAML no Visual Studio para C++/WinRT está próximo da paridade com C#. No Visual Studio, você pode usar a guia Eventos da janela Propriedades do para adicionar manipuladores de eventos em um projeto C++/WinRT. Você também pode adicionar manipuladores de eventos ao código manualmente, consulte Manipular eventos usando delegados no C++/WinRT para obter mais informações.

Aplicativo Principal (C++/WinRT)

Um modelo de projeto para um aplicativo UWP (Plataforma Universal do Windows) que não usa XAML.

Em vez disso, ele usa o cabeçalho de namespace do Windows C++/WinRT para o namespace Windows.ApplicationModel.Core. Depois de compilar e executar, clique em um espaço vazio para adicionar um quadrado colorido; em seguida, clique em um quadrado colorido para arrastá-lo.

Aplicativo do Console do Windows (C++/WinRT)

Um modelo de projeto para um aplicativo cliente C++/WinRT para a Área de Trabalho do Windows, com uma interface do usuário do console.

Aplicativo da Área de Trabalho do Windows (C++/WinRT)

Um modelo de projeto para um aplicativo cliente C++/WinRT para a Área de Trabalho do Windows, que exibe um Windows Runtime Windows.Foundation.Uri dentro de umMessageBox Win32.

Componente do Windows Runtime (C++/WinRT)

Um modelo de projeto para um componente; geralmente para uso em uma Plataforma Universal do Windows (UWP).

Este modelo demonstra a cadeia de ferramentas midl.exe>cppwinrt.exe, em que os metadados do Windows Runtime (.winmd) são gerados a partir da IDL e, em seguida, os stubs de implementação e cabeçalho são gerados a partir dos metadados do Windows Runtime.

Em um arquivo IDL, defina as classes de runtime em seu componente, sua interface padrão e quaisquer outras interfaces que implementem. Crie o projeto uma vez para gerar module.g.cpp, module.h.cpp, modelos de implementação em Generated Filese definições de tipo stub em Generated Files\sources. Em seguida, use essas definições de tipo stub para referência para implementar as classes de runtime em seu componente. Consulte as classes de runtime do Factoring em arquivos Midl (.idl).

Agrupe o binário do componente Windows Runtime compilado e seu .winmd com o aplicativo UWP que os consome.

Versões anteriores da extensão VSIX

Recomendamos que você instale (ou atualize para) a versão mais recente da extensão VSIX. Ele é configurado para se atualizar por padrão. Se você fizer isso e tiver projetos que foram criados com uma versão da extensão VSIX anterior à 1.0.190128.4, esta seção conterá informações importantes sobre como atualizar esses projetos para trabalhar com a nova versão. Se você não atualizar, ainda encontrará as informações nesta seção úteis.

Em termos de versões compatíveis do SDK do Windows e do Visual Studio, bem como da configuração do Visual Studio, as informações na seção sobre o suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e o pacote NuGet, mencionada acima, se aplicam a versões anteriores dessas extensões. As informações abaixo descrevem diferenças importantes em relação ao comportamento e à configuração de projetos criados com (ou atualizados para trabalhar com) versões anteriores.

Criado anteriormente à 1.0.181002.2

Se o projeto foi criado com uma versão da extensão VSIX anterior à 1.0.181002.2, o suporte ao build do C++/WinRT foi integrado a essa versão da extensão VSIX. Seu projeto tem a propriedade <CppWinRTEnabled>true</CppWinRTEnabled> definida no arquivo .vcxproj.

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

Você pode atualizar seu projeto instalando manualmente o pacote NuGet Microsoft.Windows.CppWinRT. Depois de instalar (ou atualizar para) a versão mais recente da extensão VSIX, abra seu projeto no Visual Studio, clique em Projeto>Gerenciar Pacotes NuGet...>Procurar, digite ou cole microsoft.Windows.CppWinRT na caixa de pesquisa, selecione o item nos resultados da pesquisa e clique em Instalar para instalar o pacote para seu projeto.

Criado com (ou atualizado para) entre 1.0.181002.2 e 1.0.190128.3

Se o projeto foi criado com uma versão da extensão VSIX entre 1.0.181002.2 e 1.0.190128.3, inclusive, o pacote Microsoft.Windows.CppWinRT NuGet foi instalado no projeto automaticamente pelo modelo de projeto. Você também pode ter atualizado um projeto mais antigo para usar uma versão da extensão VSIX nesse intervalo. Se você fez isso, então, visto que o suporte ao build ainda estava presente nas versões da extensão VSIX nesse intervalo, é possível que o seu projeto atualizado tenha ou não o pacote NuGet Microsoft.Windows.CppWinRT instalado.

Para atualizar seu projeto, siga as instruções na seção anterior e verifique se o projeto tem o Microsoft.Windows.CppWinRT pacote NuGet instalado.

Configurações de atualização inválidas

Com a versão mais recente da extensão VSIX, não é válido que um projeto tenha a propriedade <CppWinRTEnabled>true</CppWinRTEnabled> se não tiver o pacote Microsoft.Windows.CppWinRT NuGet instalado. Um projeto com essa configuração produz a seguinte mensagem de erro de compilação: "O VSIX do C++/WinRT não fornece mais suporte à compilação do projeto. Adicione uma referência de projeto ao pacote Nuget Microsoft.Windows.CppWinRT."

Conforme mencionado acima, um projeto C++/WinRT agora precisa ter o pacote NuGet instalado nele.

Como o elemento <CppWinRTEnabled> agora está obsoleto, opcionalmente, você pode editar o .vcxproje excluir o elemento. Não é estritamente necessário, mas é uma opção.

Além disso, se o .vcxproj contiver <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, você poderá removê-lo para que possa compilar sem exigir que a extensão VSIX do C++/WinRT seja instalada.

Suporte do SDK para C++/WinRT

Embora agora esteja presente apenas por motivos de compatibilidade, a partir da versão 10.0.17134.0 (Windows 10, versão 1803), o SDK do Windows contém uma biblioteca C++ padrão baseada em arquivo de cabeçalho para consumir APIs do Windows de primeira parte (APIs do Windows Runtime em namespaces do Windows). Esses cabeçalhos estão dentro da pasta %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. A partir do SDK do Windows versão 10.0.17763.0 (Windows 10, versão 1809), esses cabeçalhos são gerados para você dentro da pasta $(GeneratedFilesDir) do seu projeto.

Novamente para compatibilidade, o SDK do Windows também vem com a ferramenta cppwinrt.exe. No entanto, recomendamos que você instale e use a versão mais recente do cppwinrt.exe, que está incluída no pacote NuGet Microsoft.Windows.CppWinRT. Esse pacote e cppwinrt.exesão descritos nas seções acima.

Tipos personalizados na projeção C++/WinRT

Em sua programação C++/WinRT, você pode usar recursos de linguagem padrão C++ e tipos de dados padrão C++ e C++/WinRT— incluindo alguns tipos de dados da Biblioteca Padrão C++. Mas você também estará ciente de alguns tipos de dados personalizados na projeção e poderá optar por usá-los. Por exemplo, usamos winrt::hstring no exemplo de código de início rápido em Introdução ao C++/WinRT.

winrt::com_array é outro tipo que você provavelmente usará em algum momento. Mas é menos provável que você use diretamente um tipo como winrt::array_view. Ou você pode optar por não usá-lo para não ter nenhum código a ser alterado se e quando um tipo equivalente aparecer na Biblioteca Padrão C++.

Aviso

Também há tipos que você poderá ver se estudar de perto os cabeçalhos de namespace do Windows C++/WinRT. Um exemplo é winrt::param::hstring, mas também há exemplos de coleção. Elas existem apenas para otimizar a associação de parâmetros de entrada e geram grandes melhorias de desempenho e fazem com que a maioria dos padrões de chamada "apenas funcione" para tipos e contêineres C++ padrão relacionados. Esses tipos só são usados pela projeção nos casos em que eles adicionam mais valor. Eles são altamente otimizados e não são para uso geral; não fique tentado a usá-los por conta própria. Também não deve usar nada do namespace winrt::impl, pois são tipos de implementação e, portanto, sujeitos a alterações. Você deve continuar a usar tipos padrão ou tipos do namespace winrt.

Veja também Passando parâmetros para o limite da ABI.

APIs importantes

  • Last updated on