Como criar um COM suplemento do Office utilizando o Visual Basic .NET

Microsoft Office 2000 e posterior suporta uma arquitectura de novo design uniforme para construir aplicações suplementos para melhorar e para controlar as aplicações do Office. Estes suplementos são denominados suplementos. Este artigo passo a passo aborda os suplementos COM do Office e descreve como criar um COM Office add-in utilizando o Microsoft Visual Basic. NET.

A interface IDTExensibility2

Um suplemento é um servidor do COM em processo ou ActiveX biblioteca de ligação dinâmica (DLL), que implementa a interface IDTExensibility2 conforme descrito na biblioteca de tipos suplemento Microsoft Designer (Msaddndr.dll). Todos os suplementos COM herdam desta interface e tem de implementar cada uma das respectivos cinco métodos.

OnConnection

O evento OnConnection é accionado sempre que o suplemento está ligado. O suplemento a pode ser ligado no arranque, pelo utilizador final, ou através de automatização. Se OnConnection devolve com êxito, diz-se o suplemento que está a carregar. Se uma mensagem de erro é devolvida, a aplicação inicial imediatamente liberta a referência do suplemento e, o objecto é destruído.

OnConnection assume os quatro parâmetros seguintes:

• aplicação - referência a objecto de aplicação anfitrião.
• ConnectMode - constante que especifica como o suplemento está ligado. O suplemento pode ser ligado das seguintes formas:
  • ext_cm_AfterStartup - O suplemento é iniciado pelo utilizador final da caixa de diálogo suplementos COM .
  • ext_cm_CommandLine - O suplemento está ligado a partir da linha de comandos. Nota Se isto não se aplica à criação de suplementos para aplicações do Office.
  • ext_cm_External - O suplemento está ligada por uma aplicação externa através de automatização. Nota Se isto não se aplica à criação de suplementos para o Office aplicações.
  • ext_cm_Startup - O suplemento é iniciado pelo anfitrião no arranque da aplicação. Este comportamento é controlado por uma definição no registo.
• AddInInst - uma referência ao objecto COMAddIn que se refere este suplemento na colecção COMAddIns para a aplicação inicial.
• personalizada - uma matriz de valores de tipo de variante que pode conter dados definidos pelo utilizador.

OnDisconnection

O evento OnDisconnection é accionado quando o suplemento está desligado e antes de descarrega da memória. O suplemento deve ser efectuada qualquer limpeza de recursos neste caso e deve restaurar todas as alterações efectuadas a aplicação inicial.

OnDisconnection assume os dois parâmetros seguintes:

• RemoveMode - constante que especifica como o suplemento foi desligado. O suplemento pode ser desligado da seguinte forma:
  • ext_dm_HostShutdown - O suplemento é desligado quando fechar a aplicação inicial.
  • ext_dm_UserClosed - O add - in é desligada pelo utilizador final ou por uma automatização controlador.
• personalizada - uma matriz de valores de tipo de variante que pode conter dados definidos pelo utilizador.

OnAddInsUpdate

O evento OnAddInsUpdate é accionado quando o conjunto de registado COM alterações de suplementos. Por outras palavras, sempre que um suplemento for instalado ou removido a aplicação inicial, este evento é accionado.

OnStartupComplete e OnBeginShutdown

Ambos os OnStartupComplete e os métodos OnBeginShutdown são chamados quando a aplicação inicial saiu ou está a entrar num estado no qual o utilizador interacção deve ser evitada porque a aplicação está ocupada a carregar ou descarregar próprio da memória. OnStartupComplete apenas é chamado se o suplemento estava ligado durante o arranque e OnBeginShutdown só é chamado se o anfitrião desliga o suplemento durante o encerramento.

Uma vez que a interface de utilizador para a aplicação inicial é totalmente activa quando estes eventos accionados, podem ser a única forma de efectuar determinadas acções que caso contrário, seriam indisponíveis OnConnection e OnDisconnection .

Registo do suplemento COM

Em juntamente para registo COM normal, um suplemento tem registar-se com cada aplicação do Office em que é executado. Registar-se com uma determinada aplicação, o suplemento deve criar uma subchave, utilizar o ID de programa como o nome para a chave, na seguinte localização: O suplemento pode fornecer valores nesta localização chave para um nome amigável e uma descrição completa. Além disso, o suplemento deve especificar o comportamento de carregamento pretendida utilizando um valor DWORD denominado . Este valor determina como o suplemento é carregado por aplicação anfitriã e é constituído por uma combinação dos seguintes valores:

