Atributos C++ para COM e .NET

Artigo
04/03/2023

A Microsoft define um conjunto de atributos C++ que simplificam o desenvolvimento do .NET Framework Common Language Runtime e da programação COM. Quando você inclui atributos em seus arquivos de origem, o compilador funciona com DLLs de provedor para inserir código ou modificar o código nos arquivos de objeto gerados. Esses atributos ajudam na criação de arquivos .idl, interfaces, bibliotecas de tipos e outros elementos COM. No IDE (ambiente de desenvolvimento integrado), os atributos têm suporte dos assistentes e do janela Propriedades.

Embora os atributos eliminem algumas das codificações detalhadas necessárias para gravar objetos COM, você precisa conhecer os conceitos básicos de COM para usá-los melhor.

Observação

Se você estiver procurando atributos padrão C++, confira Atributos.

Finalidade de atributos

Os atributos estendem o C++ em direções nas quais ainda não é possível fazer sem quebrar a estrutura clássica da linguagem. Os atributos permitem que provedores (DLLs separadas) estendam a funcionalidade de linguagem dinamicamente. O objetivo principal dos atributos é simplificar a criação de componentes COM, além de aumentar o nível de produtividade do desenvolvedor do componente. Os atributos podem ser aplicados a quase qualquer constructo do C++, como classes, membros de dados ou funções de membro. Veja abaixo os benefícios fornecidos por esta nova tecnologia:

Expõe uma convenção de chamada conhecida e simples.
Usa o código inserido, que, ao contrário das macros, é reconhecido pelo depurador.
Permite a derivação fácil de classes base sem detalhes de implementação onerosos.
Substitui a grande quantidade de código IDL exigida por um componente COM por alguns atributos concisos.

Por exemplo, para implementar um coletor de eventos simples para uma classe ATL genérica, você pode aplicar o atributo event_receiver a uma classe específica, como CMyReceiver. Em seguida, o atributo event_receiver é compilado pelo compilador do Microsoft C++, que insere o código adequado no arquivo-objeto.

[event_receiver(com)]
class CMyReceiver
{
   void handler1(int i) { ... }
   void handler2(int i, float j) { ... }
}

Então, você pode configurar os métodos CMyReceiverhandler1 e handler2 para manipular eventos (usando a função intrínseca __hook) de uma origem de evento, que você pode criar usando event_source.

Mecânica básica de atributos

Há três maneiras de inserir atributos em seu projeto. Em primeiro lugar, você pode inseri-los manualmente no código-fonte. Em segundo, você pode inseri-los usando a grade de propriedade de um objeto em seu projeto. Por fim, você pode inseri-los usando os vários assistentes. Para obter mais informações sobre como usar a janela Propriedades e os vários assistentes, confira Projetos do Visual Studio – C++.

Como antes, quando o projeto é criado, o compilador analisa cada arquivo de origem do C++, produzindo um arquivo-objeto. No entanto, quando o compilador encontra um atributo, ele é analisado e verificado sintaticamente. Em seguida, o compilador chama dinamicamente um provedor de atributo para inserir código ou fazer outras modificações no tempo de compilação. A implementação do provedor é diferente dependendo do tipo de atributo. Por exemplo, os atributos relacionados à ATL são implementados por Atlprov.dll.

A figura a seguir demonstra a relação entre o compilador e o provedor de atributo.

Diagram showing component attribute communication.

Observação

O uso do atributo não altera o conteúdo do arquivo de origem. A única vez que o código de atributo gerado é visível é durante as sessões de depuração. Além disso, para cada arquivo de origem no projeto, você pode gerar um arquivo de texto que exibe os resultados da substituição de atributo. Para obter mais informações sobre esse procedimento, consulte /Fx (Mesclar código injetado) e Depurar código injetado.

Como a maioria dos constructos C++, os atributos têm um conjunto de características que definem seu uso adequado. Isso é conhecido como o contexto do atributo e é abordado na tabela de contexto de atributo para cada tópico de referência de atributo. Por exemplo, o atributo coclasse só pode ser aplicado a uma classe ou estrutura existente, em vez do atributo cpp_quote, que pode ser inserido em qualquer lugar dentro de um arquivo de origem C++.

