Programar complementos VSTOProgram VSTO Add-ins

Cuando se amplía una aplicación de Microsoft Office mediante la creación de un complemento VSTO, el código se escribe directamente en la clase ThisAddIn de su proyecto.When you extend a Microsoft Office application by creating a VSTO Add-in, you write code directly against the ThisAddIn class in your project. Puede usar esta clase para realizar tareas tales como tener acceso al modelo de objetos de la aplicación host de Microsoft Office, personalizar la interfaz de usuario (UI) de la aplicación y exponer objetos del complemento VSTO en otras soluciones de Office.You can use this class to perform tasks such as accessing the object model of the Microsoft Office host application, customizing the user interface (UI) of the application, and exposing objects in your VSTO Add-in to other Office solutions.

Se aplica a: La información de este tema se aplica a VSTO agregar-en los proyectos.Applies to: The information in this topic applies to VSTO Add-in projects. Para obtener más información, consulte características disponibles por tipo de aplicación y el proyecto de Office.For more information, see Features available by Office application and project type.

Algunos aspectos de la escritura de código en proyectos de complementos VSTO difieren de otros tipos de proyectos de Visual Studio.Some aspects of writing code in VSTO Add-in projects are different from other types of projects in Visual Studio. Muchas de estas diferencias se deben a la forma en que los modelos de objetos de Office se exponen al código administrado.Many of these differences are caused by the way the Office object models are exposed to managed code. Para obtener más información, consulte escribir código en soluciones de Office.For more information, see Write code in Office solutions.

Para obtener información general sobre los complementos VSTO y otros tipos de soluciones puede crear mediante el uso de las herramientas de desarrollo de Office en Visual Studio, consulte información general sobre el desarrollo de soluciones de Office (VSTO).For general information about VSTO Add-ins and other types of solutions you can create by using the Office development tools in Visual Studio, see Office solutions development overview (VSTO).

Utilice la clase ThisAddInUse the ThisAddIn class

