Adicionando refer�ncias dinamicamente no VBA

 Requisitos do sistema

  • Microsoft Office (mais de uma vers�o dispon�vel que suporte o Visual Basic for Applications)

 Introdu��o

Em muitos projetos VBA, existe a necessidade de adicionar refer�ncias para habilitar alguns recursos, por exemplo, manipular um documento do Word ou outro aplicativo do Office, a inser��o de um novo controle ou mesmo acessar um Banco de dados via ADO, o que exigiria a refer�ncia a uma biblioteca do Microsoft Active Data Objects.

Quando h� alguma incompatibilidade de vers�es ou mesmo a aus�ncia dessas refer�ncias que geralmente s�o componentes .DLL ou .OCX, o aplicativo n�o funcionar� e resultar� em erro acusando que a biblioteca est� ausente. Por�m, � poss�vel adicionar, retirar ou mesmo verificar essas refer�ncias via c�digo VBA. Isso possibilita contornar uma s�rie de problemas, desde a aus�ncia de um software na m�quina cliente at� mesmo uma adapta��o � vers�o de um aplicativo.

Para que este recurso funcione, � necess�rio entender alguns conceitos que ser�o explicados a seguir.

Confian�a sobre a manipula��o

� preciso permitir que esse tipo de manipula��o seja feita. Isso ocorre porque o VBA � concebido para manipular objetos dos aplicativos em que ele est� hospedado, por exemplo, o Excel, Word ou o Corel Draw. No n�vel padr�o de seguran�a, a manipula��es convencionais s�o permitidas, mas � poss�vel manipular o VBA atrav�s do pr�prio VBA para permitir a��es como cria��o de formul�rios (UserForms), m�dulos, controles entre outras rotinas que normalmente fazemos, at� mesmo cria refer�ncias que � o assunto deste artigo.

Delegando confian�a

Por padr�o esse tipo de manipula��o n�o � permitido. Para acion�-la, � preciso ir � op��es de seguran�a de Macro no aplicativos que encontra-se geralmente no menu Ferramentas->Macro->Seguran�a. Ao acionar esta op��o, surgir� a seguinte caixa de di�logo:

Figura 1: Op��es de Seguran�a de Macro

Acione a aba Fontes confi�veis e veja logo abaixo a op��o Confiar no acesso ao projeto do Visual Basic. Por padr�o est� desabilitada. Habilite-a para poder prosseguir com os exemplos e clique em OK.

 Testando o aplicativo

 Para tornar o teste id�neo, � interessante ter dispon�vel mais de uma vers�o do Office. Para este exemplo, vamos construir o aplicativo em Excel-VBA em que criaremos um novo arquivo do Word.

 Abra o Excel e acione o editor do VBA pelo menu Ferramentas->Macros->Editor do Visual Basic  ou com o atalho Alt+F11. No VBA, acione ao menu Ferramentas->Refer�ncias para visualizar as refer�ncias existentes e dispon�veis. Procure pela refer�ncia Microsoft Word XX.0 Object Library onde XX � o numero da vers�o do Office instalada em seu computador:

Office

N� Vers�o

Microsoft Office 97

8.0

Microsoft Office 2000

9.0

Microsoft Office XP

10.0

Microsoft Office 2003

11.0

Como estou fazendo este aplicativo na vers�o 2003, a biblioteca referenciada ser� a Microsoft Word 11.0 Object Library conforme mostra a figura:

 

Figura 2: Refer�ncias do aplicativo

 Agora, insira um m�dulo convencional indo ao menu Inserir->M�dulo. Nesse m�dulo, coloque o seguinte c�digo:

 

  Public Sub AbreWord()

    Dim versao As String
   
'Declara uma vari�vel do tipo Word.Application (aplicativo)
    Dim arqWord As Word.Application
    'Declara uma vari�vel do tipo Word.Document (documento)
    Dim docWord As Word.Document
    'Cria uma nova inst�ncia do Word
 
   arqWord = CreateObject("Word.Application")
    'Esta linha serve para criar um documento em branco
    docWord = arqWord.Documents.Add
    'Torna o Word Vis�vel
    arqWord.Visible = True
    'Captura a vers�o do Word
    Versao = arqWord.Version
    'Escreve texto no arquivo

    arqWord.Selection.TypeText("Ol� Word " & versao & "!")

  End Sub

