Program VSTO Add-ins

Artigo
02/02/2017

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

When you extend a Microsoft Office application by creating a VSTO Add-in, you write code directly against the ThisAddIn class in your project. 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.

Applies to: The information in this topic applies to VSTO Add-in projects. For more information, see Features available by Office application and project type.

Some aspects of writing code in VSTO Add-in projects are different from other types of projects in Visual Studio. Many of these differences are caused by the way the Office object models are exposed to managed code. For more information, see Write code in Office solutions.

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).

Use the ThisAddIn class

You can start writing your VSTO Add-in code in the ThisAddIn class. Visual Studio automatically generates this class in the ThisAddIn.vb (in Visual Basic) or ThisAddIn.cs (in C#) code file in your VSTO Add-in project. The Visual Studio Tools for Office runtime automatically instantiates this class for you when the Microsoft Office application loads your VSTO Add-in.

There are two default event handlers in the ThisAddIn class. To run code when the VSTO Add-in is loaded, add code to the ThisAddIn_Startup event handler. To run code just before the VSTO Add-in is unloaded, add code to the ThisAddIn_Shutdown event handler. For more information about these event handlers, see Events in Office projects.

Note

In Outlook, by default the ThisAddIn_Shutdown event handler is not always called when the VSTO Add-in is unloaded. For more information, see Events in Office projects.

Access the object model of the host application

To access the object model of the host application, use the Application field of the ThisAddIn class. This field returns an object that represents the current instance of the host application. The following table lists the type of the return value for the Application field in each VSTO Add-in project.

Host application	Return value type
Microsoft Office Excel	Application
Microsoft Office InfoPath	Application
Microsoft Office Outlook	Application
Microsoft Office PowerPoint	Application
Microsoft Office Project	Microsoft.Office.Interop.MSProject.Application
Microsoft Office Visio	Microsoft.Office.Interop.Visio.Application
Microsoft Office Word	Application

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. 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);

To do the same thing from outside the ThisAddIn class, use the Globals object to access the ThisAddIn class. 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);

For more information about the object models of specific Microsoft Office applications, see the following topics:

Access a document when the Office application starts

Not all Office 2010 applications automatically open a document when you start them, and none of the Office 2013 applications open a document when you start them. Therefore, don't add code in the ThisAdd-In_Startup event handler if the code requires a document to be open. Instead, add that code to an event that the Office application raises when a user creates or opens a document. That way, you can guarantee that a document is open before your code performs operations on it.

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

ThisAddIn members to use for other tasks

The following table describes other common tasks and shows which members of the ThisAddIn class you can use to perform the tasks.

Task	Member to use
Run code to initialize the VSTO Add-in when the VSTO Add-in is loaded.	Add code to the `ThisAddIn_Startup` method. This is the default event handler for the Startup event. For more information, see Events in Office projects.
Run code to clean up resources used by the VSTO Add-in before the VSTO Add-in is unloaded.	Add code to the `ThisAddIn_Shutdown` method. This is the default event handler for the Shutdown event. For more information, see Events in Office projects. Note: In Outlook, by default the `ThisAddIn_Shutdown` event handler is not always called when the VSTO Add-in is unloaded. For more information, see Events in Office projects.
Display a custom task pane.	Use the `CustomTaskPanes` field. For more information, see Custom task panes.
Expose objects in your VSTO Add-in to other Microsoft Office solutions.	Override the RequestComAddInAutomationService method. For more information, see Call code in VSTO Add-ins from other Office solutions.
Customize a feature in the Microsoft Office system by implementing an extensibility interface.	Override the RequestService method to return an instance of a class that implements the interface. For more information, see Customize UI features by using extensibility interfaces. Note: To customize the ribbon UI, you can also override the CreateRibbonExtensibilityObject method.

Understand the design of the ThisAddIn class

In projects that target the .NET Framework 4, AddIn is an interface. The ThisAddIn class derives from the AddInBase class. This base class redirects all calls to its members to an internal implementation of the AddIn interface in the Visual Studio Tools for Office runtime.

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. These base classes provide some additional functionality to support form regions. For more information about form regions, see Create Outlook form regions.

Customize the user interface of Microsoft Office applications

You can programmatically customize the UI of Microsoft Office applications by using a VSTO Add-in. For example, you can customize the ribbon, display a custom task pane, or create a custom form region in Outlook. For more information, see Office UI customization.

Visual Studio provides designers and classes that you can use to create custom task panes, ribbon customizations, and Outlook form regions. These designers and classes help to simplify the process of customizing these features. For more information, see Custom task panes, Ribbon Designer, and Create Outlook form regions.

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. For more information, see Customize UI features by using extensibility interfaces.

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. This enables you to add managed controls to documents and worksheets. For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at run time.

Call code in VSTO Add-ins from other solutions

You can expose objects in your VSTO Add-in to other solutions, including other Office solutions. This is useful if your VSTO Add-in provides a service that you want to enable other solutions to use. 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.

For more information, see Call code in VSTO Add-ins from other Office solutions.

Partilhar via