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

Artigo
08/08/2011

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

Você deseja estender o código do VBA existente em um documento usando os recursos em uma personalização em nível de documento que está associada com o mesmo documento.
Você deseja disponibilizar serviços que você desenvolva uma personalização de nível de documento para os usuários finais que podem acessar os serviços, escrevendo o código do VBA no documento.

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

As ferramentas de desenvolvimento do Office em Visual Studio oferecem um recurso semelhante para suplementos de nível de aplicativo. Se você estiver desenvolvendo um add-in, você pode chamar o código no seu suplemento de outras soluções de Microsoft Office. For more information, see Código de chamada no nível do aplicativo Add-ins de outras soluções do Office.

Observação
Este recurso não pode ser usado em projetos de modelo do Word. Ele pode ser usado somente no documento do Word, pasta de trabalho do Excel ou projetos de modelo do Excel.

Requirements

Antes de ativar o código do VBA 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 o Word: . docm ou. doc
- Para o Excel: . xlsm,. xltm,. xls ou. xlt
O documento já deve conter um projeto do VBA que contém um código VBA.
O código do VBA do documento deve ser permitido para executar sem perguntar ao usuário ativar macros. Você pode confiar em código VBA, adicionando o local do projeto do Office à lista de locais confiáveis em que as configurações da Central de confiabilidade para o 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ê estiver expondo a VBA.

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

Ativando o código do VBA chamar o Assembly de personalização

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

Você pode expor os membros de uma classe de item de host em um Visual Basic o projeto VBA. Para fazer isso, defina a EnableVbaCallers a propriedade do item de host para True na Propriedades janela enquanto o item de host (isto é, o documento, planilha ou pasta de trabalho) está aberta no designer. Visual Studio realiza automaticamente todo o trabalho necessário para habilitar o código do VBA chamar membros da classe.
Você pode expor os membros em qualquer classe pública em um projeto do Visual C# ou classe do item de membros em um host não um Visual Basic o projeto, a VBA. Essa opção oferece mais liberdade para escolher quais classes que você exponha ao VBA, mas ele também requer mais etapas manuais.

Para fazer isso, você deve executar as seguintes etapas principais:
1. Expor a classe COM.
2. Substituir o GetAutomationObject método de uma classe de item de host em seu projeto para retornar uma instância da classe que você está expondo a VBA.
3. Definir o ReferenceAssemblyFromVbaProject a propriedade de qualquer classe de item de host no projeto True. Isso incorpora a biblioteca de tipos do assembly de personalização no assembly e adiciona uma referência à biblioteca de tipos para o projeto do VBA no documento.

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

O EnableVbaCallers e ReferenceAssemblyFromVbaProject propriedades só estão disponíveis na Propriedades janela em 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 em Visual Studio. Para obter mais informações sobre as tarefas específicas que Visual Studio executa quando você definir essas propriedades, consulte Tarefas executadas pelas propriedades de Item de Host.

Observação
Se a pasta de trabalho ou o documento ainda não contiver código VBA ou se o código do VBA no documento não é confiável para executar, você receberá uma mensagem de erro ao definir o EnableVbaCallers ou ReferenceAssemblyFromVbaProject propriedade para True. Isso ocorre porque Visual Studio não é possível modificar o projeto VBA do documento nesta situação.

O uso de membros no código VBA para chamar o Assembly de personalização

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

Para todos os projetos, Visual Studio adiciona um método global chamado GetManagedClass.
Para Visual Basic classe do item de projetos em que você exponha membros de um host usando o EnableVbaCallers propriedade, Visual Studio também adiciona uma propriedade chamada CallVSTOAssembly para o ThisDocument, ThisWorkbook, Sheet1, Sheet2, ou Sheet3 o módulo no projeto VBA.

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

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

Usando a propriedade CallVSTOAssembly em um projeto de Visual Basic

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

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

Esta propriedade é uma forma mais conveniente para chamar o assembly de personalização que usar o GetManagedClass método diretamente. CallVSTOAssemblyRetorna um objeto que representa o host a classe do item que você está exposto a VBA. Os membros e os parâmetros do método do objeto retornado aparecem em IntelliSense.

O CallVSTOAssembly a propriedade tem uma declaração semelhante para o código a seguir. Esse código pressupõe que você tenha exposto a Sheet1 classe do item de host em um projeto de pasta de trabalho do Excel chamado ExcelWorkbook1 para VBA.

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

Usando o método GetManagedClass

Para usar o modelo global da GetManagedClass método, passar o objeto do VBA que corresponde à classe de item de host que contém a substituição da GetAutomationObject método. Em seguida, use o objeto retornado para acessar a classe que é exposto a VBA.

Por exemplo, a macro VBA a seguir chama um método chamado MyVSTOMethod que está definido na Sheet1 classe do 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 o método tem a seguinte declaração.

GetManagedClass(pdispInteropObject Object) As Object

Esse método retorna um objeto que representa a classe que você está exposto a VBA. Os membros e os parâmetros do método do objeto retornado aparecem em IntelliSense.

Diretrizes para adicionar o código do VBA para o documento

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

Como desenvolver e testar sua solução, você pode escrever o código do VBA no documento que será aberta enquanto você depurar ou executa o projeto em Visual Studio (ou seja, o documento na pasta de saída de compilação). No entanto, qualquer código do VBA que você adicionar a este documento será substituído na próxima vez que você constrói o projeto como Visual Studio substitui o documento na pasta de saída de compilação com uma cópia do documento da pasta do projeto principal.

