Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
C++/WinRT é uma projeção de linguagem C++17 moderna totalmente padrão para APIs do Tempo de Execução do Windows (WinRT), 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 Tempo de Execução do Windows 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).
O C++/WinRT é o substituto recomendado pela Microsoft para a projeção da linguagem C++/CX e a Biblioteca de Modelos C++ do Tempo de Execução do Windows (WRL) . A lista completa de tópicos sobre C++/WinRT inclui informações sobre como interoperar com e a migração de C++/CX e WRL.
Importante
Algumas das partes mais importantes do C++/WinRT a serem observadas são descritas nas seções suporte SDK para C++/WinRT e suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e o pacote NuGet.
Consulte também Onde posso encontrar aplicativos de exemplo C++/WinRT?.
Projeções linguísticas
O Runtime do Windows é baseado nas APIs do Modelo de Objeto Componente (COM) e foi projetado para ser acessado 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 no conteúdo de referência da API do Runtime do Windows
Quando estiver navegando
Suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e o pacote NuGet
Para suporte ao Visual Studio, você 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). De dentro do Visual Studio Installer, instale a carga de trabalho desenvolvimento de Plataforma Universal do Windows. Em Detalhes da Instalação de desenvolvimento da Plataforma Universal do Windows>, marque a(s) opção(ões) para as ferramentas C++ (v14x) da Plataforma Universal do Windows, caso ainda não tenha feito isso. E, em Configurações do> WindowsPrivacidade e segurança (Windows 10: Atualização & Segurança) >Para desenvolvedores, habilite a opção Modo de desenvolvedor (Windows 10: não a opção Sideload apps).
Embora seja recomendável que você desenvolva com as versões mais recentes do Visual Studio e do SDK do Windows, se você estiver usando uma versão do C++/WinRT fornecida 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 mínima de destino 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 C++/WinRT integrados, para que você possa começar a desenvolver C++/WinRT imediatamente. Inclui também a visualização nativa de depuração do Visual Studio (natvis) para tipos projetados em C++/WinRT, proporcionando uma experiência semelhante à depuração em C#. 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, convém baixar e instalar a versão mais recente do
- A extensão VSIX fornece modelos de projeto e de item C++/WinRT no Visual Studio.
- Além disso, proporciona a visualização nativa de depuração do Visual Studio (natvis) para tipos projetados em C++/WinRT.
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 do Microsoft.Windows.CppWinRT fornece suporte à compilação C++/WinRT (propriedades e alvos do MSBuild), tornando o seu projeto portátil 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).
Como alternativa, você pode converter um projeto existente instalando manualmente o pacote Microsoft.Windows.CppWinRT NuGet. 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, 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 desse projeto. Depois de adicionar o pacote, receberá suporte ao 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 a 1.0.190128.4, consulte 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 utiliza funcionalidades do padrão C++17, o pacote NuGet configura a propriedade do projeto >C/C++ Language>C++ Language Standard>ISO C++17 Standard (/std:c++17) no Visual Studio.
- Ele também adiciona a opção de compilador /bigobj.
- Ele adiciona a opção de compilador /await para habilitar
co_await. - Ele instrui o compilador XAML a gerar código C++/WinRT.
- Você também pode querer definir modo de conformidade: Sim (/permissive-), o que restringe ainda mais seu código a ser compatível com os padrões.
- Outra propriedade de projeto a ser observada é C/C++>Geral>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.exegeram avisos até que você adicione sua implementação a eles.
Com seu sistema configurado conforme descrito acima, você poderá criar e compilar, ou abrir, um projeto C++/WinRT no Visual Studio e implantá-lo.
A partir da versão 2.0, o pacote Microsoft.Windows.CppWinRT NuGet inclui a ferramenta cppwinrt.exe. Você pode apontar a ferramenta cppwinrt.exe para um arquivo de metadados do Tempo de Execução do Windows (.winmd) para gerar uma biblioteca C++ padrão baseada em arquivo de cabeçalho que projetos APIs descritas nos metadados para consumo do código C++/WinRT. Os arquivos de metadados do Windows Runtime (.winmd) fornecem uma maneira padrão de descrever uma API do Windows Runtime. Ao apontar cppwinrt.exe para metadados, pode-se gerar uma biblioteca para uso com qualquer classe de tempo de execução implementada num componente Windows Runtime de uma segunda ou terceira parte, ou implementada na sua própria aplicação. Para obter mais informações, consulte Utilizar APIs com C++/WinRT.
Com C++/WinRT, você também pode implementar suas próprias classes de tempo de execução usando C++ padrão, sem recorrer à programação no estilo COM. Para uma classe em tempo de execução, basta descrever os seus tipos num ficheiro IDL e midl.exe e cppwinrt.exe geram os seus ficheiros de código-fonte base de implementação para si. Como alternativa, você pode apenas implementar interfaces derivando de uma classe base C++/WinRT. Para mais informações, veja APIs de Autor com C++/WinRT.
Para obter uma lista de opções de personalização para a ferramenta cppwinrt.exe, definida por meio das propriedades do projeto, consulte o pacote NuGet Microsoft.Windows.CppWinRT Readme.
Você pode identificar um projeto que usa o suporte a C++/WinRT MSBuild 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.
Aplicação Vazia (C++/WinRT)
Um modelo de projeto para um aplicativo da Plataforma Universal do Windows (UWP) que tem uma interface de usuário XAML.
O Visual Studio fornece suporte a compiladores XAML para gerar stubs de implementação e cabeçalho a partir do arquivo IDL (Interface Definition Language) (.idl) que fica atrás de cada arquivo de marcação XAML. Em um arquivo IDL, defina quaisquer classes de tempo de execução locais que você deseja referenciar nas páginas XAML do seu aplicativo e, em seguida, crie o projeto uma vez para gerar modelos de implementação em Generated Filese definições de tipo de stub em Generated Files\sources. Em seguida, use essas definições de tipo de stub como referência para implementar suas classes de tempo de execução locais. Consulte Fatoração de classes de tempo de execução em ficheiros 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 para adicionar manipuladores de eventos em um projeto C++/WinRT. Você também pode adicionar manipuladores de eventos ao seu código manualmente — consulte Manipular eventos usando delegados em C++/WinRT para obter mais informações.
Aplicativo principal (C++/WinRT)
Um modelo de projeto para um aplicativo da Plataforma Universal do Windows (UWP) 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 construir e executar, clique em um espaço vazio para adicionar um quadrado colorido; Em seguida, clique em um quadrado colorido para arrastá-lo.
Aplicativo de Console do Windows (C++/WinRT)
Um modelo de projeto para um aplicativo cliente C++/WinRT para Windows Desktop, com uma interface de usuário de console.
Aplicativo de área de trabalho do Windows (C++/WinRT)
Um modelo de projeto para uma aplicação cliente C++/WinRT para o Windows Desktop, que mostra um Windows Runtime Windows.Foundation.Uri dentro de um Win32 MessageBox.
Componente do Tempo de Execução do Windows (C++/WinRT)
Um modelo de projeto para um componente; normalmente para consumo a partir de uma Plataforma Universal do Windows (UWP).
Este modelo demonstra a cadeia de ferramentas midl.exe>cppwinrt.exe, onde os metadados do Tempo de Execução do Windows (.winmd) são gerados a partir do IDL e, em seguida, a implementação e os stubs de cabeçalho são gerados a partir dos metadados do Tempo de Execução do Windows.
Em um arquivo IDL, defina as classes de tempo de execução 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 de stub em Generated Files\sources. Em seguida, use essas definições de tipo de stub como referência para implementar as classes de tempo de execução em seu componente. Consulte Fatoração de classes de tempo de execução em ficheiros Midl (.idl).
Agrupe o binário do componente do Tempo de Execução do Windows criado e seus .winmd com o aplicativo UWP consumindo-os.
Versões anteriores da extensão VSIX
Recomendamos que se instale (ou atualize para) a extensão VSIX na versão mais recente. Ele está 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 a 1.0.190128.4, esta seção contém informações importantes sobre como atualizar esses projetos para trabalhar com a nova versão. Se você não atualizar, ainda achará as informações nesta seção úteis.
Em termos de versões suportadas do Windows SDK e Visual Studio e configuração do Visual Studio, as informações na seção suporte do Visual Studio para C++/WinRT, XAML, a extensão VSIX e o pacote NuGet acima se aplicam a versões anteriores da extensão VSIX. As informações abaixo descrevem diferenças importantes em relação ao comportamento e configuração de projetos criados com (ou atualizados para trabalhar) 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 a 1.0.181002.2, o suporte à compilação C++/WinRT foi incorporado nessa 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 Microsoft.Windows.CppWinRT NuGet. Depois de instalar (ou atualizar para) a versão mais recente da extensão VSIX, abra seu projeto no Visual Studio, clique em Project>Manage NuGet Packages...>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 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 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ê o fez, então, como o suporte à compilação também ainda estava presente em versões da extensão VSIX nesse intervalo, seu projeto atualizado pode ou não ter o pacote Microsoft.Windows.CppWinRT NuGet instalado.
Para atualizar seu projeto, siga as instruções na seção anterior e verifique se o projeto tem o pacote Microsoft.Windows.CppWinRT NuGet instalado.
Configurações de atualização inválidas
Com a versão mais recente da extensão VSIX, não é válido para um projeto ter a propriedade <CppWinRTEnabled>true</CppWinRTEnabled> se ele também não tiver o pacote Microsoft.Windows.CppWinRT NuGet instalado. Um projeto com essa configuração produz a mensagem de erro de compilação, "O C++/WinRT VSIX não fornece mais suporte à compilação do projeto. Adicione uma referência de projeto ao pacote Nuget Microsoft.Windows.CppWinRT."
Como mencionado acima, um projeto C++/WinRT agora precisa ter o pacote NuGet instalado nele.
Como o elemento <CppWinRTEnabled> agora está obsoleto, você pode, opcionalmente, editar seu .vcxproje excluir o elemento. Não é estritamente necessário, mas é uma opção.
Além disso, se o seu .vcxproj contiver <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, então você pode removê-lo para que você possa construir sem exigir que a extensão C++/WinRT VSIX seja instalada.
Suporte 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 Tempo de Execução do Windows 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 SDK do Windows (Windows 10, versão 1809), estes cabeçalhos são gerados automaticamente na pasta $(GeneratedFilesDir) do seu projeto.
Novamente para compatibilidade, o SDK do Windows também vem com a ferramenta cppwinrt.exe. No entanto, recomendamos que, em vez disso, você instale e use a versão mais recente do cppwinrt.exe, que está incluído no pacote Microsoft.Windows.CppWinRT NuGet. Esse pacote, e cppwinrt.exe, sã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 C++ padrão e tipos de dados C++ padrão eC++/WinRT — incluindo alguns tipos de dados C++ Standard Library. Mas você também conhecerá 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 que você não terá nenhum código para alterar se e quando um tipo equivalente aparecer na Biblioteca Padrão C++.
Advertência
Há também tipos que você pode 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. Eles existem apenas para otimizar a ligação de parâmetros de entrada, e eles produzem grandes melhorias de desempenho e fazem com que a maioria dos padrões de chamada "simplesmente funcione" para tipos e contêineres C++ padrão relacionados. Esses tipos só são utilizados pela projeção nos casos em que agregam mais valor. Eles são altamente otimizados e não são para uso geral; Não se sinta tentado a usá-los você mesmo. Também não deve usar nada do namespace winrt::impl, já que esses são tipos de implementação e, portanto, estão sujeitos a alterações. Você deve continuar a usar tipos padrão ou tipos do namespace winrt.
Consulte também Passagem de parâmetros através da fronteira ABI.
APIs importantes
- winrt::hstring struct
- de namespace winrt