Se a refer�ncia estiver sido feita corretamente. ser� poss�vel usufruir dos recursos do Intellisense para escrever o c�digo. No Word 2003, o resultado da execu��o do c�digo � uma nova inst�ncia e um novo documento do Word com o seguinte texto:

 

Figura 3: Arquivo de Word gerado pela Macro �AbreWord� no Word 2003

A Macro pegou a vers�o do Word referenciada, criou um novo documento colocando o texto que foi composto com o n�mero da vers�o do Word, neste caso, 11.0.

 Com a Macro funcionando, vamos agora test�-la em outra vers�o do Office. Neste caso, utilizarei a vers�o 2000. Abra a planilha no Excel 2000 e tente executar a Macro. Facilite o acesso com o atalho Alt+F8 para mostrar a Macro e clique em executar:

 

Figura 4: Executando a Macro

 

Se tudo der certo (ou errado), surgir� a seguinte mensagem:

 

Figura 5: Erro gerado pela Macro executada no Excel 2000

 Clique em OK e veja que o editor parou a execu��o do c�digo na linha em declaramos o Objeto Word.Application. 

Figura 6: Vericando a linha de erro da Macro 

Verifique as refer�ncias feitas inda � caixa de di�logo de refer�ncias (Ferramentas->Refer�ncias o VBA) e veja que a biblioteca Microsoft Word 11.0 Object Library est� marcada como AUSENTE: 

Figura 7: Vericando a aus�ncia da refer�ncia 

Para resolver o problema de funcionamento da Macro, bastaria desfazer essa refer�ncia e procurar a Microsoft Word 9.0 Object Library que � correspondente ao Office instalado. Ap�s isso, tente executar novamente a Macro. O resultado dever� ser este: 

Figura 8: Arquivo de Word gerado pela Macro AbreWord no Word 2000 

Veja que o texto gerado dinamicamente pela Macro obedeceu ao crit�rio de vers�o e alterou o n�mero colocado no texto (Se executar a Macro no Office XP, a vers�o apresentada ser� 10.0). Feche o arquivo do Word, salve a planilha no Excel 2000 e abra-a no Excel 2003 novamente. Ao executar a Macro, ela funcionar� normalmente. Porque? Abra o VBA, acione o menu Ferramentas->Refer�ncias e veja que a refer�ncia foi atualizada para o Microsoft Word 11.0 Object Library. 

Neste ponto, chegamos a algumas conclus�es e solu��es para o problema: 

Desenvolver sempre numa vers�o mais antiga para garantir o funcionamento em qualquer vers�o do Office?

O problema � que limitar�amos aos recursos de uma vers�o mais antiga al�m do fato de se a o aplicativo for aberto em alguma vers�o superior e for salvo, ele manter� a refer�ncia da �ltima vers�o do aplicativo em que foi aberto provocando novamente o problema de versionamento. 

Ter instalada todas as vers�es do Office para incluir todas as refer�ncias?

Talvez desse certo, mas quem se disponibiliza tanto financeiramente como em recursos de m�quina e conflitos gerados a ter instalada todas as vers�es do aplicativo? 

Cria e manter a refer�ncias dinamicamente?

Essa creio eu ser a melhor sa�da. N�o � completamente infal�vel, mas j� testei em v�rios ambientes e se comportou muito bem. 



Como adicionar as refer�ncias via c�digo 

Al�m dos conceitos de seguran�a e permiss�es discutidos no come�o do artigo, � preciso se acostumar um pouco com os elementos das refer�ncias. Para que a manipula��o funcione, � preciso fazer refer�ncia � bilbioteca Microsoft Visual Basic for Applications Extensibility 5.3. Essa � a biblioteca que permite manipular objetos do VBA, tanto do VBA como desde outras ferramentas como Visual Basic 6 ou Visual Basic .NET. Essa bilbioteca � instalada juntamente com o VBA e a garantia que ela esteja presente na m�quina cliente � de quase 100%, j� que na instala��o padr�o do Office o VBA � tamb�m instalado. 

Vamos fazer um exemplo que use objetos dessa biblioteca. Insira um m�dulo convencional na mesma planilha que fizemos anteriormente no Excel 2003 e coloque o seguinte c�digo: 

  Public Sub ChecaReferencias()

     Dim mensagem As String
    'Faz a refer�ncia ao projeto VBA
    Dim vbProj As VBProject
    'A referencia em si
    Dim chkRef As Reference 

    'Seta a vari�vel para o projeto da pasta de trabalho ativa.
    vbProj = ActiveWorkbook.VBProject
 

    'Checa as refer�ncias selecionadas (veja na caixa de di�logo Refer�ncias)
   
