Introdução ao C++/WinRT

C++/WinRT é uma linguagem moderna de projeção C++17 totalmente padrão para APIs Windows Runtime (WinRT), implementada como uma biblioteca baseada em ficheiros de cabeçalho e concebida para lhe proporcionar acesso de primeira classe à API moderna do Windows. Com C++/WinRT, pode criar e consumir APIs do Windows Runtime usando qualquer compilador C++17 compatível com os 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 é o substituto recomendado pela Microsoft para a projeção da linguagem C++/CX e para a Windows Runtime C++ Template Library (WRL). A lista completa de tópicos sobre C++/WinRT inclui informações quer sobre a interoperabilidade com o C++/CX e o WRL, quer sobre a migração a partir do C++/CX e do WRL.

Veja também Onde posso encontrar aplicações de exemplo em C++/WinRT?.

Projeções linguísticas

O Windows Runtime baseia-se em APIs do Component Object Model (COM) e foi concebido para ser acedido através de projeções de linguagem. Uma projeção oculta os detalhes do COM e fornece uma experiência de programação mais natural para uma determinada linguagem.

A projeção da linguagem C++/WinRT na API do Windows Runtime referencia o conteúdo

Quando estiver a navegar por APIs do Windows Runtime, clique na caixa de combinação de Linguagem no canto superior direito e selecione C++/WinRT para visualizar os blocos de sintaxe da API tal como aparecem na projeção da linguagem C++/WinRT.

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

Para suporte ao Visual Studio, vai precisar do Visual Studio 2022, ou Visual Studio 2019, ou Visual Studio 2017 (pelo menos a versão 15.6; recomendamos pelo menos a 15.7). No Visual Studio Installer, instale a carga de trabalho desenvolvimento da Plataforma Universal do Windows. Em Detalhes de Instalação>desenvolvimento da Plataforma Universal do Windows, selecione a(s) opção(ões) ferramentas da Plataforma Universal do Windows para C++ (v14x), caso ainda não o tenha feito. E, nas Definições>Privacidade e segurança do Windows (Windows 10: Atualização e Segurança) >Para programadores, ative a opção Modo de programador (Windows 10: não a opção Carregar aplicações lateralmente).

Embora recomendemos que desenvolva com as versões mais recentes do Visual Studio e do Windows SDK, se estiver a usar uma versão de C++/WinRT que veio com o Windows SDK anterior à 10.0.17763.0 (Windows 10, versão 1809), então, para usar os cabeçalhos dos namespaces do Windows mencionados acima, precisará de um mínimo Versão alvo do SDK do Windows no seu projeto 10.0.17134.0 (Windows 10, versão 1803).

O Visual Studio 2022 inclui templates de projetos e itens em C++/WinRT incorporados, para que possa começar o desenvolvimento em C++/WinRT de imediato. Também inclui visualização de depuração nativa (natvis) do Visual Studio de tipos projetados em C++/WinRT, o que proporciona uma experiência semelhante à depuração em C#. O Natvis está ativado automaticamente nas compilações de depuração. Para mais informações, consulte Visual Studio native debug visualization for C++/WinRT.

Para versões mais antigas do Visual Studio, deverá descarregar e instalar a versão mais recente da Extensão Visual Studio (VSIX) em C++/WinRT a partir do Visual Studio Marketplace.

• A extensão VSIX dá-te templates de projetos e itens em C++/WinRT no Visual Studio.
• Além disso, fornece-lhe a visualização nativa de depuração (natvis) do Visual Studio para tipos projetados em C++/WinRT.

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

Em alternativa, 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 Project>Manage NuGet Packages...>Procurar, escreva ou cole Microsoft.Windows.CppWinRT na caixa de pesquisa, selecione o item nos resultados da pesquisa e, em seguida, clique em Install para instalar o pacote para esse projeto. Depois de adicionares o pacote, receberás suporte do MSBuild para C++/WinRT no projeto, incluindo a invocação da ferramenta cppwinrt.exe.

• Como o C++/WinRT utiliza funcionalidades da norma C++17, o pacote NuGet define a propriedade do projeto C/C++>Linguagem>Norma da Linguagem C++>Norma ISO C++17 (/std:c++17) no Visual Studio.
• Também adiciona a opção de compilador /bigobj.
• Adiciona a opção do compilador /await para ativar co_await.
• Instrui o compilador XAML a emitir codegen C++/WinRT.
• Também pode querer definir o modo de conformidade: Sim (/permissivo-), o que limita ainda mais o seu código a ser compatível com os padrões.
• Outra propriedade do projeto a ter em conta é C/C++>Geral>Tratar avisos como erros. Define isto para Sim (/WX) ou Não (/WX-) ao gosto. Por vezes, ficheiros de origem gerados pela cppwinrt.exe ferramenta geram avisos até adicionares a tua implementação a eles.

