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

Você pode usar o código do Visual Basic é Applications (VBA) em um documento que é parte de uma personalização da nível do Microsoft Office Word e Microsoft Office Excel.Você pode chamar código de VBA no documento do assembly de personalização, ou você pode configurar seu projeto ativar o código de VBA no documento para chamar código no assembly de personalização.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de documento para os seguintes aplicativos: Excel 2013 e Excel 2010; Word 2013 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Comportamento do código de VBA em uma personalização da Nível

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

Quando você executa a solução, os manipuladores de eventos no VBA e o assembly de personalização web pegam os eventos que são criados no documento, e dois conjuntos de execução de código.Você não pode determinar de antemão que o código será executado antes de outro; você deve determinar isso com os testes em cada caso individuais.Você pode obter resultados inesperados se os dois conjuntos de código não são de coordenadas e não são cuidadosamente testados.

Código de VBA de chamada do assembly de personalização

Você pode chamar macros em documentos da palavra, e você pode chamar macros e funções nas pastas de trabalho do Excel.Para fazer isso, use um dos seguintes métodos:

• Para palavras, chame o método de Run da classe de Microsoft.Office.Interop.Word.Application .

• Para o excel, chame o método de Run da classe de Microsoft.Office.Interop.Excel.Application .

Para cada método, o primeiro parâmetro identifica o nome de macros ou funciona você deseja chamar, e parâmetros opcionais restantes especificam os parâmetros para passar a macro ou à função.O primeiro parâmetro pode ter vários formatos diferentes para palavra e Excel:

• Para palavras, o primeiro parâmetro é uma cadeia de caracteres que pode ser qualquer combinação de modelo, de módulo, e de nome macro.Se você especifica o nome do documento, seu código pode ser executado somente 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 Range macros, indicando onde a função é, ou uma identificação do registro para uma função de DLL registrada XLL ().Se você passar uma cadeia de caracteres, a cadeia de caracteres será avaliada no contexto de folha.

O exemplo de código a seguir mostra como chamar uma macro denominada MyMacro de um projeto da nível do excel.este exemplo assume que MyMacro está definido em Sheet1.

Globals.Sheet1.Application.Run("MyMacro")

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 de missing no lugar dos parâmetros opcionais no visual C#, consulte Escrevendo código em soluções do Office.

Chamando o código em personalizações da Nível de VBA

Você pode configurar um projeto de nível para a palavra ou do excel de modo que o código do Visual Basic é VBA Applications () no documento pode chamar código no assembly de personalização.Isso é útil nas seguintes situações:

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

• Você deseja fazer os serviços que você desenvolve em uma personalização da nível disponível aos usuários finais que podem acessar os serviços escrevendo código de VBA no documento.

Ferramentas de desenvolvimento do Office no Visual Studio fornecem um recurso semelhante para suplementos do aplicativo.Se você estiver desenvolvendo um suplemento, você pode chamar código no suplemento de outras soluções do Office.Para obter mais informações, consulte Chamar código nos suplementos de nível de aplicativo de outras soluções do Office.

Observação
Esse recurso pode não ser usado em projetos do modelo de palavras.Pode ser usado apenas em projetos de documento do word, o modelo de pasta de trabalho do Excel, ou Excel.

Requisitos

Antes que você possa ativar o código de VBA para chamar no 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 palavra: .docm ou .doc

  • Para o excel: .xlsm, .xltm, .xls, ou .xlt

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

• O código de VBA no documento deve ser permitido executar sem avisar o usuário para ativar macros.Você pode confiar o código de VBA para executar adicionando o local do projeto do Office à lista de locais confiáveis nas configurações do centro de confiança por palavras 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á exposto a VBA.

  Você pode expor, propriedades, métodos e eventos a VBA.A classe que você exponha pode ser uma classe de item host (como ThisDocument por palavras, ou ThisWorkbook e Sheet1 para o excel) ou outra classe que você define em seu projeto.Para obter mais informações sobre os itens host, consulte Itens de host e visão geral sobre controles de Host.

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

Há duas maneiras diferentes que você pode expor membros em um conjunto de personalização para o código de VBA no documento:

• Você pode expor membros de uma classe de item host em um projeto de Visual Basic a VBA.Para fazer isso, defina a propriedade de EnableVbaCallers de item host a True na janela de Propriedades quando o item host (isto é, o documento, a planilha, ou pasta de trabalho) é aberto no designer.O Visual Studio automaticamente executa qualquer trabalho necessário para ativar o código de 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 de host não em Visual Basic projeto, a VBA.Esta opção fornece mais liberdade para escolher as classes que você exponha a VBA, mas também requer as etapas manuais mais.

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

  1. A classe expõe um COM.

  2. Substituir o método de GetAutomationObject de uma classe de item host em seu projeto retornar uma instância da classe que você está exposto a VBA.

  3. Defina a propriedade de ReferenceAssemblyFromVbaProject de qualquer classe de item de projeto host na True.Isso insere a biblioteca de tipo do conjunto de personalização no assembly e adiciona uma referência à biblioteca de tipo para o projeto de VBA no documento.

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

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

