Partilhar via

Combine o VBA e personalizações no nível do 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 de documento para o Microsoft Office Word ou Microsoft Office Excel. Você pode chamar o código VBA no documento a partir das definições de personalização, ou pode configurar seu projeto para permitir que o código VBA no documento chame o código nas definições 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 do Office e 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 se executar a solução, processadores de eventos tanto no VBA como no assembly de personalização capturam eventos que ocorrem no documento, e ambas as sequências de código são executadas. Você não pode determinar de antemão qual código será executado antes do outro; Você deve determinar isso através 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 módulo 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, use um dos seguintes métodos:

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

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

    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 diferentes formatos 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 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, 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 o 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 de nível de documento do VBA

Você pode configurar um projeto ao nível do documento para Word ou Excel, de modo que o código de Visual Basic for Applications (VBA) presente no documento possa chamar o código no assembly de personalização. Isto é ú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 os serviços desenvolvidos em uma personalização no nível do 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, você pode 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.

Requerimentos

Antes de ativar o código VBA para invocar o assembly de personalização, o 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.

  • O código VBA no documento deve ter permissão para ser executado sem solicitar que o usuário habilite macros. Você pode confiar na execução do código VBA 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 e Sheet1 para Excel) ou outra classe que você define em seu projeto. Para obter mais informações sobre itens de host, consulte Visão geral de itens de host e controles de host.

Ativar 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 host num projeto do Visual Basic para utilização no 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 num projeto de Visual C# ou membros numa classe de item não principal num projeto de Visual Basic para a 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 ao 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. Este incorpora a biblioteca de tipos do assembly de personalização no assembly e adiciona uma referência dessa biblioteca de tipos ao projeto VBA no documento.

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

    As propriedades EnableVbaCallers e ReferenceAssemblyFromVbaProject estão disponíveis somente na janela Properties em tempo de design; eles não podem ser usados em tempo de execução. Para exibir as propriedades, abra o designer de 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 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 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.

Usar membros no código VBA para chamar a assemblagem de personalização

Depois de configurar o projeto para ativar 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 se expõem membros de uma classe de item de host usando a propriedade EnableVbaCallers, o Visual Studio também adiciona uma propriedade denominada CallVSTOAssembly ao módulo ThisDocument, ThisWorkbook, Sheet1, Sheet2 ou Sheet3 no projeto VBA.

    Você pode usar a propriedade CallVSTOAssembly ou método GetManagedClass para acessar membros públicos da classe que tornou acessível 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

Utilize a propriedade CallVSTOAssembly para aceder a membros públicos que adicionou ao item de classe 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

Esta propriedade é uma maneira mais conveniente de invocar 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 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ê tenha exposto a classe de item de Sheet1 host em um projeto de pasta de trabalho do Excel nomeado ExcelWorkbook1 para VBA.

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

Use 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 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 MyVSTOMethod que é definido na Sheet1 classe de item de host 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 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 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 se pode adicionar código VBA que invoca a personalização a 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ê depurar ou executar seu projeto no Visual Studio (ou seja, o documento na pasta de saída de compilação). No entanto, qualquer código VBA que você adicionar 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 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 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 principais de documentos 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 esta 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.

Atenção

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. 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 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 o documento.

No computador do utilizador final

Se os usuários finais forem desenvolvedores do VBA que estão chamando os serviços que você fornece na personalização no nível do documento, você poderá 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 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 do item host.

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

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

    Quando você define a propriedade EnableVbaCallers de volta para False, o 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, o Visual Studio executa as seguintes tarefas:

  1. Gera uma biblioteca de tipos para o assembly de personalização e integra a biblioteca de tipos nesse assembly.

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

    • A biblioteca de tipos para o seu conjunto 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 de volta para 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 conjunto.

Troubleshoot

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 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. Certifique-se de que o documento no projeto contém pelo menos uma macro VBA, o projeto VBA tem confiança suficiente para ser executado e 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 da versão especificado pelo parâmetro AssemblyVersionAttribute não é válido. Certifique-se de que 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 chama o assembly de personalização para 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, de volta 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

  • Last updated on