Cómo crear un complemento COM de Office mediante Visual C# .NET

Seleccione idioma Seleccione idioma
Id. de artículo: 302901 - Ver los productos a los que se aplica este artículo
Expandir todo | Contraer todo

En esta página

Resumen

Microsoft Office XP, Microsoft Office 2003 y Microsoft Office 2007 admiten una arquitectura de diseño uniforme para crear complementos de aplicación para mejorar y controlar las aplicaciones de Office. Estos complementos se denominan modelo de objetos componentes (COM) de Microsoft de complementos. En este artículo paso a paso se explica los complementos COM de Office y se describe cómo crear un complemento COM de Office mediante Microsoft Visual C#. NET.

La interfaz IDTExensibility2

Un complemento es un servidor COM en proceso o biblioteca de vínculos dinámicos (DLL) de ActiveX que implementa la interfaz IDTExensibility2 como se describe en la biblioteca de tipo de diseñador Microsoft Add-in (Msaddndr.dll). Todos los complementos COM heredan de esta interfaz y deben implementar cada uno de sus cinco métodos.

OnConnection

El evento OnConnection se desencadena siempre que el complemento está conectado. El complemento puede conectarse en el inicio, por el usuario final, o a través de automatización. Si el evento OnConnection devuelve correctamente, el complemento se dice que se va a cargar. Si se devuelve un mensaje de error, la aplicación host libera su referencia para el complemento inmediatamente y se destruye el objeto.

El evento OnConnection toma los cuatro parámetros siguientes:
  • aplicación : referencia a objeto de la aplicación host.
  • ConnectMode : constante que especifica cómo se conecta el complemento. El complemento se puede conectar de las maneras siguientes:
    • ext_cm_AfterStartup : el complemento inicia el usuario final en el cuadro de diálogo complementos COM .
    • ext_cm_CommandLine : el complemento está conectado desde la línea de comandos. Tenga en cuenta que esto no se aplica a la creación de complementos COM para las aplicaciones de Office.
    • ext_cm_External : el complemento está conectado mediante una aplicación externa mediante automatización. Tenga en cuenta que esto no se aplica a la creación de complementos COM para Office aplicaciones.
    • ext_cm_Startup : el complemento se inicia mediante el host al iniciarse la aplicación. Este comportamiento se controla mediante una configuración en el registro.
  • AddInInst : una referencia al objeto COMAddIn que hace referencia a este complemento en la colección COMAddIns de la aplicación host.
  • personalizado : una matriz de valores de tipo Variant que puede contener datos definidos por el usuario.

OnDisconnection

El evento OnDisconnection se desencadena cuando el complemento se desconecta y justo antes de descarga de memoria. El complemento debe realizar la limpieza de recursos en este evento y restaurar los cambios realizados en la aplicación host.

El evento OnDisconnection toma los dos parámetros siguientes:
  • RemoveMode : constante que especifica cómo se ha desconectado el complemento. El complemento se puede desconectar de las maneras siguientes:
    • ext_dm_HostShutdown : el complemento se desconecta cuando cierra la aplicación host.
    • ext_dm_UserClosed : el complemento se desconecta por el usuario final o una automatización controlador.
  • personalizado : una matriz de valores de tipo Variant que puede contener datos definidos por el usuario.

OnAddInsUpdate

El evento OnAddInsUpdate se desencadena cuando el conjunto de registrado COM cambios de complementos. En otras palabras, siempre que un complemento está instalado o quitado de la aplicación host, este evento se desencadena.

OnStartupComplete y OnBeginShutdown

Tanto el método OnStartupComplete y el método OnBeginShutdown se llama cuando la aplicación host ha dejado o está entrando en un estado en que el usuario debe evitarse interacción porque la aplicación está ocupada cargando o descargando propio de la memoria. Se llama al método OnStartupComplete sólo si del complemento estaba conectado durante el inicio y se llama al método OnBeginShutdown sólo si el host desconecta el complemento durante el apagado.

