Automação do Office usando o Visual C++

Sumário

1. O que é Automação?

2. Sou novo na Automação, onde posso encontrar bons recursos para aprender mais?

3. Há maneiras diferentes de usar a Automação?

4. O que é COM?
    

5. Como fazer anexar à instância em execução de um aplicativo do Office?

6. Como fazer passar parâmetros opcionais?

7. Como fazer capturar eventos expostos pelos aplicativos do Office?
    

8. Meu código de automação é muito lento. Como posso acelerar as coisas?

9. O que significam esses enormes valores de erro, como -2147352573 ou 0x80030002?

10. O que é uma biblioteca de tipos?

11. Meu código de automação funcionou com o Microsoft Excel 95, mas falha com o Microsoft Excel 97. Porque?

12. Por que o aplicativo que estou automatizando permanece na memória depois que meu programa é concluído?

13. Sei o que quero fazer como usuário de aplicativo do Microsoft Office, mas como faço isso programaticamente usando a Automação?

14. Posso automatizar um aplicativo do Microsoft Office inserido?

15. Como fazer acessar minhas propriedades de documento em um documento do Microsoft Office?

Perguntas e respostas

1. O que é Automação?
   
   A automação (anteriormente Automação OLE) é uma tecnologia que permite aproveitar a funcionalidade de um programa existente e incorporá-la em seus próprios aplicativos. Por exemplo, você pode utilizar os recursos de verificação ortográfica e gramatical do Microsoft Word em seu aplicativo sem o Microsoft Word visível para seus usuários. Você pode até usar todas as ferramentas de mapeamento, impressão e análise de dados do Microsoft Excel. Essa tecnologia pode simplificar e acelerar muito o desenvolvimento.
    

2. Sou novo na Automação, onde posso encontrar bons recursos para aprender mais? O capítulo 24 de "Inside Visual C++" de David Kruglinski (ISBN:1-57231-565-2) fornece uma visão geral, bem como alguns ótimos exemplos. Além disso, a Base de Dados de Conhecimento da Microsoft é uma boa fonte de informações.
   Se preferir aprender por exemplo, consulte o seguinte artigo na Base de Dados de Conhecimento da Microsoft:
    

   179706 HOWTO Use MFC para automatizar o Excel & criar/formatar uma nova pasta de trabalho

3. Há maneiras diferentes de usar a Automação?
   
   Há três maneiras básicas de usar a Automação: MFC, #import e C/C++:
    

   • Com o MFC, use o Visual C++ ClassWizard para gerar "classes wrapper" das bibliotecas de tipos do Microsoft Office. Essas classes, bem como outras classes MFC, como COleVariant, COleSafeArray, COleException, simplificam as tarefas da Automação. Esse método geralmente é recomendado em relação aos outros e a maioria dos exemplos da Base de Dados de Conhecimento da Microsoft usa MFC.

   • #import, uma nova diretiva que ficou disponível com o Visual C++ 5.0, cria "ponteiros inteligentes" VC++ de uma biblioteca de tipos especificada. Ele é muito poderoso, mas muitas vezes não é recomendado devido a problemas de contagem de referência que normalmente ocorrem quando usados com os aplicativos do Microsoft Office.

   • A Automação C/C++ é muito mais difícil, mas às vezes necessária para evitar sobrecarga com MFC ou problemas com #import. Basicamente, você trabalha com APIs como interfaces CoCreateInstance() e COM, como IDispatch e IUnknown.

   É importante observar que há algumas pequenas diferenças entre a automação do C++ em comparação com c simples, porque o COM foi projetado em torno da classe C++.
    

4. O que é COM?
   
   A automação é baseada no COM (Component Object Model). O COM é uma arquitetura de software padrão baseada em interfaces e projetada para ter o código separado em objetos independentes. Pense nele como uma extensão do paradigma OOP (Programação Orientada ao Objeto), mas aplicável a aplicativos separados. Cada objeto expõe um conjunto de interfaces e toda a comunicação a um objeto, como inicialização, notificações e transferência de dados, acontece por meio dessas interfaces.
   
   O COM também é um conjunto de serviços fornecidos por DLLs (bibliotecas de link dinâmico) instalados com o sistema operacional. A automação usa muitos desses serviços. Um exemplo é o serviço "Marshalling", que empacota as chamadas do aplicativo cliente para as funções membro das interfaces do aplicativo do servidor e passa elas, com seus argumentos, para o aplicativo do servidor. Ele faz parecer que as interfaces do servidor são expostas no espaço de memória do cliente, o que não é o caso quando o cliente é um .exe em execução em seu próprio espaço de processo. O marshalling também obtém os valores retornados dos métodos do servidor de volta através dos limites do processo e em segurança nas mãos da chamada do cliente. Há muitos outros serviços essenciais para a Automação que são fornecidos pelas várias bibliotecas COM. As fontes de informações sobre eles incluem "Inside Ole - Second Edition" de Kraig Brockschmidt, ISBN 1-55615-843-2, "Inside COM" de Dale Rogerson - ISBN 1-57231-349-8 e "Referência do Programador de Automação", ISBN 1-57231-584-9.

5. Como fazer anexar à instância em execução de um aplicativo do Office?
   
   Use a API GetActiveObject(). Os servidores de automação se registram na ROT (Tabela de Objetos em Execução), por meio da API RegisterActiveObject(). Os clientes de automação podem obter na instância em execução com código como:
   
    

         // Translate server ProgID into a CLSID. ClsidFromProgID
         // gets this information from the registry.
         CLSID clsid;
         CLSIDFromProgID(L"Excel.Application", &clsid);  
   
         // Get an interface to the running instance, if any..
         IUnknown *pUnk;
         HRESULT hr = GetActiveObject(clsid, NULL, (IUnknown**)&pUnk);
   
         ASSERT(!FAILED(hr));
   
         // Get IDispatch interface for Automation...
         IDispatch *pDisp;
         hr = pUnk->QueryInterface(IID_IDispatch, (void **)&pDisp);
         ASSERT(!FAILED(hr));
   
         // Release the no-longer-needed IUnknown...
         pUnk->Release();
   
   

   OBSERVAÇÃO: se houver várias instâncias em execução do aplicativo do Office que você deseja anexar, você só poderá anexar à primeira instância que foi iniciada usando a API GetActiveObject().
   
   Teoricamente, você pode iterar o ROT para cada instância individual, mas os aplicativos do Office não se registram se outra instância já estiver no ROT porque o moniker para si é sempre o mesmo (não poderia ser distinguido de qualquer maneira). Isso significa que você não pode anexar a nenhuma instância, exceto à primeira. No entanto, como os aplicativos do Office também registram seus documentos no ROT, você pode anexar com êxito a outras instâncias iterando o ROT procurando um documento específico, anexando-o e, em seguida, obtendo o objeto Application dele.
   Você não precisará fazer isso pelo PowerPoint, pois ele é um aplicativo de instância única; você só pode ter uma instância dele em execução.

6. Como fazer passar parâmetros opcionais?
   
   Alguns métodos têm parâmetros "opcionais". No Visual Basic, você pode omitê-los casualmente ao chamar o método. No entanto, ao chamar com o Visual C++ você precisa passar uma VARIANT especial cujo campo .vt é VT_ERROR e o campo .scode é DISP_E_PARAMNOTFOUND. Isto é:
    

         // VARIANT used in place of optional-parameters.
         VARIANT varOpt;
         varOpt.vt = VT_ERROR;
         varOpt.scode = DISP_E_PARAMNOTFOUND;
   

   Isso é realmente o que o Visual Basic está fazendo nos bastidores.

