Programming Application-Level Add-Ins
When you extend a Microsoft Office application by creating an application-level 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 add-in to other Office solutions.
Applies to: The information in this topic applies to application-level projects for Microsoft Office 2013 and Microsoft Office 2010. For more information, see Features Available by Office Application and Project Type.
Some aspects of writing code in 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 application-level add-ins and other types of solutions you can create by using the Office development tools in Visual Studio, see Office Solutions Development Overview.
Using the ThisAddIn Class
You can start writing your 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 add-in project. The Visual Studio Tools for Office runtime automatically instantiates this class for you when the Microsoft Office application loads your add-in.
There are two default event handlers in the ThisAddIn class. To run code when the add-in is loaded, add code to the ThisAddIn_Startup event handler. To run code just before the 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 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 add-in project.
Host application |
Return value type |
|---|---|
Microsoft Office Excel |
|
Microsoft Office InfoPath |
|
Microsoft Office Outlook |
|
Microsoft Office PowerPoint |
|
Microsoft Office Project |
Microsoft.Office.Interop.MSProject.Application |
Microsoft Office Visio |
Microsoft.Office.Interop.Visio.Application |
Microsoft Office Word |
The following code example shows how to use the Application field to create a new workbook in an 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:
Accessing a Document When the Office Application Starts
Not all Microsoft 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
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.
}
}
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 add-in when the 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 add-in before the 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 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 add-in to other Microsoft Office solutions. |
Override the RequestComAddInAutomationService method. For more information, see Calling Code in Application-Level 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 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.
Customizing the User Interface of Microsoft Office Applications
You can programmatically customize the UI of Microsoft Office applications by using an application-level 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 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 Application-Level Add-ins at Run Time.
Calling Code in Application-Level Add-ins from Other Solutions
You can expose objects in your add-in to other solutions, including other Office solutions. This is useful if your add-in provides a service that you want to enable other solutions to use. For example, if you have an 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 add-in at run time.
For more information, see Calling Code in Application-Level Add-ins from Other Office Solutions.
See Also
Tasks
Walkthrough: Calling Code in an Application-Level Add-in from VBA
How to: Create Office Projects in Visual Studio
Concepts
Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time
Calling Code in Application-Level Add-ins from Other Office Solutions
Customizing UI Features By Using Extensibility Interfaces
Architecture of Application-Level Add-Ins
Writing Code in Office Solutions