Como criar um adicionar o Office COM através do Visual C# .NET

  • Artigo
  • Aplica-se a:
    Microsoft Office XP, Microsoft Office 2003, Microsoft Office 2007

Resumo

O Microsoft Office XP, o Microsoft Office 2003 e o Microsoft Office 2007 suportam uma arquitetura de estrutura uniforme para a criação de adicionar aplicações para melhorar e controlar as aplicações do Office. Estes add-ins são denominados microsoft Component Object Model (COM). Este artigo passo a passo aborda os adicionar ao Office COM e descreve como criar um adicionar o Office COM através do Microsoft Visual C# .NET.

A interface IDTExensibility2

Um add-in COM é um servidor COM no processo, ou uma biblioteca de ligação dinâmica ActiveX (DLL), que implementa a interface IDTExensibility2, conforme descrito na biblioteca de tipos de Tipo de Add-in Designer da Microsoft (Msaddndr.dll). Todos os add-ins COM herdam desta interface e têm de implementar cada um dos cinco métodos.

OnConnection

O evento AoLigar é ateado sempre que o add-in COM está ligado. O add-in pode estar ligado durante o arranque, pelo utilizador final ou através de Automatização. Se o evento AoLigar for devolvê-lo com êxito, afirma-se que o mesmo será carregado. Se for devolvida uma mensagem de erro, a aplicação anfitrião solta imediatamente a sua referência ao add-in e o objeto é arrasado.

O evento AoLigar requer os seguintes quatro parâmetros:

  • Aplicação: uma referência ao objeto de aplicação anfitrião.

  • ConnectMode: uma constante que especifica como o mesmo está ligado. O add-in pode ser ligado das seguintes formas:

    • ext_cm_AfterStartup: O add-in é iniciado pelo utilizador final a partir da caixa de diálogo Adicionar Com.
    • ext_cm_CommandLine: o add-in está ligado a partir da linha de comandos. Tenha em atenção que isto não se aplica à composição de add-ins COM para aplicações do Office.
    • ext_cm_External: o add-in está ligado por uma aplicação externa através da Automatização. Tenha em atenção que isto não se aplica à composição de add-ins COM para aplicações do Office.
    • ext_cm_Startup: o add-in é iniciado pelo anfitrião no arranque da aplicação. Este comportamento é controlado por uma definição no registo.

  • AddInInst: uma referência ao objeto COMAddIn que se refere a este add-in na coleção COMAddIns da aplicação anfitriã.

  • Personalizado: uma matriz de valores do tipo Variante que pode conter dados definidos pelo utilizador.

OnDisconnection

O evento OnDisconnection é ativado quando o add-in COM está desligado e mesmo antes de ser descarregado da memória. O adicionar deve efetuar qualquer limpeza de recursos neste evento e restaurar as alterações feitas à aplicação anfitriã.

O evento OnDisconnection requer os seguintes dois parâmetros:

  • RemoveMode: uma constante que especifica como o mesmo foi desligado. O add-in pode ser desligado das seguintes formas:

    • ext_dm_HostShutdown: o add-in é desligado quando a aplicação anfitrião fecha.
    • ext_dm_UserClosed: o add-in é desligado pelo utilizador final ou por um controlador de automatização.

  • Personalizado: uma matriz de valores do tipo Variante que pode conter dados definidos pelo utilizador.

OnAddInsUpdate

O evento OnAddInsUpdate é ateado quando o conjunto de add-ins COM registados é alterado. Por outras palavras, sempre que um adicionar COM for instalado ou removido da aplicação anfitrião, este evento é ateado.

OnStartupComplete e OnBeginShutdown

Tanto o método AoInstartupComplete como o método OnBeginShutdown são chamados quando a aplicação anfitrião saiu ou está a introduzir um estado no qual a interação do utilizador deve ser evitada porque a aplicação está a carregar ou a carregar-se a si própria da memória. O método OnStartupComplete é denominado apenas se o add-in tiver sido ligado durante o arranque e o método AoBeginShutdown é denominado apenas se o anfitrião desligar o add-in durante o encerramento.

Uma vez que a interface de utilizador da aplicação anfitrião está totalmente ativa quando estes eventos são ativados, podem ser a única forma de executar determinadas ações que, de outra forma, estariam indisponíveis a partir do evento AoLigação e do evento AoAdisconnection.

Registo do add-in COM

Para além do registo COM normal, um adicionar COM tem de se registar em cada aplicação do Office em que é executado. Para se registar numa determinada aplicação, o adicionar deverá criar uma subchava, utilizando o respas ProgID como nome para a chave, na seguinte localização:

HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeApp\Addins\ProgID

O adicionar pode fornecer valores nesta localização chave, tanto para um nome a apresentar amigável como para uma descrição completa. Além disso, o adicionar deve especificar o comportamento de carregamento pretendido ao utilizar um valor DWORD com o nome LoadBehavior. Este valor determina a forma como o add-in é carregado pela aplicação anfitrião e é formado por uma combinação dos seguintes valores:

  • 0 = Desligar - Não é carregado.
  • 1 = Ligado - É carregado.
  • 2 = Arranque - Carregar no arranque da aplicação.
  • 8 = DemandLoad - Carregar apenas quando solicitado pelo utilizador.
  • 16 = ConnectFirstTime - Carregar apenas uma vez (no arranque seguinte).

O valor típico especificado é 0x03 (Ligação | Bootload).

Os add-ins que implementem o IDTExtensibility2 também devem especificar um valor DWORD denominado CommandLineSafe para indicar se os add-ins são seguros para operações que não suportam uma interface de utilizador. Um valor de 0x00 indica Falso e um valor de 0x01 indica Verdadeiro.

Como criar um add-in COM através do Visual C# .NET

Conforme mencionado anteriormente, um add-in COM do Office é um servidor COM no processo que é ativado por uma aplicação do Office através da camada de tempo de resposta COM. Portanto, o desenvolvimento de um adicionar COM no .NET requer que o componente de add-in seja implementado no .NET e, em seguida, exposto aos clientes COM (ou seja, as aplicações do Office) através da camada interopção COM.

Para criar um adicionar COM no Visual C# .NET, siga estes passos:

  1. No Visual C# .NET, crie um projeto de Biblioteca de Turmas.
  2. Adicione uma referência à biblioteca de tipos que implementa o IDTExtensibility2. A assemblagem interopção principal para este problema já está disponível com o nome Extensibilidade.
  3. Adicione uma referência à biblioteca de objetos do Microsoft Office. A assemblagem interopriana principal para este problema já está disponível com o nome Office.
  4. Crie uma turma pública na biblioteca de aula que implemente o IDTExtensibility2.
  5. Após a construção da biblioteca de turmas, registe a biblioteca no intervalo COM. Para tal, gere uma assemblagem com nome forte para esta biblioteca de aula e, em seguida, registe-a com a interopção COM. Pode utilizar o Regasm.exe para registar um componente .NET para o intervalo COM.
  6. Crie entradas de registo para que as aplicações do Office possam reconhecer e carregar o mesmo.

Pode optar por concluir todos estes passos ou pode criar um projeto .NET do tipo Addin Partilhado. Esta ação inicia o Assistente de Extensibilidade, que o ajuda a criar um add-in COM em .NET.

O Assistente de Extensibilidade cria um projeto de biblioteca de aula do Visual C# .NET juntamente com uma turma de Ligação que implementa a interface IDTExtensibility2. Também é gerado o código de esqueleto que implementa os membros vazios do IDTExtensibility. Este projeto tem referências a Extensibilidade e a assemblagens do Office. As definições de composição do projeto têm a opção Register for COM Interop selecionada. O ficheiro da tecla de assemblagem (.snk) é gerado e é referenciado no atributo AssemblyKeyfile em Assemblyinfo.vb.

Juntamente com o projeto da biblioteca de turma, o assistente gera um projeto de configuração que pode utilizar para implementar o add-in COM noutros computadores. Se quiser, pode remover este projeto.

Exemplo passo a passo

  1. No menu Ficheiro no Microsoft Visual Studio .NET, clique em Novo e, em seguida, clique em Projeto.

  2. Na caixa de diálogo Novo Projeto, expanda Outros Projetos em Tipos de Projeto, selecione Projetos de Extensibilidade e, em seguida, selecione o modelo Adicionar Partilhado.

  3. Escreva MyCOMAddin como o nome do mesmo e, em seguida, clique em OK.

  4. Quando o Assistente de Extensibilidade aparecer, siga estes passos:

    1. Na página 1, selecione Criar um Adicionar utilizando o Visual C# e, em seguida, clique em Seguinte.

    2. Na página 2, selecione as seguintes aplicações anfitriãs e, em seguida, clique em Seguinte:

      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access

    3. Na página 3, forneça um nome e uma descrição para o add-in e, em seguida, clique em Seguinte.

      Nota O nome e a descrição do mesmo são apresentados na caixa de diálogo Adicionar COM na aplicação do Office.

    4. Na página 4, selecione todas as opções disponíveis e, em seguida, clique em Seguinte.

    5. Clique em Concluir.

  5. No menu Projeto, clique em Adicionar Referência. Clique System.Windows.Forms.DLL na lista de componentes, clique em Selecionar e, em seguida, clique em OK.

  6. Adicione o seguinte à lista de espaços de nomes na classe Ligar:

    using System.Reflection;

  7. Adicione o membro seguinte à turma Ligar:

    private CommandBarButton MyButton;

  8. Implementar o código para os membros do IDTExtensibility2 na classe Connect, da seguinte forma:

    public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) {
   applicationObject = application;
   addInInstance = addInInst;

if(connectMode != Extensibility.ext_ConnectMode.ext_cm_Startup)
   {
      OnStartupComplete(ref custom);
   }

}

