Programming VSTO Add-Ins

 

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

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.

System_CAPS_ICON_note.jpg 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.

Accessing 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 applicationReturn value type
Microsoft Office ExcelMicrosoft.Office.Interop.Excel.Application
Microsoft Office InfoPathT:Microsoft.Office.Interop.InfoPath.Application
Microsoft Office OutlookT:Microsoft.Office.Interop.Outlook.Application
Microsoft Office PowerPointT:Microsoft.Office.Interop.PowerPoint.Application
Microsoft Office ProjectMicrosoft.Office.Interop.MSProject.Application
Microsoft Office VisioMicrosoft.Office.Interop.Visio.Application
Microsoft Office WordMicrosoft.Office.Interop.Word.Application

The following code example shows how to use the Application field to create a new workbook in an 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()

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

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

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

TaskMember 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_Startup 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 Calling 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 Customizing UI Features By Using Extensibility Interfaces. Note: To customize the ribbon UI, you can also override the CreateRibbonExtensibilityObject method.

Understanding the Design of the ThisAddIn Class

In projects that target the .NET Framework 4, Microsoft.Office.Tools.AddIn is an interface. The ThisAddIn class derives from the Microsoft.Office.Tools.AddInBase class. This base class redirects all calls to its members to an internal implementation of the Microsoft.Office.Tools.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 Microsoft.Office.Tools.Outlook.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 Creating Outlook Form Regions.

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 Creating 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 Customizing 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 Extending Word Documents and Excel Workbooks in VSTO Add-ins at Run Time.

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 an 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 Calling Code in VSTO Add-ins from Other Office Solutions.

Developing Office Solutions
Extending Word Documents and Excel Workbooks in VSTO Add-ins at Run Time
Calling Code in VSTO Add-ins from Other Office Solutions
Walkthrough: Calling Code in a VSTO Add-in from VBA
Customizing UI Features By Using Extensibility Interfaces
How to: Create Office Projects in Visual Studio
Architecture of VSTO Add-ins
Writing Code in Office Solutions

Show: