Compartilhar via

Combinar VBA e personalizações em nível de documento

  • Artigo

Você pode usar o código VBA (Visual Basic for Applications) em um documento que faz parte de uma personalização em nível de documento para o Microsoft Office Word ou Microsoft Office Excel. Você pode chamar o código VBA no documento a partir do assembly de personalização ou pode configurar seu projeto para habilitar o código VBA no documento para chamar o código no assembly de personalização.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento para Excel e Word. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Comportamento do código VBA em uma personalização em nível de documento

Quando você abre seu projeto no Visual Studio, o documento é aberto no modo de design. O código VBA não é executado quando o documento está no modo de design, portanto, você pode trabalhar no documento e no código sem executar o código VBA.

Quando você executa a solução, os manipuladores de eventos no VBA e no assembly de personalização selecionam eventos que são gerados no documento e ambos os conjuntos de código são executados. Você não pode determinar de antemão qual código será executado antes do outro; Você deve determinar isso por meio de testes em cada caso individual. Você pode obter resultados inesperados se os dois conjuntos de código não forem cuidadosamente coordenados e testados.

Chamar o código VBA do assembly de personalização

Você pode chamar macros em documentos do Word e pode chamar macros e funções em pastas de trabalho do Excel. Para tal, use um dos seguintes métodos:

  • Para o Word, chame o RunApplication método da classe.

  • Para o Excel, chame o RunApplication método da classe.

    Para cada método, o primeiro parâmetro identifica o nome da macro ou função que você deseja chamar e os parâmetros opcionais restantes especificam os parâmetros a serem passados para a macro ou função. O primeiro parâmetro pode ter formatos diferentes para Word e Excel:

  • Para o Word, o primeiro parâmetro é uma cadeia de caracteres que pode ser qualquer combinação de modelo, módulo e nome de macro. Se você especificar o nome do documento, seu código só poderá executar macros em documentos relacionados ao contexto atual — não apenas qualquer macro em qualquer documento.

  • Para o Excel, o primeiro parâmetro pode ser uma cadeia de caracteres que especifica o nome da macro, uma que indica onde a função está ou uma ID de registro para uma Range função DLL registrada (XLL). Se você passar uma cadeia de caracteres, ela será avaliada no contexto da planilha ativa.

    O exemplo de código a seguir mostra como chamar uma macro nomeada MyMacro de um projeto de nível de documento para Excel. Este exemplo pressupõe que MyMacro está definido em Sheet1.

Globals.Sheet1.Application.Run("MyMacro", missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing);

Observação

Para obter informações sobre como usar a variável global missing no lugar de parâmetros opcionais no Visual C#, consulte Escrever código em soluções do Office.

Chamar código em personalizações em nível de documento do VBA

Você pode configurar um projeto de nível de documento para Word ou Excel para que o código VBA (Visual Basic for Applications) no documento possa chamar código no assembly de personalização. Isso é útil nos seguintes cenários:

  • Você deseja estender o código VBA existente em um documento usando recursos em uma personalização em nível de documento associada ao mesmo documento.

  • Você deseja disponibilizar os serviços desenvolvidos em uma personalização em nível de documento para os usuários finais que podem acessar os serviços escrevendo código VBA no documento.

    As ferramentas de desenvolvimento do Office no Visual Studio fornecem um recurso semelhante para suplementos VSTO. Se você estiver desenvolvendo um suplemento VSTO, poderá chamar o código em seu suplemento VSTO de outras soluções do Microsoft Office. Para obter mais informações, consulte Código de chamada em suplementos VSTO de outras soluções do Office.

Observação

Esse recurso não pode ser usado em projetos de modelo do Word. Ele pode ser usado somente em documentos do Word, pastas de trabalho do Excel ou projetos de modelo do Excel.

Requisitos