Debido a que la interfaz de usuario para la aplicación host es plenamente activa cuando estos eventos se desencadenan, pueden ser la única manera de realizar determinadas acciones en caso contrario, sería no está disponibles desde el evento OnConnection y el evento OnDisconnection .

Registro del complemento COM

Además el registro COM normal, un complemento necesita registrarse a sí mismo con cada aplicación de Office en el que se ejecuta. Para registrarse con una aplicación determinada, el complemento debe crear una subclave, con su ProgID como el nombre de la clave en la siguiente ubicación:
HKEY_CURRENT_USER\Software\Microsoft\Office\<OfficeApp>\Addins\<ProgID>
El complemento puede proporcionar valores en esta ubicación clave para un nombre descriptivo y una descripción completa. Además, el complemento debe especificar su comportamiento de carga deseada mediante un valor DWORD que se denomina LoadBehavior. Este valor determina cómo el complemento se carga por la aplicación host y se compone de una combinación de los siguientes valores:
  • 0 = Desconectar - no está cargado.
  • 1 = Conectado - está cargado.
  • 2 = Bootload - cargar al inicio de la aplicación.
  • 8 = DemandLoad - carga sólo cuando se solicitan por usuario.
  • 16 = ConnectFirstTime - carga sólo una vez (en el siguiente inicio).
El valor típico especificado es 0 x 03 (conectado | bootload).

Los complementos que implementan IDTExtensibility2 deben especificar también un valor DWORD llamado
CommandLineSafe
para indicar si los complementos son seguros para operaciones que no admiten una interfaz de usuario. Un valor de 0 x 00 indica FALSO y un valor de 0 x 01 indica que True.

Cómo crear un complemento utilizando Visual C# .NET

Como se mencionó anteriormente, un complemento de COM de Office es un COM en proceso servidor que se activa mediante una aplicación de Office a través de la capa de tiempo de ejecución COM. Por tanto, desarrollar un complemento COM en .NET requiere que el componente de complemento se implementa en .NET y, a continuación, expone a los clientes COM (es decir, las aplicaciones de Office) a través de la capa de interoperabilidad COM.

Para crear un complemento en Visual C#. NET, siga estos pasos:
  1. En Visual C#. NET, cree una biblioteca de clases proyecto.
  2. Agregue una referencia a la biblioteca de tipo que implementa IDTExtensibility2 . Para este ensamblado de interoperabilidad primario ya está disponible en el nombre de extensibilidad .
  3. Agregue una referencia a la biblioteca de objeto Microsoft Office. Para este ensamblado de interoperabilidad primario ya está disponible en el nombre de Office .
  4. Cree una clase pública en la biblioteca de clase que implementa IDTExtensibility2 .
  5. Después de la clase se genera la biblioteca, registrar la biblioteca para la interoperabilidad COM. Para ello, generar un seguro denominado ensamblado para esta biblioteca de clase y, a continuación, regístrelo con interoperabilidad COM. Puede utilizar Regasm.exe para registrar un componente de .NET para la interoperabilidad COM.
  6. Crear entradas del registro para que las aplicaciones de Office pueden reconocer y cargar el complemento.
Puede elegir completar todos estos pasos o puede crear un proyecto .NET del tipo de Complemento compartido . Esto inicia el Asistente de para extensibilidad, que le ayuda a crear un complemento en. NET.

El Asistente de extensibilidad crea Visual C# proyecto de .NET de biblioteca de clases junto con una clase de Conectar que implementa la interfaz IDTExtensibility2 . También se genera el código esqueleto que implementa a los miembros vacíos de IDTExtensibility . Este proyecto contiene referencias a ensamblados extensibilidad y Office. La configuración de generación del proyecto tiene que Registrar para interoperabilidad COM seleccionado. El archivo de clave (.snk) del ensamblado se genera y se hace referencia en el atributo AssemblyKeyfile en AssemblyInfo.vb.

Junto con el proyecto de biblioteca de clases, el asistente genera un proyecto de instalación que puede utilizar para implementar el complemento COM en otros equipos. Puede quitar este proyecto si lo desea.