Se você deseja salvar o código do VBA que você adicionar ao documento durante a depuração ou executando a solução, copie o código do VBA para o documento na pasta do projeto. Para obter mais informações sobre o processo de compilação, consulte Visão Geral do Processo de Compilação de uma Solução Office.

Quando estiver pronto para implantar sua solução, existem três locais do documento principal, na qual você pode adicionar o código do VBA.

Na pasta do projeto no computador de desenvolvimento

Esse local é conveniente se você tem total controle sobre o código do VBA no documento e o código de personalização. Porque o documento está no computador de desenvolvimento, você pode modificar facilmente o código do VBA se você alterar o código de personalização. Código do VBA que você adicionar a esta cópia do documento permanecerá no documento quando você criar, depurar e publica a sua solução.

É possível adicionar o código do VBA para o documento enquanto ele está aberto no designer. Você deve primeiro fechar o documento no designer e, em seguida, abra o documento diretamente no Word ou Excel.

Aviso

Se você adicionar o código do VBA que é executado quando o documento for aberto, em casos raros esse código pode corromper o documento ou impedir a abertura no designer.

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

Em alguns casos, talvez seja adequado adicionar o código do VBA para o documento na pasta de instalação ou publicar. Você pode, por exemplo, escolha esta opção se o código do VBA é gravado e testado por um desenvolvedor diferente em um computador que não tem o Visual Studio instalado.

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

Se os usuários instalarem a solução de uma pasta de instalação é diferente da pasta de publicação, você pode evitar adicionando o código do VBA do documento sempre que você publique a solução. Quando uma atualização de publicação está pronta para ser movida a partir 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 são desenvolvedores VBA que estão chamando em serviços que você fornecer personalização de nível de documento, você poderá dizê-los como chamar seu código usando o 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 do VBA no documento no computador do usuário final não serão substituídos, porque o documento não é modificado por publicar atualizações.

Tarefas executadas pelas propriedades de Item de Host

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

EnableVbaCallers

Ao definir o EnableVbaCallers a propriedade de um item de host para True em um projeto de Visual Basic, Visual Studio realiza as seguintes tarefas:

Ele adiciona o ComClassAttribute e ComVisibleAttribute atributos para o item de host classe.
Ela substitui o GetAutomationObject o método do item de host classe.
Ele define o ReferenceAssemblyFromVbaProject a propriedade do item de host, a True.

Ao definir o EnableVbaCallers propriedade de volta para False, Visual Studio realiza as seguintes tarefas:

Ele remove o ComClassAttribute e ComVisibleAttribute atributos a partir de ThisDocument classe.

Ele remove o GetAutomationObject método a partir do item de host classe.

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

ReferenceAssemblyFromVbaProject

Quando o ReferenceAssemblyFromVbaProject de qualquer item de host em um projeto de Visual Basic ou C# Visual for definida como True, Visual Studio realiza as seguintes tarefas:

Ele gera uma biblioteca de tipos para o assembly de personalização e incorpora a biblioteca de tipos no assembly.
Ele adiciona uma referência para as seguintes bibliotecas de tipo no projeto VBA do documento:
- A biblioteca de tipos para o assembly de personalização.
- O Microsoft Visual Studio Tools para o Office a execução do mecanismo 9.0 biblioteca de tipos. Esta biblioteca de tipos está incluída na Visual Studio Tools for Office runtime.

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

Ele remove as referências de biblioteca de tipo do projeto VBA no documento.
Ela remove a biblioteca de tipos incorporada do assembly.

Troubleshooting

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

Error	Suggestion
Depois de definir o EnableVbaCallers ou ReferenceAssemblyFromVbaProject propriedade, uma mensagem de erro informa que o documento não contém um projeto do VBA, ou você não tem permissão para acessar o projeto VBA do documento.	Certifique-se de que o documento do projeto contém pelo menos uma macro do VBA, o projeto VBA possui confiança suficiente para executar e o projeto do VBA não está protegido por senha.
Depois de definir o EnableVbaCallers ou ReferenceAssemblyFromVbaProject propriedade, uma mensagem de erro informa que o GuidAttribute declaração está ausente ou corrompido.	Certifique-se de que o GuidAttribute declaração está localizada no arquivo AssemblyInfo. cs ou AssemblyInfo. vb no seu projeto, e que esse atributo é definido para um GUID válido.
Depois de definir o EnableVbaCallers ou ReferenceAssemblyFromVbaProject uma mensagem de erro de propriedade, que declara que o número de versão especificado pelo AssemblyVersionAttribute não é válido.	Certifique-se de que o AssemblyVersionAttribute declaração no arquivo AssemblyInfo. cs ou AssemblyInfo. vb no seu projeto está definida para um número de versão do assembly válido. Para obter informações sobre números de versão do assembly válido, consulte o AssemblyVersionAttribute classe.
Após renomear o assembly de personalizaçã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 expô-lo ao código VBA, o link entre o projeto VBA do documento e seu assembly de personalização é quebrado. Para corrigir esse problema, altere o ReferenceFromVbaAssembly propriedade em seu projeto para False e depois voltar ao Truee substitua todas as referências ao antigo nome de assembly no código VBA com o novo nome de assembly.

Consulte também

Compartilhar via