• 0 = Desligar - não é carregado.
• 1 = Ligado - É carregado.
• 2 = Bootload - carregar no arranque da aplicação.
• 8 = DemandLoad - carregar apenas quando solicitado pelo utilizador.
• 16 = ConnectFirstTime - carregar apenas uma vez (no próximo arranque).

O valor típico especificado é 0x03 (ligado | Bootload).

Suplementos que implementam IDTExtensibility2 também devem especificar um valor DWORD denominado para indicar se os suplementos são seguros para operações que não suportam uma interface de utilizador. Um valor de 0 x 00 indica FALSO e um valor de 0 x 01 indica VERDADEIRO.

Como criar um suplemento COM o Visual Basic .NET

Tal como mencionado anteriormente, um suplemento COM do Office é um processo COM o servidor que esteja activado por uma aplicação do Office através da camada de tempo de execução COM. Por este motivo, desenvolver um suplemento COM no Visual Basic .NET requer que o componente suplementar ser implementado no .NET e, em seguida, exposto a clientes COM (ou seja, as aplicações do Office) através da camada de interoperabilidade COM.

Para criar um suplemento COM no Visual Basic. NET, siga estes passos:

1. No Visual Basic. NET, crie uma biblioteca de classes projecto.
2. Adicione uma referência à biblioteca de tipos que implementa IDTExtensibility2 . A assemblagem de interoperabilidade primária para este já está disponível com o nome de extensibilidade .
3. Adicione uma referência à biblioteca de objectos do Microsoft Office. A assemblagem de interoperabilidade primária para este já está disponível sob o nome do Office .
4. Crie uma classe pública na biblioteca de classe que implementa IDTExtensibility2 .
5. Depois da classe biblioteca é criada, registar a biblioteca de interoperabilidade COM. Para efectuar este procedimento, gerar uma forte denominado assemblagem para esta biblioteca de classes e registe-lo com a interoperabilidade COM. Pode utilizar regasm.exe para registar um componente .NET para interoperabilidade COM.
6. Crie entradas de registo para que aplicações do Office podem reconhecer e carregar o suplemento.

Pode optar por concluir todos estes passos, ou pode criar um projecto .NET do tipo Suplemento partilhados do . Este procedimento inicia o Assistente de extensibilidade que ajuda a criar um suplemento COM no .NET.

O Assistente de extensibilidade cria um projecto de biblioteca do Visual Basic .NET classe juntamente com uma classe de ligar que implementa a interface IDTExtensibility2 . O código skeleton que implementa os membros vazios IDTExtensibility também é gerado. Este projecto tem referências a assemblagens de extensibilidade e Office. As definições de compilação do projecto têm Registar para interoperabilidade seleccionado. O ficheiro de chave (.snk) assemblagem é gerado e é referenciado no atributo AssemblyKeyfile em Assemblyinfo.vb.

Juntamente com o projecto de biblioteca de classe, o assistente gera um projecto de configuração que pode utilizar para implementar o suplemento noutros computadores. Pode remover este projecto se assim o desejar.

Exemplo passo a passo

1. No menu ficheiro do Microsoft Visual Studio. NET, clique em Novo e, em seguida, clique em projecto .
2. Na caixa de diálogo Novo projecto , expanda Outros projectos em Project Types , seleccione Projectos de extensibilidade e, em seguida, seleccione o modelo partilhado Add-in .
3. Escreva MyCOMAddin como o nome do suplemento e, em seguida, clique em OK .
4. Quando aparecer o Assistente de extensibilidade, siga estes passos:
   1. Na página 1, seleccione criar um suplemento utilizando o Visual Basic e, em seguida, clique em seguinte .
   2. Na página 2, seleccione as seguintes aplicações de anfitrião e, em seguida, clique em seguinte :
      • O Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • O Microsoft Excel
      • O Microsoft Access
   3. Na página 3, forneça um nome e descrição para o suplemento e, em seguida, clique em seguinte .
      
      Nota O nome e descrição do suplemento aparecem na caixa de diálogo suplemento na aplicação do Office.
      
      
   4. Na página 4, seleccione todas as opções disponíveis e, em seguida, clique em seguinte .
   5. Clique em Concluir .
5. Adicionar o membro seguinte para a classe ligar :

   Dim WithEvents MyButton As CommandBarButton 

