Compartilhar via

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

Você pode usar o código do Visual Basic for Applications (VBA) em um documento que faz parte de uma personalização no nível do documento para o Microsoft Office Word ou o Microsoft Office Excel. Você pode chamar o código VBA no documento do assembly de personalização ou configurar seu projeto para habilitar o código VBA no documento para chamar 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 Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Comportamento do código VBA em uma personalização no nível do 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 capturam eventos acionados 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ê poderá obter resultados inesperados se os dois conjuntos de código não forem cuidadosamente coordenados e testados.

Chamar código VBA a partir 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 fazer isso, utilize um dos métodos seguintes:

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

  • Para o Excel, chame o Run método da Application 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 da macro. Se você especificar o nome do documento, seu código só poderá executar macros em documentos relacionados ao contexto atual , não apenas em 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 Range que indica onde a função está ou uma ID de registro para uma função DLL (XLL) registrada. Se você passar uma cadeia de caracteres, a cadeia de caracteres 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 seja 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.

Código de chamada em personalizações no nível do documento do VBA

Você pode configurar um projeto em nível de documento para Word ou Excel para que o código VBA 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 no nível do documento associada ao mesmo documento.

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

    As ferramentas de desenvolvimento do Office no Visual Studio oferecem um recurso semelhante para Add-ins do VSTO. Se você estiver desenvolvendo um Add-in VSTO, poderá executar código em seu Add-in VSTO a partir 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, pasta de trabalho do Excel ou projetos de modelo do Excel.

Requirements

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

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

    • Para o Word: .docm ou .doc

    • Para Excel: .xlsm, .xltm, .xlsou .xlt

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

  • 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 para 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 contenha 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 ThisWorkbook para Sheet1 Excel) ou outra classe que você define em seu projeto. Para obter mais informações sobre itens de host, consulte a visão geral de itens de host e controles de host.

Habilitar o código VBA para chamar o assembly de customizaçã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 hospedeiro em um projeto do Visual Basic ao 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, a planilha ou a 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 de qualquer classe pública em um projeto do Visual C# ou membros de uma classe de item que não é host em um projeto do Visual Basic para o 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. Sobrescreva o método GetAutomationObject de uma classe de item hospedeiro em seu projeto, a fim de 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 insere a biblioteca de tipos do assembly de personalização dentro do assembly e adiciona uma referência da biblioteca de tipos ao projeto do 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 apenas na janela Propriedades no tempo de design; eles não podem ser usados 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 executadas pelo Visual Studio ao definir essas propriedades, consulte Tarefas executadas pelas propriedades do item de host.

Observação

Se a pasta de trabalho ou documento ainda não contiver código VBA ou se o código VBA no documento não for confiável para execução, você receberá uma mensagem de erro ao 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 os membros no código VBA para acessar o assembly de personalização

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

  • 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 ao módulo ThisDocument, ThisWorkbook, Sheet1, Sheet2 ou Sheet3 no projeto VBA.

    Você pode usar a CallVSTOAssembly propriedade ou o GetManagedClass 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 em que 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 propriedade CallVSTOAssembly para acessar os membros públicos que você adicionou à classe de item do host. Por exemplo, a macro VBA a seguir chama um método chamado MyVSTOMethod que é definido na classe Sheet1 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 diretamente o método GetManagedClass. 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 host Sheet1 em um projeto de pasta de trabalho do Excel nomeado ExcelWorkbook1 para uso com o 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 a 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 seguinte macro VBA chama um método chamado MyVSTOMethod que é definido na classe de item host Sheet1 em um projeto de pasta de trabalho do Excel chamado ExcelWorkbook1.

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

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

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 em que você pode adicionar código VBA que chama a personalização no nível do documento.

Ao desenvolver e testar sua solução, você pode escrever código VBA no documento que é aberto enquanto depura ou executa seu projeto no Visual Studio (ou seja, o documento na pasta de saída de build). No entanto, qualquer código VBA adicionado a este documento será substituído na próxima vez que você compilar o projeto, pois o Visual Studio substitui o documento na pasta de saída de build por uma cópia do documento da pasta principal do projeto.

Se você quiser salvar o código VBA que você adiciona ao documento durante a depuração ou a 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 build, consulte Criar Soluções do Office.

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 será 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. Primeiro, você deve fechar o documento no designer e abrir o documento diretamente no Word ou no Excel.

Cuidado

Se você adicionar o código VBA executado quando o documento for aberto, em casos raros esse código poderá corromper o documento ou impedir que ele seja aberto no designer.

Na pasta publicar ou instalar

Em alguns casos, pode ser adequado adicionar o código VBA ao documento na pasta de publicação ou instalação. Por exemplo, você poderá 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. 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 de uma pasta de instalação diferente da pasta de publicação, você poderá evitar adicionar o 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 para o documento.

No computador do usuário final

Se os usuários finais forem desenvolvedores do VBA que estão chamando os serviços fornecidos por você na personalização em nível de documento, você pode dizer a eles 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 na solução, o código VBA no documento no computador do usuário final não será sobrescrito, pois o documento não é modificado por atualizações.

Tarefas executadas pelas propriedades do item anfitrião

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 como True em um projeto do Visual Basic, o Visual Studio executa as seguintes tarefas:

  1. Ele adiciona os atributos ComClassAttribute e ComVisibleAttribute à classe de item de 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 como False, o Visual Studio executa as seguintes tarefas:

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

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

    Observação

    O Visual Studio não define automaticamente a propriedade ReferenceAssemblyFromVbaProject como 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 do Visual Basic ou do Visual C# é definida como True, o Visual Studio executa as seguintes tarefas:

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

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

    • A biblioteca de tipos do 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 runtime das Ferramentas do Visual Studio para Office.

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

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

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

Troubleshoot

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

Erro Suggestion
Depois de definir a propriedade EnableVbaCallers ou ReferenceAssemblyFromVbaProject , uma mensagem de erro indica 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, 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 GuidAttribute declaração está ausente ou corrompida. Verifique se a GuidAttribute declaraçã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 indica que o número de versão especificado pelo AssemblyVersionAttribute não é válido. Verifique se a AssemblyVersionAttribute declaração no arquivo AssemblyInfo.cs ou AssemblyInfo.vb em seu projeto está 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 faz chamadas para o assembly de personalização deixa de funcionar. Se você alterar o nome do assembly de personalização depois de expô-lo ao código VBA, o link entre o projeto VBA no documento e o assembly de personalização será interrompido. Para corrigir esse problema, altere a propriedade ReferenceFromVbaAssembly em seu projeto para False e, em seguida, volte para True e substitua todas as referências ao nome do assembly antigo no código VBA pelo novo nome do assembly.

Conteúdo relacionado

  • Last updated on