Puede empezar a escribir el código del complemento VSTO en la clase ThisAddIn .You can start writing your VSTO Add-in code in the ThisAddIn class. Visual Studio genera automáticamente esta clase en el ThisAddIn.vb (en Visual BasicVisual Basic) o ThisAddIn.cs archivo en el proyecto de complemento VSTO de código (en C#).Visual Studio automatically generates this class in the ThisAddIn.vb (in Visual BasicVisual Basic) or ThisAddIn.cs (in C#) code file in your VSTO Add-in project. El elemento Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime crea automáticamente una instancia de esta clase cuando la aplicación de Microsoft Office carga el complemento VSTO.The Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime automatically instantiates this class for you when the Microsoft Office application loads your VSTO Add-in.

Hay dos controladores de eventos predeterminados en la clase ThisAddIn .There are two default event handlers in the ThisAddIn class. Para ejecutar el código cuando se carga el complemento VSTO, agregue el código al controlador de eventos ThisAddIn_Startup .To run code when the VSTO Add-in is loaded, add code to the ThisAddIn_Startup event handler. Para ejecutar el código justo antes de que se descargue el complemento VSTO, agregue el código al controlador de eventos ThisAddIn_Shutdown .To run code just before the VSTO Add-in is unloaded, add code to the ThisAddIn_Shutdown event handler. Para obtener más información acerca de estos controladores de eventos, consulte eventos en proyectos de Office.For more information about these event handlers, see Events in Office projects.

Note

En Outlook, de forma predeterminada, no siempre se llama al controlador de eventos ThisAddIn_Shutdown cuando el complemento VSTO se descarga.In Outlook, by default the ThisAddIn_Shutdown event handler is not always called when the VSTO Add-in is unloaded. Para obtener más información, consulte eventos en proyectos de Office.For more information, see Events in Office projects.

Obtener acceso al modelo de objeto de la aplicación hostAccess the object model of the host application

Para obtener acceso al modelo de objetos de la aplicación host, utilice el campo Application de la clase ThisAddIn .To access the object model of the host application, use the Application field of the ThisAddIn class. Este campo devuelve un objeto que representa la instancia actual de la aplicación host.This field returns an object that represents the current instance of the host application. La siguiente tabla muestra el tipo de valor devuelto del campo Application en cada proyecto de complemento VSTO.The following table lists the type of the return value for the Application field in each VSTO Add-in project.

Aplicación hostHost application Tipo de valor devueltoReturn value type
Microsoft Office ExcelMicrosoft Office Excel Application
Microsoft Office InfoPathMicrosoft Office InfoPath Microsoft.Office.Interop.InfoPath.Application
Microsoft Office OutlookMicrosoft Office Outlook Microsoft.Office.Interop.Outlook.Application
Microsoft Office PowerPointMicrosoft Office PowerPoint Microsoft.Office.Interop.PowerPoint.Application
Microsoft Office ProjectMicrosoft Office Project Microsoft.Office.Interop.MSProject.ApplicationMicrosoft.Office.Interop.MSProject.Application
Microsoft Office VisioMicrosoft Office Visio Microsoft.Office.Interop.Visio.ApplicationMicrosoft.Office.Interop.Visio.Application
Microsoft Office WordMicrosoft Office Word Application

En el ejemplo de código siguiente se muestra cómo utilizar el Application campo para crear un nuevo libro en un complemento VSTO para Microsoft Office Excel.The following code example shows how to use the Application field to create a new workbook in a VSTO Add-in for Microsoft Office Excel. Este ejemplo está pensado para ejecutarse desde la clase ThisAddIn .This example is intended to be run from the ThisAddIn class.

Dim newWorkbook As Excel.Workbook = Me.Application.Workbooks.Add()
Excel.Workbook newWorkbook = this.Application.Workbooks.Add(System.Type.Missing);

Para hacer lo mismo desde fuera de la clase ThisAddIn , use el objeto Globals para tener acceso a la clase ThisAddIn .To do the same thing from outside the ThisAddIn class, use the Globals object to access the ThisAddIn class. Para obtener más información sobre la Globals de objetos, consulte acceso Global a objetos en los proyectos de Office.For more information about the Globals object, see Global access to objects in Office projects.

Dim newWorkbook As Excel.Workbook = Globals.ThisAddIn.Application.Workbooks.Add()
Excel.Workbook newWorkbook = Globals.ThisAddIn.Application.Workbooks.Add(System.Type.Missing);

Para obtener más información acerca de los modelos de objetos de aplicaciones de Microsoft Office concretas, vea los temas siguientes:For more information about the object models of specific Microsoft Office applications, see the following topics:

Obtener acceso a un documento cuando se inicia la aplicación de OfficeAccess a document when the Office application starts

No todas las aplicaciones Office 2010Office 2010 abren automáticamente un documento al iniciarlas, y ninguna de las aplicaciones Office 2013Office 2013 abre un documento al iniciarla.Not all Office 2010Office 2010 applications automatically open a document when you start them, and none of the Office 2013Office 2013 applications open a document when you start them. Por lo tanto, no agregue el código en el ThisAdd-In_Startup controlador de eventos si el código requiere que un documento esté abierto.Therefore, don't add code in the ThisAdd-In_Startup event handler if the code requires a document to be open. En su lugar, agregue ese código a un evento que sea generado por la aplicación de Office cuando un usuario cree o abra un documento.Instead, add that code to an event that the Office application raises when a user creates or opens a document. De este modo, puede garantizar que haya un documento abierto para que el código realice operaciones en él.That way, you can guarantee that a document is open before your code performs operations on it.

El siguiente ejemplo de código funciona con un documento de Word sólo cuando el usuario crea un documento o abre un documento existente.The following code example works with a document in Word only when the user creates a document or opens an existing document.

    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        this.Application.DocumentOpen +=
new Word.ApplicationEvents4_DocumentOpenEventHandler(WorkWithDocument);

        ((Word.ApplicationEvents4_Event)this.Application).NewDocument +=
            new Word.ApplicationEvents4_NewDocumentEventHandler(WorkWithDocument);  
    }
    
    private void WorkWithDocument(Microsoft.Office.Interop.Word.Document Doc)
    {
        try
        {
            Word.Range rng = Doc.Range(0, 0);
            rng.Text = "New Text";
            rng.Select();
        }
        catch (Exception ex)
        {
            // Handle exception if for some reason the document is not available.
        }
    }