Compilando um programa atribuído

Depois de colocar atributos do Visual C++ no código-fonte, convém que o compilador do Microsoft C++ produza uma biblioteca de tipos e um arquivo .idl para você. As seguintes opções de vinculador ajudam você a compilar arquivos .tlb e .idl:

Alguns projetos contêm vários arquivos .idl independentes. Eles são usados para produzir dois ou mais arquivos .tlb e, opcionalmente, associá-los ao bloco de recursos. No momento, não há suporte para esse cenário no Visual C++.

Além disso, o vinculador do Visual C++ produzirá todas as informações de atributo relacionadas à IDL para um único arquivo MIDL. Não haverá como gerar duas bibliotecas de tipos de um único projeto.

Contextos de atributos

Os atributos do C++ podem ser descritos usando quatro campos básicos: o destino ao qual podem ser aplicados (Aplica-se a), se são repetíveis ou não (Repetíveis), a presença necessária de outros atributos (Atributos Obrigatórios) e incompatibilidades com outros atributos (Atributos Inválidos). Esses campos são listados em uma tabela de acompanhamento no tópico de referência de cada atributo. Esses campos são descritos a seguir.

Aplica-se A

Este campo descreve os diferentes elementos de linguagem C++ que são destinos legais para o atributo especificado. Por exemplo, se um atributo especificar "classe" no campo Aplica-se a, isso indica que o atributo só poderá ser aplicado a uma classe C++ legal. Se o atributo for aplicado a uma função de membro de uma classe, ocorrerá um erro de sintaxe.

Confira Atributos por Uso para obter mais informações.

Repetível

Esse campo indica se o atributo pode ser aplicado repetidamente ao mesmo destino. A maioria dos atributos não é repetível.

Atributos necessários.

Esse campo lista outros atributos que precisam estar presentes (ou seja, aplicados ao mesmo destino) para que o atributo especificado funcione corretamente. É incomum que um atributo tenha entradas para esse campo.

Atributos inválidos

Esse campo lista outros atributos incompatíveis com o atributo especificado. É incomum que um atributo tenha entradas para esse campo.

Depurar código injetado

Usar atributos pode simplificar muito a programação C++. Para obter mais informações, confira Conceitos. Alguns atributos são interpretados diretamente pelo compilador. Outros atributos injetam o código na origem do programa, que o compilador em seguida compila. Este código injetado facilita a programação reduzindo a quantidade de códigos que você precisa escrever. Entretanto, às vezes, um bug pode causar falha no aplicativo ao executar o código injetado. Quando isso acontece, você provavelmente desejará examinar o código injetado. O Visual Studio fornece duas maneiras de ver o código injetado:

Você pode exibir o código injetado na janela Desmontagem.
Usando /Fx, você pode criar um arquivo de origem mesclada que contém o código original e injetado.

A janela Desmontagem mostra as instruções da linguagem assembly que corresponde ao código-fonte e o código injetado por atributos. Além disso, a janela Desmontagem pode mostrar a anotação do código-fonte.

Para ativar a anotação de origem

Clique com o botão direito do mouse na janela Desmontagem e escolha Mostrar Código-Fonte no menu de atalho.

Se você souber a localização de um atributo em uma janela de origem, poderá usar o menu de atalho para localizar o código injetado na janela Desmontagem.

Para exibir o código injetado

O depurador deve estar no modo de interrupção.
Em uma janela do código-fonte, coloque o cursor na frente do atributo cujo código injetado você deseja exibir.
Clique com o botão direito do mouse e selecione Ir para Desmontagem no menu de atalho.

Se a localização do atributo estiver perto do ponto de execução atual, você poderá selecionar a janela Desmontagem no menu Depurar.

Para exibir o código de desmontagem no ponto de execução atual

O depurador deve estar no modo de interrupção.
No menu Depurar, escolha Windows e clique em Desmontagem.

Nesta seção

Perguntas frequentes sobre programação de atributos
Atributos por grupo
Atributos por uso
Referência alfabética de atributos