Ejemplo paso a paso

  1. En el menú archivo en Visual Studio.NET, haga clic en nuevo y, a continuación, haga clic en proyecto .
  2. En el cuadro de diálogo Nuevo proyecto , expanda Otros proyectos en Tipos de proyecto , seleccione Proyectos de extensibilidad y seleccione la plantilla Add-in Shared .
  3. Escriba MyCOMAddin como el nombre de la macro y haga clic en Aceptar .
  4. Cuando aparezca el Asistente para extensibilidad, siga estos pasos:
    1. En la página 1, seleccione crear un complemento utilizando C# y, a continuación, haga clic en siguiente .
    2. En página 2, seleccione las siguientes aplicaciones de host y, a continuación, haga clic en siguiente :
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
    3. En la página 3, proporcione un nombre y una descripción para el complemento y, a continuación, haga clic en siguiente .

      Nota El nombre y la descripción del complemento en aparecen en el cuadro de diálogo complemento COM en la aplicación de Office.

    4. En la página 4, seleccione todos de las opciones disponibles y, a continuación, haga clic en siguiente .
    5. Haga clic en Finalizar .
  5. En el menú proyecto , haga clic en Agregar referencia . Haga clic en System.Windows.Forms.dll en la lista de componentes, haga clic en Seleccionar y, a continuación, haga clic en Aceptar .
  6. Agregar lo siguiente a la lista de espacios de nombres en la clase Connect :
    using System.Reflection;
  7. Agregue el siguiente miembro a la clase Connect :
    private CommandBarButton MyButton; 
  8. Implementar el código para los miembros de IDTExtensibility2 en la clase Connect , como sigue:
    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. Generar y probar el complemento. Para ello, siga estos pasos:
    1. En el menú Generar , haga clic en Generar solución . Tenga en cuenta que al generar el complemento se registra la clase de .NET con la interoperabilidad COM.
    2. Inicie uno de las aplicaciones de Office que seleccionó como aplicaciones de host para el complemento (por ejemplo, Microsoft Word o Microsoft Excel).
    3. Una vez el complemento ha iniciado, el OnStartupComplete se desencadena el evento de la macro y recibirá un mensaje. Cerrar el cuadro de mensaje. Observe que el complemento agregado un nuevo botón personalizado con el título "Mi botón personalizado" a la barra de herramientas estándar.
    4. Haga clic en el botón personalizado . El evento Click para el botón está controlado por el complemento y recibirá un cuadro de mensaje. Cerrar el cuadro de mensaje.
    5. Salga de la aplicación de Office.
    6. Al salir de la aplicación, el OnBeginShutDown evento se desencadena y recibe un mensaje. Para cerrar el cuadro de mensaje para finalizar la demostración.

Referencias

Para obtener información adicional sobre cómo escribir complementos COM, haga clic en el número de artículo siguiente para verlo en Microsoft Knowledge Base:
190253INFORMACIÓN: Los diseñadores de VB6 no funcionan en VB5

Propiedades

Id. de artículo: 302901 - Última revisión: viernes, 11 de mayo de 2007 - Versión: 10.2
La información de este artículo se refiere 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
  • 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
Palabras clave: 
kbmt kbautomation kbhowtomaster KB302901 KbMtes
Traducción automática
IMPORTANTE: Este artículo ha sido traducido por un software de traducción automática de Microsoft (http://support.microsoft.com/gp/mtdetails) en lugar de un traductor humano. Microsoft le ofrece artículos traducidos por un traductor humano y artículos traducidos automáticamente para que tenga acceso en su propio idioma a todos los artículos de nuestra base de conocimientos (Knowledge Base). Sin embargo, los artículos traducidos automáticamente pueden contener errores en el vocabulario, la sintaxis o la gramática, como los que un extranjero podría cometer al hablar el idioma. Microsoft no se hace responsable de cualquier imprecisión, error o daño ocasionado por una mala traducción del contenido o como consecuencia de su utilización por nuestros clientes. Microsoft suele actualizar el software de traducción frecuentemente.
Haga clic aquí para ver el artículo original (en inglés): 302901

Enviar comentarios

 

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