Observação
Se a pasta de trabalho ou o documento não contêm o código de VBA ou se o código de VBA no documento não é confiável para executar, você receberá uma mensagem de erro quando você define a propriedade de EnableVbaCallers ou de ReferenceAssemblyFromVbaProject a True.Isso ocorre porque o Visual Studio não pode alterar o projeto de VBA no documento em esta situação.

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

Depois que você configura seu projeto ativar o código de VBA para chamar no assembly de personalização, o Visual Studio adiciona os seguintes membros ao projeto de VBA no documento:

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

• Para Visual Basic projetos em que você expõe membros de uma classe de item host usando a propriedade de EnableVbaCallers , o Visual Studio também adiciona uma propriedade chamada CallVSTOAssembly a ThisDocument, a ThisWorkbook, a Sheet1, a Sheet2, ou módulo de Sheet3 no projeto de VBA.

Você pode usar a propriedade de CallVSTOAssembly ou o método de GetManagedClass para acessar membros públicos de classes que você tenha expostos a VBA o código no projeto.

Observação
Quando você desenvolver e implantar sua solução, há várias cópias diferentes de documento onde você pode adicionar código de VBA.Para obter mais informações, consulte diretrizes para adicionar o código de VBA ao documento.

Usando a propriedade de CallVSTOAssembly em um projeto do Visual Basic

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

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

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

A propriedade de CallVSTOAssembly tem uma declaração que é semelhante ao seguinte código.Este código presume que você tenha expostos a classe de item host de Sheet1 em um projeto de pasta de trabalho do Excel chamado ExcelWorkbook1 a VBA.

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

usando o método de GetManagedClass

Para usar o método global de GetManagedClass , passe o objeto de VBA que corresponde à classe de item host que contém sua sobrescrita do método de GetAutomationObject .Em seguida, use o objeto retornado para acessar a classe que você tenha expostos a VBA.

Por exemplo, as chamadas a macro de VBA um método chamado MyVSTOMethod que é definido na classe de item host de 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 método de GetManagedClass tem a seguinte declaração.

GetManagedClass(pdispInteropObject Object) As Object

Esse método retorna um objeto que representa a classe que você tenha expostos a VBA.Os membros e os parâmetros do método do objeto retornado aparecem no IntelliSense.

diretrizes para adicionar o código de VBA ao documento

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

Como você desenvolve e testar sua solução, você pode escrever código de VBA no documento que abre quando você depura ou executar seu projeto no Visual Studio (isto é, o documento na pasta de saída de compilação).Entretanto, qualquer código que você adicionar a VBA de este documento será substituído na próxima vez que você criar o projeto, como o Visual Studio substitui o documento na pasta de saída de compilação com uma cópia do documento da pasta do projeto.

Se você deseja salvar o código de VBA que você adiciona ao documento a depuração ou executar a solução, copiar o código de VBA no documento na pasta do projeto.Para obter mais informações sobre o processo de compilação, consulte Construindo soluções do Office.

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

Em a pasta do projeto no computador de desenvolvimento

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

Você não pode adicionar código de VBA quando o documento está aberto no designer.Primeiro você deve fechar o documento no designer, e então abra o documento diretamente nas palavras ou Excel.

Cuidado
Se você adicionar o código de VBA que é executado quando o documento está aberto, em casos raros este código pode danificar o documento ou impedi-lo de abertura no designer.

Em a pasta de instalação ou publicar

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

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

Se os usuários instalar a solução de uma pasta de instalação que seja diferente do diretório de publicação, você pode evitar adicionar o código de VBA no documento sempre que você publica a solução.Quando uma atualização de publicação estiver pronto para ser movido da pasta publicar a pasta de instalação, copiar todos os arquivos na pasta de instalação para a exceção do documento.

Em o computador do usuário final

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

Tarefas executadas pelas propriedades de item do host

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

EnableVbaCallers

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

1. Adiciona ComClassAttribute e atributos de ComVisibleAttribute ao item host classe.

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

3. Defina a propriedade de ReferenceAssemblyFromVbaProject de item host a True.

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

1. Remove ComClassAttribute e atributos de ComVisibleAttribute de ThisDocument classe.

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

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

ReferenceAssemblyFromVbaProject

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

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

2. Adiciona uma referência às seguintes bibliotecas de tipo no projeto de VBA no documento:

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

   • Ferramentas do Microsoft Visual Studio para a biblioteca de tipos 9,0 do mecanismo de execução do Office.Esta biblioteca de tipos é incluída em Visual Studio Tools for Office Runtime.

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

1. Remove as referências de biblioteca de tipo de projeto de VBA no documento.

2. Remove a biblioteca inserida de tipo do assembly.

Solução de problemas

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

Consulte também

Tarefas

Como: expor um código VBA em um projeto de Visual Basic

Como: expor um código VBA em um projeto do Visual C#

Passo a passo: Chamar o código do VBA em um projeto de Visual Basic

Passo a passo: Chamar o código do VBA em um projeto do Visual C#

Conceitos

VBA e soluções do Office em Visual Studio em comparação comparada

Outros recursos

Projetando e criando soluções do Office

Programação personalizações em nível de documento