Walkthrough: Creating Your First Application-Level Add-in for Word

Article
04/28/2015

This introductory walkthrough shows you how to create an application-level add-in for Microsoft Office Word. The features that you create in this kind of solution are available to the application itself, regardless of which documents are open.

Applies to: The information in this topic applies to application-level projects for Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

Creating a Word add-in project.
Writing code that uses the object model of Word to add text to a document when it is saved.
Building and running the project to test it.
Cleaning up the completed project so that the add-in no longer runs automatically on your development computer.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Customizing Development Settings in Visual Studio.

Prerequisites

You need the following components to complete this walkthrough:

An edition of Visual Studio 2013 that includes the Microsoft Office developer tools. For more information, see Configuring a Computer to Develop Office Solutions.
Word 2013 or Word 2010.

Creating the Project

To create a new Word add-in project in Visual Studio

Start Visual Studio.
On the File menu, point to New, and then click Project.
In the templates pane, expand Visual C# or Visual Basic, and then expand Office/SharePoint.
Under the expanded Office/SharePoint node, select the Office Add-ins node.
In the list of project templates, select Word 2010 Add-in or Word 2013 Add-in.
In the Name box, type FirstWordAddIn.
Click OK.

Visual Studio creates the FirstWordAddIn project and opens the ThisAddIn code file in the editor.

Writing Code to Add Text to the Saved Document

Next, add code to the ThisAddIn code file. The new code uses the object model of Word to add boilerplate text to each saved document. By default, the ThisAddIn code file contains the following generated code:

A partial definition of the ThisAddIn class. This class provides an entry point for your code and provides access to the object model of Word. For more information, see Programming Application-Level Add-Ins. The remainder of the ThisAddIn class is defined in a hidden code file that you should not modify.
The ThisAddIn_Startup and ThisAddIn_Shutdown event handlers. These event handlers are called when Word loads and unloads your add-in. Use these event handlers to initialize your add-in when it is loaded, and to clean up resources used by your add-in when it is unloaded. For more information, see Events in Office Projects.

To add a paragraph of text to the saved document

In the ThisAddIn code file, add the following code to the ThisAddIn class. The new code defines an event handler for the DocumentBeforeSave event, which is raised when a document is saved.

When the user saves a document, the event handler adds new text at the start of the document.
```
Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, ByRef SaveAsUI As Boolean, _
    ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
    Doc.Paragraphs(1).Range.InsertParagraphBefore()
    Doc.Paragraphs(1).Range.Text = "This text was added by using code." 
End Sub
```
```
void Application_DocumentBeforeSave(Word.Document Doc, ref bool SaveAsUI, ref bool Cancel)
{
    Doc.Paragraphs[1].Range.InsertParagraphBefore();
    Doc.Paragraphs[1].Range.Text = "This text was added by using code.";
}
```
Note

This code uses an index value of 1 to access the first paragraph in the Paragraphs collection. Although Visual Basic and Visual C# use 0-based arrays, the lower array bounds of most collections in the Word object model is 1. For more information, see Writing Code in Office Solutions.
If you are using C#, add the following required code to the ThisAddIn_Startup event handler. This code is used to connect the Application_DocumentBeforeSave event handler with the DocumentBeforeSave event.
```
this.Application.DocumentBeforeSave += 
    new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(Application_DocumentBeforeSave);
```

To modify the document when it is saved, the previous code examples use the following objects:

The Application field of the ThisAddIn class. The Application field returns a Application object, which represents the current instance of Word.
The Doc parameter of the event handler for the DocumentBeforeSave event. The Doc parameter is a Document object, which represents the saved document. For more information, see Word Object Model Overview.

Testing the Project

To test the project

Press F5 to build and run your project.

When you build the project, the code is compiled into an assembly that is included in the build output folder for the project. Visual Studio also creates a set of registry entries that enable Word to discover and load the add-in, and it configures the security settings on the development computer to enable the add-in to run. For more information, see Building Office Solutions.
In Word, save the active document.
Verify that the following text is added to the document.

This text was added by using code.
Close Word.

Cleaning up the Project

When you finish developing a project, remove the add-in assembly, registry entries, and security settings from your development computer. Otherwise, the add-in will continue to run every time that you open Word on your development computer.

To clean up the completed project on your development computer

In Visual Studio, on the Build menu, click Clean Solution.

Next Steps

Now that you have created a basic application-level add-in for Word, you can learn more about how to develop add-ins from these topics:

General programming tasks that you can perform in add-ins: Programming Application-Level Add-Ins.
Programming tasks that are specific to Word add-ins: Word Solutions.
Using the object model of Word: Word Object Model Overview.
Customizing the UI of Word, for example, by adding a custom tab to the Ribbon or creating your own custom task pane: Office UI Customization.
Building and debugging application-level add-ins for Word: Building Office Solutions.
Deploying application-level add-ins for Word: Deploying an Office Solution.