Private Sub ThisAddIn_Startup() Handles Me.Startup

    AddHandler Application.NewDocument, AddressOf WorkWithDocument

End Sub

Private Sub WorkWithDocument(ByVal Doc As Microsoft.Office.Interop.Word.Document) _
    Handles Application.DocumentOpen

    Dim rng As Word.Range = Doc.Range(Start:=0, End:=0)
    rng.Text = " New Text "
    rng.Select()

End Sub

Miembros de ThisAddIn que se usará para otras tareasThisAddIn members to use for other tasks

La tabla siguiente se describen otras tareas habituales y muestra los miembros de la clase ThisAddIn que puede utilizar para realizar las tareas.The following table describes other common tasks and shows which members of the ThisAddIn class you can use to perform the tasks.

TareaTask Miembro para usarMember to use
Ejecute el código para inicializar el complemento VSTO cuando este se cargue.Run code to initialize the VSTO Add-in when the VSTO Add-in is loaded. Agregue código al método ThisAddIn_Startup .Add code to the ThisAddIn_Startup method. Este es el controlador de eventos predeterminado para el evento Startup .This is the default event handler for the Startup event. Para obtener más información, consulte eventos en proyectos de Office.For more information, see Events in Office projects.
Ejecute el código para limpiar los recursos usados por el complemento VSTO antes de que este se descargue.Run code to clean up resources used by the VSTO Add-in before the VSTO Add-in is unloaded. Agregue código al método ThisAddIn_Shutdown .Add code to the ThisAddIn_Shutdown method. Este es el controlador de eventos predeterminado para el evento Shutdown .This is the default event handler for the Shutdown event. Para obtener más información, consulte eventos en proyectos de Office.For more information, see Events in Office projects. Nota: En Outlook, de forma predeterminada, no siempre se llama al controlador de eventos ThisAddIn_Startup cuando el complemento VSTO se descarga.Note: In Outlook, by default the ThisAddIn_Startup event handler is not always called when the VSTO Add-in is unloaded. Para obtener más información, consulte eventos en proyectos de Office.For more information, see Events in Office projects.
Mostrar un panel de tareas personalizado.Display a custom task pane. Utilice el campo CustomTaskPanes .Use the CustomTaskPanes field. Para obtener más información, consulte paneles de tareas personalizados.For more information, see Custom task panes.
Exponer objetos de un complemento VSTO en otras soluciones de Microsoft Office.Expose objects in your VSTO Add-in to other Microsoft Office solutions. Invalide el método RequestComAddInAutomationService .Override the RequestComAddInAutomationService method. Para obtener más información, consulte llamar a código en complementos VSTO desde otras soluciones de Office.For more information, see Call code in VSTO Add-ins from other Office solutions.
Personalizar una característica del sistema Microsoft Office implementando una interfaz de extensibilidad.Customize a feature in the Microsoft Office system by implementing an extensibility interface. Invalide el método RequestService para que devuelva una instancia de una clase que implemente la interfaz.Override the RequestService method to return an instance of a class that implements the interface. Para obtener más información, consulte características de personalización de la interfaz de usuario mediante interfaces de extensibilidad.For more information, see Customize UI features by using extensibility interfaces. Nota: Para personalizar la interfaz de usuario de la cinta de opciones, también puede invalidar el método CreateRibbonExtensibilityObject.Note: To customize the ribbon UI, you can also override the CreateRibbonExtensibilityObject method.

Entender el diseño de la clase ThisAddInUnderstand the design of the ThisAddIn class

En los proyectos que tienen como destino .NET Framework 4.NET Framework 4, AddIn es una interfaz.In projects that target the .NET Framework 4.NET Framework 4, AddIn is an interface. La clase ThisAddIn se deriva de la clase AddInBase .The ThisAddIn class derives from the AddInBase class. Esta clase base redirige todas las llamadas a sus miembros a una implementación interna de la interfaz AddIn en Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime.This base class redirects all calls to its members to an internal implementation of the AddIn interface in the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime.

