WRL (Biblioteca de Modelos C++ do Tempo de Execução do Windows)

  • Artigo

A WRL (Biblioteca de Modelos C++ do Tempo de Execução do Windows) é uma biblioteca de modelos que fornece uma maneira de baixo nível para criar e usar componente do Windows Runtime.

Observação

O WRL foi substituído pelo C++/WinRT, uma projeção de linguagem C++17 padrão para APIs de Windows Runtime. C++/WinRT está disponível no SDK do Windows a partir da versão 1803 (10.0.17134.0) em diante. C++/WinRT é implementado inteiramente em arquivos de cabeçalho e foi projetado para fornecer acesso de primeira classe à API moderna do Windows.

Com o C++/WinRT, você pode consumir e criar APIs do Windows Runtime usando qualquer compilador C++17 em conformidade com os padrões. Normalmente o C++/WinRT tem melhor desempenho e produz binários menores do que qualquer outra opção de idioma para o Windows Runtime. Continuaremos a dar suporte a C++/CX e WRL, mas recomendamos que os novos aplicativos usem o C++/WinRT. Para obter mais informações, confira C++/WinRT.

Benefícios

A Biblioteca de Modelos do Windows Runtime C++ permite implementar e consumir componentes COM (Component Object Model) com mais facilidade. Ela fornece técnicas de limpeza, como contagem de referências para gerenciar o tempo de vida de objetos e testar valores HRESULT para determinar se uma operação foi bem-sucedida ou falhou. Para usar com êxito a Biblioteca de Modelos do Windows Runtime C++, você precisa seguir cuidadosamente essas regras e técnicas.

O C++/CX é uma maneira baseada em linguagem de alto nível de usar componente do Windows Runtime. A Biblioteca de Modelos do Windows Runtime C++ e o C++/CX simplificam a gravação do código para o Windows Runtime executando automaticamente tarefas de limpeza em seu nome.

A Biblioteca de Modelos do Windows Runtime C++ e o C++/CX oferecem benefícios diferentes. Veja alguns motivos pelos quais talvez você queira usar a Biblioteca de Modelos do Windows Runtime C++ em vez de C++/CX:

  • A Biblioteca de Modelos do Windows Runtime C++ adiciona pouca abstração sobre a ABI (Interface Binária do Aplicativo) do Windows Runtime, oferecendo a capacidade de controlar o código subjacente para criar ou consumir melhor as APIs do Windows Runtime.

  • C++/CX representa valores COM HRESULT como exceções. Se você herdou uma base de código que usa COM ou uma que não usa exceções, talvez ache que a Biblioteca de Modelos C++ do Tempo de Execução do Windows é uma maneira mais natural de trabalhar com o Tempo de Execução do Windows, pois você não precisa usar exceções.

    Observação

    A Biblioteca de Modelos do Windows Runtime C++ usa valores HRESULT e não gera exceções. Além disso, a Biblioteca de Modelos do Windows Runtime C++ usa ponteiros inteligentes e o padrão RAII para ajudar a garantir que os objetos sejam destruídos corretamente quando o código do aplicativo gera uma exceção. Para obter mais informações sobre ponteiros inteligentes e RAII, consulte Ponteiros inteligentes e Recursos de objetos próprios (RAII).

  • A finalidade e o design da Biblioteca de Modelos do Windows Runtime C++ são inspirados na ATL (Biblioteca de Modelos Ativos), que é um conjunto de classes C++ baseadas em modelo que simplificam a programação de objetos COM. Como Biblioteca de Modelos do Windows Runtime C++ usa o C++ padrão para encapsular o Windows Runtime, você pode portar e interagir com muitos componentes COM existentes gravados na ATL no Windows Runtime. Se você já conhece a ATL, pode achar que a programação da Biblioteca de Modelos do Windows Runtime C++ é mais fácil.

Introdução

Veja aqui alguns recursos que podem ajudar a começar a trabalhar com a Biblioteca de Modelos do Windows Runtime C++ imediatamente.

Como ativar e usar um componente do Tempo de Execução do Windows
Mostra como usar a Biblioteca de Modelos de Windows Runtime C++ para inicializar o Windows Runtime e ativar e usar um componente Windows Runtime.

Como: Concluir operações assíncronas
Mostra como usar a Biblioteca de Modelos do Windows Runtime C++ para iniciar operações assíncronas e executar o trabalho quando as operações forem concluídas.

Como: Manipular eventos
Mostra como usar a Biblioteca de Modelos do Windows Runtime C++ para assinar e manipular os eventos de um objeto do Windows Runtime.

Passo a passo: criando um aplicativo UWP usando WRL e Media Foundation
Saiba como criar um aplicativo UWP que usa o Microsoft Media Foundation.

Como: Criar um componente COM clássico
Mostra como usar a Biblioteca de Modelos do Windows Runtime C++ para criar um componente COM básico e uma maneira básica de registrar e consumir o componente COM de um aplicativo da área de trabalho.

Como instanciar componentes da WRL diretamente
Saiba como usar as funções Microsoft::WRL::Make e Microsoft::WRL::Details::MakeAndInitialize para instanciar um componente do módulo que o define.

Como usar winmdidl.exe e midlrt.exe para criar arquivos .h com metadados do Windows
Mostra como consumir componentes de Windows Runtime personalizados do WRL criando um arquivo IDL dos metadados .winmd.

Instruções passo a passo: conexão usando tarefas e solicitações HTTP XML
Mostra como usar as interfaces IXMLHTTPRequest2 e IXMLHTTPRequest2Callback junto com tarefas para enviar solicitações HTTP GET e POST para um serviço Web em um aplicativo UWP.

Amostra de Otimizador de viagens do Bing Mapas
Usa a classe HttpRequest definida em Passo a passo: Conectando usando tarefas e solicitações HTTP XML no contexto de um aplicativo UWP completo.

Amostra de Criando um componente DLL Windows Runtime com exemplo de C++
Mostra como usar a Biblioteca de Modelos do Windows Runtime C++ para criar um componente DLL em processo e consumi-lo de C++/CX, JavaScript e C#.

Amostra de jogo de labirinto de mármore em DirectX
Demonstra como usar a Biblioteca de Modelos do Windows Runtime C++ para gerenciar o tempo de vida de componentes COM, como DirectX e Media Foundation, no contexto de um jogo 3D completo.

Notificações do sistema de aplicativos da área de trabalho
Demonstra como enviar notificações do sistema por meio de um aplicativo da área de trabalho.

Biblioteca de Modelos do Windows Runtime C++ em comparação com ATL

A Biblioteca de Modelos do Windows Runtime C++ é semelhante à ATL (Active Template Library) porque você pode usá-la para criar objetos COM pequenos e rápidos. A Biblioteca de Modelos do Windows Runtime C++ e a ATL também compartilham conceitos como definição de objetos em módulos, registro explícito de interfaces e criação aberta de objetos usando fábricas. Você pode estar confortável com Biblioteca de Modelos do Windows Runtime C++ se estiver familiarizado com a ATL.

A Biblioteca de Modelos do Windows Runtime C++ permite a funcionalidade COM necessária para aplicativos UWP. Portanto, ela é diferente da ATL porque omite o suporte direto para recursos COM, como:

  • agregação

  • implementações de estoque

  • interfaces duplas (IDispatch)

  • interfaces de enumerador padrão

  • pontos de conexão

  • interfaces destacáveis

  • inserção de OLE

  • Controles ActiveX

  • COM+

Conceitos

A Biblioteca de Modelos do Windows Runtime C++ fornece tipos que representam alguns conceitos básicos. As seções a seguir descrevem esses tipos.

ComPtr

ComPtr é um tipo de ponteiro inteligente que representa a interface especificada pelo parâmetro de modelo. Use ComPtr para declarar uma variável que pode acessar os membros de um objeto derivado da interface. ComPtr mantém automaticamente uma contagem de referência para o ponteiro de interface subjacente e libera a interface quando a contagem de referência alcança zero.

RuntimeClass

RuntimeClass representa uma classe instanciada que herda um conjunto de interfaces especificadas. Um objeto RuntimeClass pode fornecer uma combinação de suporte para uma ou mais interfaces COM do Windows Runtime ou uma referência fraca a um componente.

Módulo

Module representa uma coleção de objetos relacionados. Um objeto Module gerencia fábricas de classes, que criam objetos e registro, o que permite que outros aplicativos usem um objeto.

Retorno de Chamada

A função Retorno de chamada cria um objeto cuja função de membro é um manipulador de eventos (um método de retorno de chamada). Use a função Callback para gravar operações assíncronas.

EventSource

EventSource é usado para gerenciar manipuladores de eventos delegados . Use a Biblioteca de Modelos do Windows Runtime C++ para implementar um delegado e usar EventSource para adicionar, remover e invocar delegados.

AsyncBase

O AsyncBase fornece métodos virtuais que representam o modelo de programação assíncrona Windows Runtime. Substitua os membros nesta classe para criar uma classe personalizada que possa iniciar, parar ou verificar o progresso de uma operação assíncrona.

FtmBase

FtmBase representa um objeto marshaler de thread livre. FtmBase cria uma GIT (tabela de interface global) e ajuda a gerenciar objetos de marshaling e proxy.

WeakRef

WeakRef é um tipo de ponteiro inteligente que representa uma referência fraca, que faz referência a um objeto que pode ou não estar acessível. Um objeto WeakRef pode ser usado apenas pelo Windows Runtime e não pelo COM clássico.

Um objeto WeakRef normalmente representa um objeto cuja existência é controlada por um thread ou aplicativo externo. Por exemplo, um objeto WeakRef pode fazer referência a um objeto de arquivo. Quando o arquivo está aberto, o arquivo WeakRef é válido e o arquivo referenciado fica acessível. Mas quando o arquivo é fechado, o arquivo WeakRef é inválido e o arquivo não está acessível.

Principais APIs por categoria
Realça os principais tipos, funções e macros da Biblioteca de Modelos do Windows Runtime C++.

Referência
Contém informações de referência para a Biblioteca de Modelos do Windows Runtime C++.

Referência rápida (C++/CX)
Descreve brevemente os recursos C++/CX que apoiam o Windows Runtime.

Usar componentes do Windows Runtime no Visual C++
Mostra como usar C++/CX para criar um componente básico do Windows Runtime.