Antes de habilitar o código VBA para chamar o assembly de personalização, seu projeto deve atender aos seguintes requisitos:

  • O documento deve ter uma das seguintes extensões de nome de arquivo:

    • Para Word: .docm ou .doc

    • Para Excel: .xlsm, .xltm, .xls ou .xlt

  • O documento já deve conter um projeto VBA que tenha código VBA.

  • O código VBA no documento deve ter permissão para ser executado sem solicitar que o usuário habilite macros. Você pode confiar no código VBA a ser executado adicionando o local do projeto do Office à lista de locais confiáveis nas configurações da Central de Confiabilidade para Word ou Excel.

  • O projeto do Office deve conter pelo menos uma classe pública que contém um ou mais membros públicos que você está expondo ao VBA.

    Você pode expor métodos, propriedades e eventos ao VBA. A classe que você expõe pode ser uma classe de item de host (como ThisDocument para Word ou e Sheet1 para Excel) ou ThisWorkbook outra classe que você define em seu projeto. Para obter mais informações sobre itens de host, consulte Visão geral sobre itens de host e controles de host.

Habilitar o código VBA para chamar o assembly de personalização

Há duas maneiras diferentes de expor membros em um assembly de personalização ao código VBA no documento:

  • Você pode expor membros de uma classe de item de host em um projeto do Visual Basic para VBA. Para fazer isso, defina a propriedade EnableVbaCallers do item de host como True na janela Propriedades enquanto o item de host (ou seja, o documento, planilha ou pasta de trabalho) está aberto no designer. O Visual Studio executa automaticamente todo o trabalho necessário para habilitar o código VBA para chamar membros da classe.

  • Você pode expor membros em qualquer classe pública em um projeto Visual C#, ou membros em uma classe de item não-host em um projeto Visual Basic, para VBA. Essa opção oferece mais liberdade para escolher quais classes você expõe ao VBA, mas também requer mais etapas manuais.

    Para fazer isso, você deve executar as seguintes etapas principais:

    1. Exponha a classe a COM.

    2. Substitua o método GetAutomationObject de uma classe de item de host em seu projeto para retornar uma instância da classe que você está expondo ao VBA.

    3. Defina a propriedade ReferenceAssemblyFromVbaProject de qualquer classe de item de host no projeto como True. Isso incorpora a biblioteca de tipos do assembly de personalização no assembly e adiciona uma referência à biblioteca de tipos ao projeto VBA no documento.

    Para obter instruções detalhadas, consulte Como: Expor código ao VBA em um projeto do Visual Basic e Como: Expor código ao VBA em um projeto do Visual C#.

    As propriedades EnableVbaCallers e ReferenceAssemblyFromVbaProject estão disponíveis somente na janela Propriedades em tempo de design, não podendo ser usadas em tempo de execução. Para exibir as propriedades, abra o designer para um item de host no Visual Studio. Para obter mais informações sobre as tarefas específicas que o Visual Studio executa quando você define essas propriedades, consulte Tarefas executadas pelas propriedades do item de host.

Observação

Se a pasta de trabalho ou documento ainda não contém código VBA ou se o código VBA no documento não é confiável para execução, você receberá uma mensagem de erro quando definir a propriedade EnableVbaCallers ou ReferenceAssemblyFromVbaProject como True. Isso ocorre porque o Visual Studio não pode modificar o projeto VBA no documento nessa situação.

Use membros no código VBA para chamar o assembly de personalização

Depois de configurar seu projeto para habilitar o código VBA para chamar o assembly de personalização, o Visual Studio adiciona os seguintes membros ao projeto VBA no documento:

  • Para todos os projetos, o Visual Studio adiciona um método global chamado GetManagedClass.

  • Para projetos do Visual Basic nos quais você expõe membros de uma classe de item de host usando a propriedade EnableVbaCallers, o Visual Studio também adiciona uma propriedade nomeada CallVSTOAssembly para o ThisDocument, , ThisWorkbookSheet1, Sheet2ou Sheet3 módulo no projeto VBA.

    Você pode usar a propriedade ou GetManagedClass o CallVSTOAssembly método para acessar membros públicos da classe que você expôs ao código VBA no projeto.

Observação

Enquanto você desenvolve e implanta sua solução, há várias cópias diferentes do documento onde você pode adicionar o código VBA. Para obter mais informações, consulte Diretrizes para adicionar código VBA ao documento.

Usar a propriedade CallVSTOAssembly em um projeto do Visual Basic

Use a CallVSTOAssembly propriedade para acessar membros públicos que você adicionou à classe de item de host. Por exemplo, a macro VBA a seguir chama um método chamado MyVSTOMethod que é definido na Sheet1 classe em um projeto de pasta de trabalho do Excel.

Sub MyMacro()
    Sheet1.CallVSTOAssembly.MyVSTOMethod()
End Sub