En proyectos de complementos VSTO de Outlook, la clase ThisAddIn se deriva de la clase Microsoft.Office.Tools.Outlook.OutlookAddIn en proyectos destinados a .NET Framework 3.5, y de la clase OutlookAddInBase en proyectos destinados a .NET Framework 4.NET Framework 4.In VSTO Add-in projects for Outlook, the ThisAddIn class derives from the Microsoft.Office.Tools.Outlook.OutlookAddIn class in projects that target the .NET Framework 3.5, and from OutlookAddInBase in projects that target the .NET Framework 4.NET Framework 4. Estas clases base proporcionan funciones adicionales para admitir las áreas de formulario.These base classes provide some additional functionality to support form regions. Para obtener más información acerca de las áreas de formulario, consulte crear áreas de formulario.For more information about form regions, see Create Outlook form regions.

Personalizar la interfaz de usuario de aplicaciones de Microsoft OfficeCustomize the user interface of Microsoft Office applications

Puede personalizar mediante programación la interfaz de usuario de las aplicaciones de Microsoft Office mediante un complemento VSTO.You can programmatically customize the UI of Microsoft Office applications by using a VSTO Add-in. Por ejemplo, puede personalizar la cinta de opciones, mostrar un panel de tareas personalizado o crear un área de formulario personalizada en Outlook.For example, you can customize the ribbon, display a custom task pane, or create a custom form region in Outlook. Para obtener más información, consulte personalización de la interfaz de usuario de Office.For more information, see Office UI customization.

Visual Studio proporciona diseñadores y clases que puede utilizar para crear paneles de tareas personalizados, personalizaciones de la cinta de opciones y áreas de formulario de Outlook.Visual Studio provides designers and classes that you can use to create custom task panes, ribbon customizations, and Outlook form regions. Estos diseñadores y clases ayudan a simplificar el proceso de personalización de estas características.These designers and classes help to simplify the process of customizing these features. Para obtener más información, consulte paneles de tareas personalizados, Ribbon Designer, y crear áreas de formulario.For more information, see Custom task panes, Ribbon Designer, and Create Outlook form regions.

Si desea personalizar una de estas características de forma que no sea compatible con las clases y los diseñadores, puede personalizarlas mediante la implementación de una interfaz de extensibilidad en el complemento VSTO.If you want to customize one of these features in a way that is not supported by the classes and designers, you can also customize these features by implementing an extensibility interface in your VSTO Add-in. Para obtener más información, consulte características de personalización de la interfaz de usuario mediante interfaces de extensibilidad.For more information, see Customize UI features by using extensibility interfaces.

Además, puede modificar la interfaz de usuario de los documentos de Word y libros de Excel generando elementos host que extienden el comportamiento de documentos y libros.In addition, you can modify the UI of Word documents and Excel workbooks by generating host items that extend the behavior of documents and workbooks. Esto le permite agregar controles administrados a documentos y hojas de cálculo.This enables you to add managed controls to documents and worksheets. Para obtener más información, consulte documentos ampliar Word y libros de Excel en complementos VSTO en tiempo de ejecución.For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

Llamar a código en complementos VSTO desde otras solucionesCall code in VSTO Add-ins from other solutions

Puede exponer los objetos de su complemento VSTO en otras soluciones (incluidas otras soluciones de Microsoft Office).You can expose objects in your VSTO Add-in to other solutions, including other Office solutions. Esto resulta útil si su complemento VSTO proporciona un servicio que quiera habilitar para que lo usen otras soluciones.This is useful if your VSTO Add-in provides a service that you want to enable other solutions to use. Por ejemplo, si tiene un complemento VSTO para Microsoft Office Excel que realiza cálculos sobre datos financieros desde un servicio web, otras soluciones pueden realizar estos cálculos llamando al complemento VSTO de Excel en tiempo de ejecución.For example, if you have a VSTO Add-in for Microsoft Office Excel that performs calculations on financial data from a web service, other solutions can perform these calculations by calling into the Excel VSTO Add-in at run time.

Para obtener más información, consulte llamar a código en complementos VSTO desde otras soluciones de Office.For more information, see Call code in VSTO Add-ins from other Office solutions.

Vea tambiénSee also