Walkthrough: Create your first document-level customization for Word

This introductory walkthrough shows you how to create a document-level customization for Microsoft Office Word. The features that you create in this kind of solution are available only when a specific document is open. You cannot use a document-level customization to make application-wide changes, for example, displaying a new Ribbon tab when any document is open.

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

This walkthrough illustrates the following tasks:

• Creating a Word document project.

• Adding text to the document that is hosted in the Visual Studio designer.

• Writing code that uses the object model of Word to add text to the customized document when it is opened.

• Building and running the project to test it.

• Cleaning up the project to remove unnecessary build files and security settings from 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 Personalize the IDE.

Prerequisites

You need the following components to complete this walkthrough:

• An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configure a computer to develop Office solutions.

• Microsoft Word

Create the project

To create a new Word document project in Visual Studio

1. Start Visual Studio.

2. On the File menu, point to New, and then click Project.

3. On the Create a New Project dialog select the Word VSTO Document project.

   Note

   You can also search for templates by typing the name of the Office product in the Search text box at the top of the Create a New Project dialog. For example, typing Excel will show you all of the project templates for Excel. You can also filter the list of templates to show only the templates for Office by selecting Office in the Project type dropdown box. For more information see Create a new project in Visual Studio.

4. Click Next.

5. Type FirstWorkbookCustomization in the Name box on the Configure your new project dialog and click Create.

6. Select Create a new document from the Visual Studio Tools for Office Project Wizard, and click OK.

   • Visual Studio creates the FirstDocumentCustomization project, and adds the FirstDocumentCustomization document and ThisDocument code file to the project. The FirstDocumentCustomization document is opened automatically in the designer.

Close and reopen the document in the designer

If you deliberately or accidentally close the document in the designer while you are developing your project, you can reopen it.

To close and reopen the document in the designer

1. Close the document by clicking the Close button (X) for the designer window.

2. In Solution Explorer, right-click the ThisDocument code file, and click View Designer.

   - or -

   In Solution Explorer, double-click the ThisDocument code file.

Add text to the document in the designer

You can design the user interface (UI) of your customization by modifying the document that is open in the designer. For example, you can add text, tables, or Word controls. For more information about how to use the designer, see Office projects in the Visual Studio environment.

To add text to your document by using the designer

1. In the document that is open in the designer, type the following text.

   This text was added by using the designer.

Add text to the document programmatically

Next, add code to the ThisDocument code file. The new code uses the object model of Word to add a second paragraph of text to the document. By default, the ThisDocument code file contains the following generated code:

• A partial definition of the ThisDocument class, which represents the programming model of the document and provides access to the object model of Word. For more information, see Document host item and Word object model overview. The remainder of the ThisDocument class is defined in a hidden code file that you should not modify.

• The ThisDocument_Startup and ThisDocument_Shutdown event handlers. These event handlers are called when the document is opened and closed. Use these event handlers to initialize your customization when the document is opened, and to clean up resources used by your customization when the document is closed. For more information, see Events in Office projects.

To add a second paragraph of text to the document by using code

1. In Solution Explorer, right-click ThisDocument, and then click View Code.

   The code file opens in Visual Studio.

2. Replace the ThisDocument_Startup event handler with the following code. When the document is opened, this code adds a second paragraph of text to the document.

   C#

   private void ThisDocument_Startup(object sender, System.EventArgs e)
   {
       this.Paragraphs[1].Range.InsertParagraphAfter();
       this.Paragraphs[2].Range.Text = "This text was added by using code.";
   }
   

   VB

   Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
       Me.Paragraphs(1).Range.InsertParagraphAfter()
       Me.Paragraphs(2).Range.Text = "This text was added by using code."
   End Sub
   

   Note

   This code uses the index value 1 to access the first paragraph in the Paragraphs property. 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 Write code in Office solutions.

Test the project

To test your document

1. Press F5 to build and run your project.

   When you build the project, the code is compiled into an assembly that is associated with the document. Visual Studio puts a copy of the document and the assembly in the build output folder for the project, and it configures the security settings on the development computer to enable the customization to run. For more information, see Build Office solutions.

2. In the document, verify that you see the following text.

   This text was added by using the designer.

   This text was added by using code.

3. Close the document.

Clean up the project

When you finish developing a project, you should remove the files in the build output folder and the security settings created by the build process.

To clean up the completed project on your development computer

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

Next steps

Now that you have created a basic document-level customization for Word, you can learn more about how to develop customizations from these topics:

• General programming tasks that you can perform in document-level customizations: Program document-level customizations.

• Programming tasks that are specific to document-level customizations for Word: 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 actions pane: Office UI customization.

• Using extended Word objects provided by Office solutions in Visual Studio to perform tasks that are not possible by using the Word object model (for example, hosting managed controls on documents and binding Word controls to data by using the Windows Forms data binding model): Automate Word by using extended objects.

• Building and debugging document-level customizations for Word: Build Office solutions.

• Deploying document-level customizations for Word: Deploy an Office solution.

Related content

• Office solutions development overview (VSTO)
• Word solutions
• Program document-level customizations
• Word object model overview
• Automate Word by using extended objects
• Office UI customization
• Build Office solutions
• Deploy an Office solution
• Office project templates overview