Como criar um suplemento de com em Office usando o Visual Basic .NET

Microsoft Office 2000 e posterior oferece suporte a uma arquitetura de design de novo, uniforme para a criação de suplementos de aplicativo para aprimorar e para controlar aplicativos do Office. Esses suplementos são chamados de suplementos. Este artigo passo a passo sobre discute suplementos de COM do Office e descreve como criar um COM Office add-in usando o Microsoft Visual Basic. NET.

A interface IDTExensibility2

Um suplemento é um servidor COM em processo, ou biblioteca de vínculo dinâmico ActiveX (DLL), que implementa a interface IDTExensibility2 conforme descrito na biblioteca de tipos suplemento Microsoft Designer (Msaddndr.dll). Todos os suplementos herdam essa interface e devem implementar cada um dos seus cinco métodos.

OnConnection

O evento OnConnection é acionado sempre que o suplemento está conectado. O add-in o pode estar conectado na inicialização, pelo usuário final, ou através de automação. Se OnConnection retorna com êxito, o add-in é considerado ser carregado. Se uma mensagem de erro for retornada, o aplicativo host imediatamente libera sua referência para o suplemento e o objeto é destruído.

OnConnection usa os seguintes quatro parâmetros:

• aplicativo - uma referência a objeto do aplicativo host.
• ConnectMode - uma constante que especifica como o add-in está conectado. O add-in pode ser conectado das seguintes maneiras:
  • ext_cm_AfterStartup - O add-in é iniciado pelo usuário final na caixa de diálogo suplementos .
  • ext_cm_CommandLine - O add-in está conectado a partir da linha de comando. Observe que isso não se aplica à criação de suplementos de COM para aplicativos do Office.
  • ext_cm_External - O add-in está conectado por um aplicativo externo através da automação. Observe que isso não se aplica à criação de suplementos de COM para o Office aplicativos.
  • ext_cm_Startup - O add-in é iniciado por host na inicialização do aplicativo. Esse comportamento é controlado por uma configuração no registro.
• AddInInst - uma referência ao objeto COMAddIn que se refere a esse suplemento da coleção COMAddIns para o aplicativo host.
• personalizado - uma matriz de valores de tipo Variant que pode conter dados definidos pelo usuário.

OnDisconnection

O evento OnDisconnection é acionado quando o suplemento está desconectado e apenas antes que ele descarrega da memória. O add-in deve executar qualquer limpeza de recursos neste evento e restaure as alterações feitas ao aplicativo host.

OnDisconnection usa dois parâmetros a seguintes:

• RemoveMode - uma constante que especifica como o suplemento foi desconectado. O add-in possa ser desconectado das seguintes maneiras:
  • ext_dm_HostShutdown - O suplemento será desconectado quando o aplicativo host fechado.
  • ext_dm_UserClosed - O add - in é desconectada pelo usuário final ou uma automação controlador.
• personalizado - uma matriz de valores de tipo Variant que pode conter dados definidos pelo usuário.

OnAddInsUpdate

O evento OnAddInsUpdate é acionado quando o conjunto de registrados COM as alterações de add-ins. Em outras palavras, sempre que um suplemento está instalado ou removido o aplicativo host, este evento é acionado.

OnStartupComplete e OnBeginShutdown

Tanto OnStartupComplete e os métodos OnBeginShutdown são chamados quando o aplicativo de host tem à esquerda ou é inserir um estado no qual o usuário interação deve ser evitada porque o aplicativo está ocupado carregando ou descarregando próprio da memória. OnStartupComplete é chamado somente se o suplemento foi conectado durante a inicialização e OnBeginShutdown é chamado somente se o host desconecta o add-in durante o desligamento.

Como a interface do usuário para o aplicativo host é totalmente ativa quando esses eventos acionados, eles podem ser a única maneira executar determinadas ações caso contrário, seria não está disponíveis de OnConnection e OnDisconnection .

Suplemento do registro

Em além para registro COM normal, um suplemento precisa se registrar com cada aplicativo do Office no qual ele é executado. Para se registrar com um determinado aplicativo, o suplemento deve criar uma subchave, usando o ProgID como o nome para a chave, no seguinte local: O add-in pode fornecer valores neste local chave para um nome para exibição amigável e uma descrição completa. Além disso, o suplemento deve especificar seu comportamento de carga desejada usando um valor DWORD chamado . Esse valor determina como o suplemento é carregado pelo aplicativo host e é composto de uma combinação dos seguintes valores:

• 0 = Desconectar - Não É carregado.
• 1 = Conectado - É carregado.
• 2 = Bootload - carregar na inicialização do aplicativo.
• 8 = DemandLoad - carga somente quando solicitado pelo usuário.
• 16 = ConnectFirstTime - carregar apenas uma vez (na próxima inicialização).

O valor típico especificado é 0 x 03 (conectado | Bootload).

Suplementos que implementam IDTExtensibility2 também devem especificar um valor DWORD chamado para indicar se os suplementos são seguros para operações que não oferecem suporte a uma interface de usuário. Um valor de 0 x 00 indica False e um valor de 0 x 01 indica True.