7. Como fazer capturar eventos expostos pelos aplicativos do Office?
   
   Basicamente, você implementa a interface do evento que deseja capturar (o "coletor") e configurar uma conexão consultiva com o aplicativo (a "origem").
   
   Em geral, para configurar a conexão consultiva, você obtém o IConnectionPointContainer do servidor e chama FindConnectionPoint() com o IID da interface do evento. Isso fornece uma interface IConnectionPoint e tudo o que resta é chamar Advise() com uma instância da interface do evento. Em seguida, o servidor chamará de volta por meio dessa interface quando esses eventos ocorrerem.

8. Meu código de automação é muito lento. Como posso acelerar as coisas?
   
   Uma causa comum de problemas de velocidade com a Automação é a leitura repetitiva e a gravação de dados. Isso é típico para clientes da Automação do Excel. No entanto, a maioria das pessoas não está ciente de que esses dados geralmente podem ser gravados ou lidos de uma só vez usando SAFEARRAY. Consulte o seguinte artigo da Base de Dados de Conhecimento da Microsoft para obter mais informações e exemplos informativos:

   179706 HOWTO: usar o MFC para automatizar o Excel e criar/formatar uma nova pasta de trabalho
   Além disso, é importante ressaltar que o uso da área de transferência às vezes pode melhorar o desempenho. Por exemplo, você pode copiar seus dados para a área de transferência e, em seguida, usar a automação para dizer ao servidor para colar. Ou vice-versa; diga ao servidor para copiar para a área de transferência e colar em seu aplicativo.

9. O que significam esses enormes valores de erro, como -2147352573 ou 0x80030002?
   
   Esses valores são conhecidos como HRESULTs e são definidos em winerror.h. Os números são tão grandes porque o primeiro bit representa se é ou não um resultado de erro. Você pode usar o utilitário ErrLook.Exe que vem com o Visual C++ para traduzir esses números em descrições significativas.
   
   Se você quiser obter programaticamente uma descrição para os erros, poderá usar a API FormatMessage().

   OBSERVAÇÃO: se você estiver usando o Visual C++ 6.0 e tiver uma variável que contenha esse valor na janela do relógio de depuração, anexe ", hr" (sem as aspas) para que o Visual C++ o traduza para você!

10. O que é uma biblioteca de tipos?
    
    Uma biblioteca de tipos é semelhante a um arquivo de cabeçalho C/C++. Ele contém as interfaces, métodos e propriedades que um servidor está publicando. Você pode exibir a biblioteca de tipos com o Visualizador de Objetos OLE/COM (Oleview.exe) que vem com o Visual C++. Aqui está uma lista dos nomes de arquivo da biblioteca de tipos para Microsoft Office 95, 97 e 2000:
    
    
    
    | de Aplicativos do Office Biblioteca
    de tipos ------------------------+----------------
    Word 95 e | anterior wb70en32.tlb
    Excel 95 e | anteriores xl5en32.olb
    Powerpoint 95 e | anterior Powerpoint.tlb
    Acesso 95 e | anteriores msaccess.tlb
    Associador 95 | binder.tlb
    Agendar+ | sp7en32.olb
    Projeto | pj4en32.olb
    | do Team Manager mstmgr1.olb
    Word 97 | msword8.olb
    Excel 97 | excel8.olb
    Powerpoint 97 | msppt8.olb
    Acesso 97 | msacc8.olb
    Associador 97 | msbdr8.olb
    Grafo 97 | graph8.olb
    Outlook 97 | msoutl8.olb
    Outlook 98 | msoutl85.olb
    Word 2000 | msword9.olb
    Excel 2000 | excel9.olb
    Powerpoint 2000 | msppt9.olb
    Acesso 2000 | msacc9.olb
    Outlook 2000 | msoutl9.olb
    Word 2002 | msword.olb
    Excel 2002 |
    excel.exe Powerpoint 2002 | msppt.olb
    Access 2002 | msacc.olb
    Outlook 2002 | msoutl.olb
    
     

