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

Traduções de Artigos Traduções de Artigos
Artigo: 302901 - Ver produtos para os quais este artigo se aplica.
Expandir tudo | Reduzir tudo

Nesta página

Sumário

Microsoft Office XP, Microsoft Office 2003 e Microsoft Office 2007 suportam uma arquitectura de apresentação uniforme para criar a aplicação de suplementos para melhorar e para controlar as aplicações do Office. Estes suplementos são designados por COM (Component Object Model) da Microsoft add-ins. Este artigo passo a passo aborda os suplementos COM do Office e descreve como criar um suplemento COM do Office utilizando o Microsoft Visual C# .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 o evento 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.

O evento 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á ligado 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.
  • personalizado : 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 efectuar qualquer limpeza de recursos neste caso e restaurar todas as alterações efectuadas a aplicação inicial.

O evento 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 fecha a aplicação inicial.
    • ext_dm_UserClosed : O suplemento é desligado pelo utilizador final ou por uma automatização controlador.
  • personalizado : 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

O método OnStartupComplete e o método 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. O método OnStartupComplete é chamado apenas se o suplemento estava ligado durante o arranque e o método OnBeginShutdown é 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 disponíveis a partir do evento OnConnection e o evento 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:
HKEY_CURRENT_USER\Software\Microsoft\Office\<OfficeApp>\Addins\<ProgID>
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 LoadBehavior. 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
CommandLineSafe
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 utilizando o Visual C# .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 .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 C#. NET, siga estes passos:
  1. No Visual C#. 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 Visual C# .NET classe biblioteca projecto 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 clique em OK .
  4. Quando aparecer o Assistente de extensibilidade, siga estes passos:
    1. Na página 1, seleccione criar um suplemento utilizando Visual C# 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 a descrição do add-in aparecem na caixa de diálogo suplemento COM 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. No menu projecto , clique em Add Reference . Clique em System.Windows.Forms.DLL na lista de componentes, clique em Seleccionar e, em seguida, clique em OK .
  6. Adicione o seguinte na lista de espaços de nomes da classe de ligar :
    using System.Reflection;
  7. Adicionar o membro seguinte para a classe ligar :
    private CommandBarButton MyButton; 
  8. Implementar o código para os membros do IDTExtensibility2 da classe de ligar , 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 suplemento. Para o fazer, siga estes passos:
    1. No menu criar , clique em Criar soluções . 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 ter sido iniciado, OnStartupComplete evento do add-in for accionado e receberá uma mensagem. Fechar a caixa de mensagem. 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.
    4. 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.
    5. Sair da aplicação Office.
    6. Quando sair da aplicação, OnBeginShutDown evento é desencadeado e receber uma mensagem. Fechar a caixa de mensagem para terminar a demonstração.

Referências

Para obter informações adicionais sobre como escrever suplementos, clique no número de artigo que se segue para visualizar o artigo na Microsoft Knowledge Base:
190253INFO: VB6 designers não funcionam em VB5

Propriedades

Artigo: 302901 - Última revisão: 11 de maio de 2007 - Revisão: 10.2
A informação contida neste artigo aplica-se a:
  • Microsoft Visual C# .NET 2003 Standard Edition
  • Microsoft Visual C# .NET 2002 Standard Edition
  • Microsoft Office Excel 2007
  • Microsoft Office Excel 2003
  • Microsoft Excel 2002 Standard Edition
  • Microsoft Office Outlook 2007
  • Microsoft Office Outlook 2003
  • Microsoft Outlook 2002 Standard Edition
  • Microsoft Office PowerPoint 2007
  • Microsoft Office PowerPoint 2003
  • Microsoft PowerPoint 2002 Standard Edition
  • Microsoft Office Word 2007
  • Microsoft Office Word 2003
  • Microsoft Word 2002 Standard Edition
Palavras-chave: 
kbmt kbautomation kbhowtomaster KB302901 KbMtpt
Tradução automática
IMPORTANTE: Este artigo foi traduzido por um sistema de tradução automática (também designado por Machine translation ou MT), não tendo sido portanto revisto ou traduzido por humanos. A Microsoft tem artigos traduzidos por aplicações (MT) e artigos traduzidos por tradutores profissionais. O objectivo é simples: oferecer em Português a totalidade dos artigos existentes na base de dados do suporte. Sabemos no entanto que a tradução automática não é sempre perfeita. Esta pode conter erros de vocabulário, sintaxe ou gramática? erros semelhantes aos que um estrangeiro realiza ao falar em Português. A Microsoft não é responsável por incoerências, erros ou estragos realizados na sequência da utilização dos artigos MT por parte dos nossos clientes. A Microsoft realiza actualizações frequentes ao software de tradução automática (MT). Obrigado.
Clique aqui para ver a versão em Inglês deste artigo: 302901

Submeter comentários

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com