Essa propriedade é uma maneira mais conveniente de chamar o assembly de personalização do que usar o GetManagedClass método diretamente. CallVSTOAssembly retorna um objeto que representa a classe de item de host que você expôs ao VBA. Os membros e os parâmetros de método do objeto retornado aparecem no IntelliSense.

A CallVSTOAssembly propriedade tem uma declaração semelhante ao código a seguir. Esse código pressupõe que você expôs a classe de item de host em um projeto de pasta de Sheet1 trabalho do Excel nomeado ExcelWorkbook1 para VBA.

Property Get CallVSTOAssembly() As ExcelWorkbook1.Sheet1
    Set CallVSTOAssembly = GetManagedClass(Me)
End Property

Usar o método GetManagedClass

Para usar o método global GetManagedClass , passe o objeto VBA que corresponde à classe de item de host que contém sua substituição do método GetAutomationObject . Em seguida, use o objeto retornado para acessar a classe que você expôs ao VBA.

Por exemplo, a macro VBA a seguir chama um método chamado que é definido na classe de item de host em um projeto de pasta de Sheet1 trabalho do Excel chamado .MyVSTOMethodExcelWorkbook1

Sub CallVSTOMethod
    Dim VSTOSheet1 As ExcelWorkbook1.Sheet1
    Set VSTOSheet1 = GetManagedClass(Sheet1)
    VSTOSheet1.MyVSTOMethod
End Sub

O GetManagedClass método tem a seguinte declaração.

GetManagedClass(pdispInteropObject Object) As Object

Esse método retorna um objeto que representa a classe que você expôs ao VBA. Os membros e os parâmetros de método do objeto retornado aparecem no IntelliSense.

Diretrizes para adicionar código VBA ao documento

Há várias cópias diferentes do documento onde você pode adicionar código VBA que chama a personalização em nível de documento.

À medida que você desenvolve e testa sua solução, você pode escrever código VBA no documento que é aberto enquanto você depura ou executa seu projeto no Visual Studio (ou seja, o documento na pasta de saída da compilação). No entanto, qualquer código VBA adicionado a este documento será substituído na próxima vez que você criar o projeto, porque o Visual Studio substitui o documento na pasta de saída de compilação com uma cópia do documento da pasta de projeto principal.

Se você quiser salvar o código VBA adicionado ao documento durante a depuração ou execução da solução, copie o código VBA para o documento na pasta do projeto. Para obter mais informações sobre o processo de compilação, consulte Criar soluções de escritório.

Quando você estiver pronto para implantar sua solução, há três locais de documento principais nos quais você pode adicionar o código VBA.

Na pasta do projeto no computador de desenvolvimento

Esse local é conveniente se você tiver controle total sobre o código VBA no documento e o código de personalização. Como o documento está no computador de desenvolvimento, você pode modificar facilmente o código VBA se alterar o código de personalização. O código VBA que você adiciona a essa cópia do documento permanece no documento quando você cria, depura e publica sua solução.

Não é possível adicionar o código VBA ao documento enquanto ele estiver aberto no designer. Você deve primeiro fechar o documento no designer e, em seguida, abrir o documento diretamente no Word ou Excel.

Cuidado

Se você adicionar código VBA que é executado quando o documento é aberto, em casos raros esse código pode corromper o documento ou impedi-lo de abrir no designer.

Na pasta de publicação ou instalação

Em alguns casos, pode ser adequado adicionar o código VBA ao documento na pasta de publicação ou instalação. Por exemplo, você pode escolher essa opção se o código VBA for escrito e testado por um desenvolvedor diferente em um computador que não tenha o Visual Studio instalado.

Se os usuários instalarem a solução diretamente da pasta de publicação, você deverá adicionar o código VBA ao documento sempre que publicar a solução. Visual Studio substitui o documento no local de publicação quando você publica a solução.

Se os usuários instalarem a solução a partir de uma pasta de instalação diferente da pasta de publicação, você poderá evitar a adição do código VBA no documento sempre que publicar a solução. Quando uma atualização de publicação estiver pronta para ser movida da pasta de publicação para a pasta de instalação, copie todos os arquivos para a pasta de instalação, exceto o documento.

No computador do usuário final