public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom) {
   if(disconnectMode != Extensibility.ext_DisconnectMode.ext_dm_HostShutdown)
   {
      OnBeginShutdown(ref custom);
   }
   applicationObject = null;
}

public void OnAddInsUpdate(ref System.Array custom)
{
}

public void OnStartupComplete(ref System.Array custom)
{
   CommandBars oCommandBars;
   CommandBar oStandardBar;

try
   {
   oCommandBars = (CommandBars)applicationObject.GetType().InvokeMember("CommandBars", BindingFlags.GetProperty , null, applicationObject ,null);
   }
   catch(Exception)
   {
   // Outlook has the CommandBars collection on the Explorer object.
   object oActiveExplorer;
   oActiveExplorer= applicationObject.GetType().InvokeMember("ActiveExplorer",BindingFlags.GetProperty,null,applicationObject,null);
   oCommandBars= (CommandBars)oActiveExplorer.GetType().InvokeMember("CommandBars",BindingFlags.GetProperty,null,oActiveExplorer,null);
   }

// Set up a custom button on the "Standard" commandbar.
   try
   {
   oStandardBar = oCommandBars["Standard"];        
   }
   catch(Exception)
   {
   // Access names its main toolbar Database.
   oStandardBar = oCommandBars["Database"];      
   }

// In case the button was not deleted, use the exiting one.
   try
   {
   MyButton = (CommandBarButton)oStandardBar.Controls["My Custom Button"];
   }
   catch(Exception)
   {
      object omissing = System.Reflection.Missing.Value ;
      MyButton = (CommandBarButton) oStandardBar.Controls.Add(1, omissing , omissing , omissing , omissing);
      MyButton.Caption = "My Custom Button";
      MyButton.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.
   MyButton.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 presses the button,
   //MSO loads the add-in automatically and then raises
   //the Click event for the add-in to handle. 
   MyButton.OnAction = "!<MyCOMAddin.Connect>";

MyButton.Visible = true;
   MyButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.MyButton_Click);

object oName = applicationObject.GetType().InvokeMember("Name",BindingFlags.GetProperty,null,applicationObject,null);

// Display a simple message to show which application you started in.
   System.Windows.Forms.MessageBox.Show("This Addin is loaded by " + oName.ToString()   , "MyCOMAddin");
   oStandardBar = null;
   oCommandBars = null;
}

public void OnBeginShutdown(ref System.Array custom)
{
   object omissing = System.Reflection.Missing.Value ;
   System.Windows.Forms.MessageBox.Show("MyCOMAddin Add-in is unloading.");
   MyButton.Delete(omissing);
   MyButton = null;
}

private void MyButton_Click(CommandBarButton cmdBarbutton,ref bool cancel) {
   System.Windows.Forms.MessageBox.Show("MyButton was Clicked","MyCOMAddin"); }

  9. Criar e testar o add-in COM. Para tal, siga estes passos:

    1. No menu Criar, clique em Construir Solução. Tenha em atenção que criar o adicionar COM regista a turma .NET com o intervalo COM.
    2. Inicia uma das aplicações do Office que selecionou como aplicações de anfitrião para o seu add-in (por exemplo, o Microsoft Word ou o Microsoft Excel).
    3. Depois de o add-in começar, o evento OnStartupComplete do mesmo é incompleto e recebe uma mensagem. Dispensar a caixa de mensagem. Tenha em atenção que o add-in adicionou um novo botão personalizado com a legenda "O Meu Botão Personalizado" à barra de ferramentas padrão.
    4. Clique no botão A Minha Personalização. O evento Click do botão é tratado pelo mesmo e recebe uma caixa de mensagem. Dispensar a caixa de mensagem.
    5. Saia da aplicação do Office.
    6. Quando sair da aplicação, o evento OnBeginShutDown é ativo e recebe uma mensagem. Dispense a caixa de mensagem para terminar a demonstração.