Como criar um suplemento de COM usando o Visual Basic .NET

Como mencionado anteriormente, um suplemento COM do Office é um processo in COM servidor é ativado por um aplicativo do Office por meio da camada de tempo de execução COM. Portanto, desenvolver um suplemento COM no Visual Basic .NET requer que o componente add-in ser implementado em .NET e, em seguida, exposto a clientes COM (ou seja, os aplicativos do Office) por meio de camada de interoperabilidade COM.

Para criar um suplemento de COM no Visual Basic. NET, execute essas etapas:

1. No Visual Basic. NET, crie uma biblioteca de classes projeto.
2. Adicione uma referência à biblioteca de tipos que implementa IDTExtensibility2 . O assembly de interoperabilidade primária para isso já está disponível sob o nome extensibilidade .
3. Adicione uma referência à biblioteca de objeto do Microsoft Office. O assembly de interoperabilidade primária para isso já está disponível sob o nome do Office .
4. Crie uma classe pública na biblioteca de classe que implementa IDTExtensibility2 .
5. Após a classe de biblioteca é criada, registrar a biblioteca for COM interop. Para fazer isso, gerar um forte chamado assembly para esta biblioteca de classes e registrá-lo com a interoperabilidade COM. Você pode usar regasm.exe para registrar um componente .NET para COM interop.
6. Crie entradas do Registro para que aplicativos do Office podem reconhecer e carregar o add-in.

Você pode optar por concluir todas essas etapas, ou você pode criar um projeto .NET do tipo Shared Addin . Isso inicia o Assistente extensibilidade, que ajuda a criar um suplemento no. NET.

O Assistente de extensibilidade cria um projeto de biblioteca de classe Visual Basic.NET along with uma classe de conectar-se que implementa a interface IDTExtensibility2 . O código estrutural que implementa os membros vazios do IDTExtensibility também é gerado. Este projeto possui referências a assemblies de extensibilidade e Office. As configurações de compilação do projeto tem Register for COM Interop selecionado. O arquivo de chave (.snk) do assembly é gerado e referenciado no atributo AssemblyKeyfile em Assemblyinfo.vb.

Along with projeto de biblioteca de classe, o assistente gera um projeto de instalação que você pode usar para implantar o add-in COM em outros computadores. Você pode remover esse projeto se desejado.

Exemplo passo a passo

1. No menu arquivo no Microsoft Visual Studio. NET, clique em novo e, em seguida, clique em Project .
2. Na caixa de diálogo New Project , expanda Outros projetos em Project Types , selecione Projetos de extensibilidade e, em seguida, selecione o modelo Shared Add-in .
3. Digite MyCOMAddin como o nome do suplemento e, em seguida, clique em OK .
4. Quando o Assistente de extensibilidade for exibida, siga estas etapas:
   1. Na página 1, selecione Create an Add-in usando o Visual Basic e, em seguida, clique em Avançar .
   2. Na página 2, selecione os seguintes aplicativos host e, em seguida, clique em Avançar :
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
   3. Na página 3, forneça um nome e descrição para o suplemento e, em seguida, clique em Avançar .
      
      Observação O nome e descrição do add-in são exibidos na caixa de diálogo suplemento de com no aplicativo do Office.
      
      
   4. Na página 4, selecione todas as opções disponíveis e, em seguida, clique em Avançar .
   5. Clique em Concluir .
5. Adicionar o membro seguir à classe Connect :

   Dim WithEvents MyButton As CommandBarButton 

6. Implementar o código para todos os membros do IDTExtensibility2 na classe conectar , da seguinte maneira:

       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 fazer isso, execute as seguintes etapas:
   1. No menu Build , clique em Criar MyCOMAddin . Observe que criar o suplemento registra a classe do .NET com a interoperabilidade COM.
   2. Inicie um dos aplicativos do Office que você selecionou como aplicativos de host para seu suplemento (por exemplo, Microsoft Word ou Microsoft Excel).
   3. Após ter iniciado o add-in, o evento OnConnection é acionado, e você recebe uma caixa de mensagem. Quando você descartar a caixa de mensagem, o evento OnStartupComplete é acionado, e você recebe uma segunda caixa de mensagem. Descartar a caixa de mensagem.
   4. Observação que o suplemento adicionado um novo botão personalizado com a legenda "Meu botão personalizado" barra de ferramentas padrão.
   5. Clique em Meu botão personalizado . O evento Click do botão é tratado pelo add-in e você recebe uma caixa de mensagem. Descartar a caixa de mensagem.
   6. Feche o aplicativo do Office.
   7. Quando você sai do aplicativo, OnBeginShutDown evento é acionado e receber uma caixa de mensagem. Fechar a caixa de mensagem para finalizar a demonstração.

Para obter informações adicionais sobre como escrever suplementos de COM, clique no número abaixo para ler 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 sites:(c) Microsoft Corporation 2001, todos os direitos reservados. Contribuições de Ranjit r. Sawant, Microsoft Corporation.