Com o seu sistema configurado como descrito acima, poderá criar e construir, ou abrir, um projeto C++/WinRT no Visual Studio e implementá-lo.

A partir da versão 2.0, o pacote NuGet Microsoft.Windows.CppWinRT inclui a ferramenta cppwinrt.exe. Pode apontar a ferramenta cppwinrt.exe para um ficheiro de metadados do Windows Runtime (.winmd) para gerar uma biblioteca padrão de C++ baseada em ficheiros de cabeçalho que projeta as APIs descritas nos metadados para serem consumidas por código C++/WinRT. Os ficheiros de metadados (.winmd) do Windows Runtime fornecem uma forma canónica de descrever a superfície da API do Windows Runtime. Ao apontar cppwinrt.exe para metadados, pode gerar uma biblioteca para usar com qualquer classe de runtime implementada num componente Windows Runtime de segunda ou terceira parte, ou implementada na sua própria aplicação. Para mais informações, consulte Consume APIs com C++/WinRT.

Com C++/WinRT, também podes implementar as tuas próprias classes de runtime usando C++ padrão, sem recorrer à programação ao estilo COM. Para uma classe de tempo de execução, basta descrever os seus tipos num ficheiro IDL, e midl.exe e cppwinrt.exe geram os ficheiros de código-fonte base da implementação por si. Alternativamente, podes simplesmente implementar interfaces derivando de uma classe base C++/WinRT. Para mais informações, consulte APIs de autor com C++/WinRT.

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

Pode identificar um projeto que utiliza o suporte do MSBuild para C++/WinRT pela presença do pacote NuGet Microsoft.Windows.CppWinRT 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 uma aplicação Plataforma Universal do Windows (UWP) que tem uma interface de utilizador XAML. Para aplicações WinUI 3 de ambiente de trabalho, utilize antes o modelo Blank App, Packaged (WinUI 3 em Ambiente de Trabalho).

O Visual Studio fornece suporte a compiladores XAML para gerar stubs de implementação e cabeçalhos a partir do ficheiro Interface Definition Language (IDL) (.idl) que se encontra atrás de cada ficheiro de marcação XAML. Num ficheiro IDL, defina quaisquer classes de runtime local que queira referenciar nas páginas XAML da sua aplicação e depois construa o projeto uma vez para gerar templates de implementação em Generated Files, e definições de tipos de stub em Generated Files\sources. Depois usa essas definições de tipos de stub como referência para implementar as tuas classes locais de runtime. Veja Fatoração de classes de runtime em ficheiros Midl (.idl).

O suporte à superfície de design XAML no Visual Studio para C++/WinRT está próximo da paridade com o C#. No Visual Studio, podes usar o separador Eventos da janela de Propriedades para adicionar handlers de eventos dentro de um projeto C++/WinRT. Também pode adicionar handlers de eventos manualmente ao seu código — veja Gerenciar eventos usando delegates em C++/WinRT para mais informações.

Aplicativo principal (C++/WinRT)

Um modelo de projeto para uma aplicação da Plataforma Universal do Windows (UWP) que não usa XAML. Não existe um equivalente no WinUI 3 deste modelo.

Em vez disso, utiliza o ficheiro de cabeçalho do espaço de nomes Windows de C++/WinRT para o espaço de nomes Windows.ApplicationModel.Core. Depois de construir e executar, clique num espaço vazio para adicionar um quadrado colorido; Depois clica num quadrado colorido para arrastar.

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

Um modelo de projeto para uma aplicação cliente C++/WinRT para Windows Desktop, com uma interface de utilizador de consola.

Aplicativo de área de trabalho do Windows (C++/WinRT)

Um modelo de projeto para uma aplicação cliente C++/WinRT para Windows Desktop, que apresenta um Windows Windows Runtime. Foundation.Uri dentro de uma caixa de mensagens Win32.

Componente de Windows Runtime (C++/WinRT)

Um modelo de projeto para um componente; tipicamente para consumo a partir de uma Plataforma Universal do Windows (UWP).

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

Num ficheiro IDL, defina as classes de runtime no seu componente, a sua interface padrão e quaisquer outras interfaces que implementem. Construa o projeto uma vez para gerar module.g.cpp, module.h.cpp, templates de implementação em Generated Files, e definições de tipo stub em Generated Files\sources. Depois usa essas definições de tipos de stub como referência para implementar as classes de runtime no teu componente. Veja Fatoração de classes de runtime em ficheiros Midl (.idl).

Agrupa o binário do componente Windows Runtime compilado e o respetivo .winmd com a aplicação UWP que os consome.

Versões anteriores da extensão VSIX