6. Implementar o código para todos os membros de IDTExtensibility2 da classe de ligar , da seguinte forma:

       Public Sub OnBeginShutdown(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnBeginShutdown
           On Error Resume Next
           ' Notify the user you are shutting down, and delete the button.
           MsgBox("Our custom Add-in is unloading.")
           MyButton.Delete()
           MyButton = Nothing
   
       End Sub
   
       Public Sub OnAddInsUpdate(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnAddInsUpdate
           '
       End Sub
   
       Public Sub OnStartupComplete(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnStartupComplete
   
           Dim oCommandBars As CommandBars
           Dim oStandardBar As CommandBar
   
           On Error Resume Next
           ' Set up a custom button on the "Standard" command bar.
           oCommandBars = applicationObject.CommandBars
           If oCommandBars Is Nothing Then
               ' Outlook has the CommandBars collection on the Explorer object.
               oCommandBars = applicationObject.ActiveExplorer.CommandBars
           End If
   
           oStandardBar = oCommandBars.Item("Standard")
           If oStandardBar Is Nothing Then
               ' Access names its main toolbar Database.
   
               oStandardBar = oCommandBars.Item("Database")
   
           End If
   
           ' In case the button was not deleted, use the exiting one.
           MyButton = oStandardBar.Controls.Item("My Custom Button")
           If MyButton Is Nothing Then
   
               MyButton = oStandardBar.Controls.Add(1)
               With MyButton
                   .Caption = "My Custom Button"
                   .Style = MsoButtonStyle.msoButtonCaption
   
                   ' The following items are optional, but recommended. 
                   ' The Tag property lets you quickly find the control 
                   ' and helps MSO keep track of it when more than
                   ' one application window is visible. The property is required
                   ' by some Office applications and should be provided.
   
                   .Tag = "My Custom Button"
   
                   ' The OnAction property is optional but recommended. 
                   ' It should be set to the ProgID of the add-in, so that if
                   ' the add-in is not loaded when a user clicks the button,
                   ' MSO loads the add-in automatically and then raises
                   ' the Click event for the add-in to handle. 
   
                   .OnAction = "!<MyCOMAddin.Connect>"
   
                   .Visible = True
               End With
           End If
   
           ' Display a simple message to show which application you started in.
           MsgBox("Started in " & applicationObject.Name & ".")
   
   
           oStandardBar = Nothing
           oCommandBars = Nothing
   
   
       End Sub
   
       Public Sub OnDisconnection(ByVal RemoveMode As Extensibility.ext_DisconnectMode, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnDisconnection
   
           On Error Resume Next
           If RemoveMode <> Extensibility.ext_DisconnectMode.ext_dm_HostShutdown Then _
              Call OnBeginShutdown(custom)
   
           applicationObject = Nothing
   
   
       End Sub
   
       Public Sub OnConnection(ByVal application As Object, ByVal connectMode As Extensibility.ext_ConnectMode, ByVal addInInst As Object, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnConnection
   
   
           MsgBox("On Connection In MyAddin")
           applicationObject = application
           addInInstance = addInInst
   
   
           ' If you aren't in startup, manually call OnStartupComplete.
           If (connectMode <> Extensibility.ext_ConnectMode.ext_cm_Startup) Then _
              Call OnStartupComplete(custom)
   
       End Sub
   
   
       Private Sub MyButton_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton, ByRef CancelDefault As Boolean) Handles MyButton.Click
           MsgBox("Our CommandBar button was pressed!")
       End Sub
   					

7. Criar e testar o suplemento. Para o fazer, siga estes passos:
   1. No menu criar , clique em Criar MyCOMAddin . Tenha em atenção que criar o suplemento regista da classe .NET com a interoperabilidade COM.
   2. Inicie uma das aplicações do Office que seleccionou como aplicações de anfitrião para o suplemento (por exemplo, o Microsoft Word ou Microsoft Excel).
   3. Depois do suplemento tiver sido iniciado, o evento OnConnection é desencadeado e recebe uma caixa de mensagem. Quando fechar a caixa de mensagem, o OnStartupComplete evento é despoletado, e receberá uma segunda caixa de mensagem. Fechar a caixa de mensagem.
   4. Note que o suplemento adicionado um novo botão personalizado com o título "Meu botão personalizado" para a barra de ferramentas padrão.
   5. Clique no botão os meus personalizada . O evento Click do botão é tratado pelo suplemento e é apresentada uma caixa de mensagem. Fechar a caixa de mensagem.
   6. Sair da aplicação Office.
   7. Quando sair da aplicação, OnBeginShutDown evento é desencadeado e receber uma caixa de mensagem. Fechar a caixa de mensagem para terminar a demonstração.

Para obter informações adicionais sobre como escrever suplementos, clique no número de artigo existente abaixo para visualizar o artigo na base de dados de conhecimento da Microsoft: Para obter mais informações sobre como desenvolver soluções baseadas na Web para o Microsoft Internet Explorer, visite os seguintes Web sites da Microsoft:(c) Microsoft Corporation 2001, todos os direitos reservados. Contribuições de Ranjit r. Sawant, Microsoft Corporation.