For Each chkRef In vbProj.References
     
'monta a string que conter� o nome de todas as refer�ncias
      mensagem = mensagem & " " & chkRef.Name & Chr(13)
    Next
    'Mostra a mensagem com o nome das refer�ncia selecionadas
    MsgBox(mensagem)

  End Sub

Execute a Macro. N�o se esque�a de adicionar a refer�ncia � biblioteca de manipula��o, como dito anteriormente. O resultado dever� ser algo parecido com este: 

Figura 9: Resultado gerado pela Macro ChecaReferencias 

Voc� pode fazer uma equival�ncia do resultado desta Macro abrindo a caixa de di�logo Refer�ncias do VBA: 

Figura 10: Verificando as refer�ncias

 

Teoricamente est� tudo OK. Com esse c�digo, podemos saber e aprender mais sobre as refer�ncias e seus atributos. Modifique a linha de c�digo que monta a mensagem para o seguinte: 

mensagem = mensagem & "Nome: " & chkRef.Name & " - Caminho: " & chkRef.FullPath & " - Descri��o: " & chkRef.Description & Chr(13)

Execute a Macro desta vez. O resultado deve ser o seguinte: 

Figura 11: Resultado gerado pela Macro ChecaReferencias com a mensagem alterada 

Agora temos uma forma simples de obter mais informa��es sobre as refer�ncias com que trabalhamos no VBA. Os atributos mais importantes a serem trabalhados para este artigo s�o o IsBroken, GUID, Major e Minor. 

A propriedade IsBroken retorna False se a refer�ncia estiver OK e True se estiver quebrada, por exemplo, quando a caixa de di�logo acusa que a refer�ncia est� AUSENTE, � um caso em que o IsBroken retornar� True. Isso nos ajuda a verificar a exist�ncia de uma refer�ncia que nos disponibiliza determinada funcionalidade, por exemplo, uma .OCX que contenha um controle ActiveX como o Calendar Control. Dependendo do resultado, voc� pode optar por rodar ou n�o o projeto. 

A propriedade GUID retorna o identificador �nico para a refer�ncia. Para ver esta identifica��o, modifique a linha de c�digo que monta a mensagem para o seguinte: 

mensagem = mensagem & "Nome: " & chkRef.Name & " - GUID: " & chkRef.GUID & " - Major: " & chkRef.Major & " - Minor: " & chkRef.Minor & Chr(13)

 Veja o resultado: 

Figura 12: Resultado gerado pela Macro ChecaReferencias com a mensagem alterada 

Com alguma pesquisa, pude confirmar que esse identificador � o mesmo independente de vers�o. Se voc� testar em qualquer outra vers�o o mesmo c�digo, ver� que os GUIDs n�o ser�o alterados. � essa propriedade que usaremos para adicionar e remover as refer�ncias em nossos aplicativos. As propriedades Major e Minor n�o requerem maiores estudos e ser�o usadas somente para a execu��o do m�todo que adiciona a refer�ncia, conforme veremos a seguir. 

Os m�todos utilizados para adicionar e remover refer�ncias s�o o AddFromGUID, AddFromFile e Remove. 

O m�todo AddFromFile adiciona a refer�ncia com base no caminho do arquivo. � uma op��o, mas pode ser problem�tica, pois precisar�amos saber qual o diret�rio em que foi instalado o aplicativo, o que � vezes pode ser um mist�rio. Para contornar a situa��o, podemos usar o m�todo Application.Path que retorna o diret�rio em que foi instalado o Office para adicionar a refer�ncia. 

O m�todo AddFromGUID adiciona a refer�ncia com tr�s par�metros: GUID, Major e Minor, que s�o as propriedades discutidas anteriormente. O GUID pode ser passado como String e as vari�veis Major e Minor devem ser passadas como Long. 

Pegar os dados requer c�digo como fizemos anteriormente. Com isso, temos para a biblioteca Microsoft Word os seguintes valores: 

GUID: {00020905-0000-0000-C000-000000000046}
Major
: 8
Minor
: Depende da vers�o. 

A vari�vel Minor possui um valor que varia conforme a vers�o do aplicativo. Para regularizar esse valor, a melhor maneira que encontrei foi pegando o valor do Application.Version. A diferen�a entre os dois valores � sempre de 8 unidades, portanto podemos fazer uma analogia para determinar o valor do par�metro. Veja a diferen�a do resultado da Macro ChecaReferencias executada no Excel 2000 e no Excel 2003: 