1. Meu código de automação funcionou com o Excel 95, mas falha com o Excel 97. O que está acontecendo?
   
   O modelo de objeto do Excel fez uma alteração significativa da versão 95 para 97. O Excel 95 implementou todos os seus métodos e propriedades em uma única implementação de IDispatch. Isso significava que, muitas vezes, você poderia chamar métodos destinados ao objeto X, do objeto Y. Esse não foi um bom design, portanto, no Office 97, cada objeto tem sua própria implementação Idispatch separada. Isso significa que, se você pedir um método ou propriedade do objeto X de um objeto separado Y, você receberá o erro 0x80020003, -2147352573, "Membro não encontrado". Para evitar esse erro, você precisa ter certeza de que a interface IDispatch subjacente da qual você está fazendo chamadas é a semanticamente correta.
    

2. O aplicativo que estou automatizando permanece na memória depois que meu programa for concluído. O que está acontecendo?
   
   Provavelmente, isso ocorre porque você esqueceu de liberar uma interface adquirida e precisará localizá-la. Aqui estão algumas sugestões gerais e as coisas a serem buscadas:
    

   • Se você estiver usando #import, é muito provável que você possa estar encontrando um dos bugs de contagem de referência associados a ele. Muitas vezes os bugs podem ser trabalhados, mas geralmente é preferível usar um dos outros métodos de Automação. #import não funciona muito bem com os aplicativos do Office, pois suas bibliotecas de tipo e uso são bastante complexas. Além disso, esses problemas de contagem de referências são difíceis de rastrear porque muitas das chamadas COM no nível da interface estão nos bastidores ao usar #import.

   • Verifique se você está chamando algum método, como Open ou New, que retornam um IDispatch * (LPDISPATCH) e ignorando o valor retornado. Se você estiver, então você está abandonando essa interface retornada e precisará alterar seu código para liberá-lo quando não for mais necessário.

   • Comente gradualmente seções de seu código até que o problema desapareça e adicione-o de forma criteriosa para rastrear onde o problema começa.

   • Observe que alguns aplicativos continuarão em execução se o usuário tiver "tocado" o aplicativo. Se isso ocorrer enquanto você estiver automatizando, o aplicativo provavelmente permanecerá em execução posteriormente. Os aplicativos do Office têm uma propriedade "UserControl" no objeto Application que você pode ler/gravar para alterar esse comportamento.

   • Além disso, alguns aplicativos decidirão continuar em execução se houver "ação" suficiente de interface do usuário. Se você pretende que o aplicativo saia, chame o método Quit() no objeto Application. O Word será desligado independentemente de sua contagem de referência quando Quit for chamado. Isso não é um comportamento COM esperado. O Excel, no entanto, apenas se esconderá corretamente, mas permanecerá em execução até que todas as interfaces pendentes sejam lançadas. Em geral, você deve liberar todas as referências pendentes e chamar Apenas Quit() se você pretende que o aplicativo saia.

3. Sei o que quero fazer como usuário de aplicativo do Office, mas como faço isso programaticamente por meio da Automação?
   
   O que você está interessado é em quais objetos, métodos e propriedades você precisa usar. A melhor maneira de aprender a navegar pelos modelos de objeto do Word, Excel e Powerpoint, com base no que você deseja fazer como usuário, é usar o Gravador de Macro. Basta escolher Macro\'Gravar Nova Macro' no menu Ferramentas, executar a tarefa na qual você está interessado e, em seguida, escolher Macro\'Parar Gravação'. Depois de terminar de gravar, escolha Macro\Macros no menu Ferramentas, selecione a macro que você gravou e clique em Editar. Isso o levará ao código VBA gerado que realizará a tarefa que você gravou. Tenha em mente que a macro gravada não será o melhor código possível na maioria dos casos, mas faz muito bem para um exemplo rápido.

4. Posso automatizar um aplicativo do Office inserido?
   
   Absolutamente. O truque é obter o ponteiro IDispatch: isso é dado no Visual C++ Technical Note 39 (TN039).
    

5. Como fazer acessar minhas propriedades de documento em um documento do Office?
   
   As propriedades do documento são acessíveis por meio da Automação ou diretamente por meio do IPropertyStorage.