Se os usuários finais forem desenvolvedores do VBA que estão chamando serviços que você fornece na personalização em nível de documento, você pode dizer-lhes como chamar seu código usando a CallVSTOAssembly propriedade ou o GetManagedClass método em suas cópias do documento. Quando você publica atualizações para a solução, o código VBA no documento no computador do usuário final não será substituído, porque o documento não é modificado por atualizações de publicação.

Tarefas executadas pelas propriedades do item de host

Quando você usa as propriedades EnableVbaCallers e ReferenceAssemblyFromVbaProject, o Visual Studio executa diferentes conjuntos de tarefas.

EnableVbaCallers

Quando você define a propriedade EnableVbaCallers de um item de host para True em um projeto do Visual Basic, Visual Studio executa as seguintes tarefas:

  1. Ele adiciona os ComClassAttribute atributos e ComVisibleAttribute à classe de item do host.

  2. Ele substitui o método GetAutomationObject da classe de item de host.

  3. Ele define a propriedade ReferenceAssemblyFromVbaProject do item de host como True.

    Quando você define a propriedade EnableVbaCallers de volta para False, Visual Studio executa as seguintes tarefas:

  4. Ele remove os ComClassAttribute atributos e ComVisibleAttribute da ThisDocument classe.

  5. Ele remove o método GetAutomationObject da classe de item de host.

    Observação

    Visual Studio não define automaticamente a propriedade ReferenceAssemblyFromVbaProject de volta para False. Você pode definir essa propriedade como False manualmente usando a janela Propriedades.

ReferenceAssemblyFromVbaProject

Quando a propriedade ReferenceAssemblyFromVbaProject de qualquer item de host em um projeto Visual Basic ou Visual C# é definida como True, Visual Studio executa as seguintes tarefas:

  1. Ele gera uma biblioteca de tipos para o assembly de personalização e incorpora a biblioteca de tipos no assembly.

  2. Ele adiciona uma referência às seguintes bibliotecas de tipos no projeto VBA no documento:

    • A biblioteca de tipos para seu assembly de personalização.

    • A biblioteca de tipos do Microsoft Visual Studio Tools for Office Execution Engine 9.0. Essa biblioteca de tipos está incluída no Visual Studio Tools for Office runtime .

    Quando a propriedade ReferenceAssemblyFromVbaProject é definida como False, o Visual Studio executa as seguintes tarefas:

  3. Ele remove as referências de biblioteca de tipos do projeto VBA no documento.

  4. Ele remove a biblioteca de tipos incorporada do assembly.

Solucionar problemas

A tabela a seguir lista alguns erros comuns e sugestões para corrigir os erros.

Erro Sugestão
Depois de definir a propriedade EnableVbaCallers ou ReferenceAssemblyFromVbaProject, uma mensagem de erro informa que o documento não contém um projeto VBA ou você não tem permissão para acessar o projeto VBA no documento. Verifique se o documento no projeto contém pelo menos uma macro VBA, se o projeto VBA tem confiança suficiente para ser executado e se o projeto VBA não está protegido por uma senha.
Depois de definir a propriedade EnableVbaCallers ou ReferenceAssemblyFromVbaProject, uma mensagem de erro indica que a GuidAttributedeclaração está ausente ou corrompida. Verifique se a GuidAttributedeclaração está localizada no arquivo AssemblyInfo.cs ou AssemblyInfo.vb em seu projeto e se esse atributo está definido como um GUID válido.
Depois de definir a propriedade EnableVbaCallers ou ReferenceAssemblyFromVbaProject , uma mensagem de erro informa que o número de versão especificado pelo AssemblyVersionAttribute não é válido. Certifique-se de que a AssemblyVersionAttribute declaração no arquivo AssemblyInfo.cs ou AssemblyInfo.vb em seu projeto esteja definida como um número de versão de assembly válido. Para obter informações sobre números de versão de assembly válidos, consulte a AssemblyVersionAttribute classe.
Depois de renomear o assembly de personalização, o código VBA que chama o assembly de personalização pára de funcionar. Se você alterar o nome do assembly de personalização depois de expô-lo ao código VBA, o vínculo entre o projeto VBA no documento e o assembly de personalização será quebrado. Para corrigir esse problema, altere a propriedade ReferenceFromVbaAssembly em seu projeto para False e, em seguida, volte para True e, em seguida, substitua quaisquer referências ao nome do assembly antigo no código VBA com o novo nome do assembly.

Conteúdo relacionado