Recomendamos que instale (ou atualize para) a versão mais recente da extensão VSIX. Está configurado para se atualizar automaticamente por defeito. Se fizeres isso, e tiveres projetos que foram criados com uma versão da extensão VSIX anterior à 1.0.190128.4, então esta secção contém informações importantes sobre como atualizar esses projetos para funcionarem com a nova versão. Se não atualizar, ainda assim achará útil a informação desta secção.

Em termos de versões suportadas do Windows SDK e Visual Studio, e da configuração do Visual Studio, a informação no suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e a secção do pacote NuGet acima aplicam-se a versões anteriores da extensão VSIX. A informação abaixo descreve diferenças importantes relativamente ao comportamento e configuração dos projetos criados com (ou atualizados para funcionar) versões anteriores.

Criado antes de 1.0.181002.2

Se o seu projeto foi criado com uma versão da extensão VSIX anterior à 1.0.181002.2, então o suporte de compilação C++/WinRT foi incorporado nessa versão da extensão VSIX. O teu projeto tem a <CppWinRTEnabled>true</CppWinRTEnabled> propriedade definida no .vcxproj ficheiro.

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

Pode atualizar o 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 o seu project no Visual Studio, clique em ProjectManage>NuGet Packages...>Navegar, escrever ou colar Microsoft.Windows. CppWinRT na caixa de pesquisa, selecione o item nos resultados de pesquisa e depois clique em Instalar para instalar o pacote do seu project.

Criado com (ou atualizado para) entre 1.0.181002.2 e 1.0.190128.3

Se o seu projeto foi criado com uma versão da extensão VSIX entre 1.0.181002.2 e 1.0.190128.3, inclusive, o pacote NuGet Microsoft.Windows.CppWinRT foi instalado automaticamente no projeto pelo modelo de projeto. Também pode ter atualizado um projeto mais antigo para usar uma versão da extensão VSIX nesta gama. Se o fez, então — uma vez que o suporte à compilação também ainda estava presente em versões da extensão VSIX neste intervalo — o seu projeto atualizado pode ou não ter instalado o pacote NuGet Microsoft.Windows.CppWinRT.

Para atualizar o seu projeto, siga as instruções da secção anterior e certifique-se de que o seu projeto tem o Microsoft.Windows. Pacote NuGet CppWinRT 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 também não tiver o pacote NuGet Microsoft.Windows.CppWinRT instalado. Um projeto com esta configuração produz a mensagem de erro de compilação: "O VSIX C++/WinRT já não fornece suporte para compilação de projetos. Por favor, adicione uma referência de projeto para o pacote NuGet Microsoft.Windows.CppWinRT.

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

Como o <CppWinRTEnabled> elemento está agora obsoleto, podes opcionalmente editar o teu .vcxproj, e apagar o elemento. Não é estritamente necessário, mas é uma opção.

Além disso, se o teu .vcxproj contém <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, podes removê-lo para que possas compilar sem precisar de instalar a extensão C++/WinRT VSIX.

Suporte a SDK para C++/WinRT

Embora agora esteja presente apenas por razões de compatibilidade, a partir da versão 10.0.17134.0 (Windows 10, versão 1803), o SDK do Windows contém uma biblioteca padrão C++ baseada em ficheiros 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 da versão 10.0.17763.0 do Windows SDK (Windows 10, versão 1809), estes cabeçalhos são gerados para si dentro da pasta $(GeneratedFilesDir) do seu projeto.

Mais uma vez, para compatibilidade, o SDK do Windows também vem com a cppwinrt.exe ferramenta. No entanto, recomendamos que, em vez disso, instale e utilize a versão mais recente de cppwinrt.exe, que está incluída no pacote NuGet Microsoft.Windows.CppWinRT. Esse pacote, e cppwinrt.exe, são descritos nas secções acima.

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

Na sua programação C++/WinRT, pode usar funcionalidades padrão da linguagem C++ e tipos de dados padrão C++ e C++/WinRT — incluindo alguns tipos de dados da Biblioteca Padrão C++. Mas também vais aperceber-te de alguns tipos de dados personalizados na projeção, e podes escolher usá-los. Por exemplo, usamos winrt::hstring no exemplo de código de início rápido em Get started with C++/WinRT.

winrt::com_array é outro tipo que provavelmente vais usar em algum momento. Mas é menos provável que uses diretamente um tipo como winrt::array_view. Ou pode optar por não o usar para não ter código a alterar caso e quando um tipo equivalente aparecer na Biblioteca Padrão C++.

APIs importantes

• winrt::hstring struct
• Espaço de nomes winrt

Tópicos relacionados

• C++/CX
• Extensão Visual Studio C++/WinRT (VSIX)
• Introdução ao C++/WinRT
• Tipos de dados padrão em C++ e C++/WinRT
• Gestão de strings em C++/WinRT
• APIs do Windows Runtime