Figura 13: Resultado gerado pela Macro ChecaReferencias no Excel 2000 

Figura 14: Resultado gerado pela Macro ChecaReferencias no Excel 2003  

O m�todo Remove remove a refer�ncia em si. � preciso passar uma vari�vel do tipo Reference para que funcione. 

Tendo visto todas estas op��es, consegui chegar � seguintes solu��es para nosso problema. Abaixo proponho um modelo de c�digo que pode tornar o aplicativo VBA praticamente universal para todas as vers�es do Office: 

  Public Sub AdicionaReferenciaWord()

     'Faz a refer�ncia ao projeto VBA
    Dim vbProj As VBProject
    'A referencia em si
    Dim versao As Long
 

    'Seta a vari�vel para o projeto da pasta de trabalho ativa.
    vbProj = ActiveWorkbook.VBProject 

    'Pega a vers�o atual do Office e corrige a vari�vel
    versao = CLng(Application.Version) / 10 

    'Adiciona a refer�ncia do Word via GUID:
    vbProj.References.AddFromGuid("{00020905-0000-0000-C000-000000000046}", 8, versao - 8) 

  End Sub

   Public Sub RemoveReferenciaWord() 

    'Faz a refer�ncia ao projeto VBA
    Dim vbProj As VBProject
    'A referencia em si
    Dim chkRef As Reference

    'Seta a vari�vel para o projeto da pasta de trabalho ativa.
   
vbProj = ActiveWorkbook.VBProject

    For Each chkRef In vbProj.References
     
'Verifica se a refer�ncia � do Word:
     
If chkRef.GUID = "{00020905-0000-0000-C000-000000000046}" Then
        'Se for, remove
        vbProj.References.Remove(chkRef)
      End If
   
Next

  End Sub

Insira esse c�digo em um m�dulo vazio de uma na planilha em que estamos trabalhando adicionando a refer�ncia ao Microsoft Visual Basic for Applications Extensibility 5.3. Insira tamb�m o c�digo para gerar o novo arquivo no Word conforme no come�o do artigo. Agora, basta colocar a chamado da Macro AdicionaReferenciaWord no evento Workbook_Open e a Macro RemoveReferenciaWord no Workbook_BeforeClose. O c�digo em Estapasta_de_trabalho fica assim: 

  Private Sub Workbook_BeforeClose(ByVal Cancel As Boolean)
    Call RemoveReferenciaWord()
  End Sub

  Private Sub Workbook_Open()
   
Call AdicionaReferenciaWord()
  End Sub

Agora, feche a planilha e salve no Excel 2003. Em seguida, abra no Excel 2000 ou XP (ativando as Macros) e sem mexer em nada, execute a Macro AbreWord. Veja que o Word � aberto corretamente n�o gerando mais o erro de versionamento. As Macros trataram de adicionar a refer�ncia para a vers�o correta do aplicativo sem interven��o do usu�rio. Fa�a isso v�rias vezes em diversas vers�es do aplicativo para testar sua efic�cia. 

Voc� pode tamb�m fazer implementa��es com o m�todo AddFromFile, embora em testes eu tenha conclu�do que o AddFromGUID � mais eficiente e menos sujeito e erros. 

As fun��es e recursos oferecidos pela biblioteca Microsoft Visual Basic for Applications Extensibility 5.3 permite ir mais al�m do que mostrei neste artigo. � poss�vel estender a funcionalidade a outras bibliotecas mais comuns como o ADO e o Microsoft Outlook. A partir da vers�o 97, o Office teve suas vers�es regularizadas para todos os aplicativos e isso nos auxilia a trabalhar com as op��es de vers�es como fizemos nos c�digos de exemplo. 

Conclus�o 

Procurei explanar de maneira enxuta um meio para resolver o problema de versionamento e aus�ncia de componentes que em muito nos auxiliam e azucrinam no desenvolvimento de nossas solu��es. 

Download da planilha com os c�digos de exemplo 

Refer�ncias 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/modcore/html/deconAutomatingVisualBasicEditor.asp 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbaac11/html/acprominor.asp 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbaac11/html/acproMajor.asp 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbext98/html/vamthaddfromguid.asp 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbext98/html/vamthaddfromguid.asp