|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Word Object Model Overview
To develop solutions that use Microsoft Office Word, you can interact with the objects provided by the Word object model. Word objects are arranged in a hierarchical order, and the two main classes at the top of the hierarchy are theand classes. These two classes are important because most of the time you either work with the Word application itself, or manipulate Word documents in some way.
The Word object model closely follows the user interface. The Application object represents the entire application, each Document object represents a single Word document, theobject corresponds to a single paragraph, and so on. Each of these objects has many methods and properties that allow you to manipulate and interact with it.
Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO 2005) extends many of these native objects into host items and host controls that can be used in document-level customizations. These controls have additional functionality such as data-binding capabilities and events. For example, a native Wordobject is extended into a control, which can be bound to data and exposes events. For more information about host items and host controls, see .
For complete information about the Word 2003 object model, see the Visual Basic for Applications (VBA) documentation that is installed with Word or see "Welcome to the Microsoft Office Word 2003 VBA Language Reference" (http://go.microsoft.com/fwlink/?linkid=27950). For complete information about the Word 2007 object model, see the VBA documentation that is installed with Word or see the 2007 Microsoft Office system developer content on the MSDN Web site (http://go.microsoft.com/fwlink/?LinkId=72870).
Accessing Objects in a Word Project
When you create a new application-level project for Word by using Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE), Visual Studio automatically creates a
ThisAddIn.cs code file. You can access the Application object by using
When you create a new document-level project for Word by using VSTO 2005, you have the option of creating a new Word Application or Word Template project. VSTO 2005 automatically creates a
ThisDocument.cs code file in your new Word project for both Document and Template projects. You can access the Application and Document objects by using the Me or this object reference.
At first glance, there appears to be a lot of overlap in the Word object model. For example, the Document andobjects are both members of the Application object, but the Document object is also a member of the Selection object. Both the Document and Selection objects contain Bookmark and objects. The overlap exists because there are multiple ways you can access the same type of object. For example, you apply formatting to a Range object; but you may want to access the range of the current selection, a particular paragraph, section or the entire document.
The Application object contains the Document, Selection, Bookmark, and Range objects.
Word provides hundreds of objects with which you can interact. The following sections briefly describe the top-level objects and how they interact with each other. These include:
The Application object represents the Word application, and is the parent of all of the other objects. Its members usually apply to Word as a whole. You can use its properties and methods to control the Word environment.
The Microsoft.Office.Interop.Word.Document object is central to programming Word. When you open a document or create a new document, you create a new Microsoft.Office.Interop.Word.Document object, which is added to thecollection in Word. The document that has the focus is called the active document and is represented by the property of the Application object.
Visual Studio Tools for Office extends the Microsoft.Office.Interop.Word.Document object by providing the
ThisDocument class, you can access members of
ThisDocument with the Me or this object reference. For example, to select the first paragraph in the document, use the following code:
The Selection object represents the area that is currently selected. When you perform an operation in the Word user interface, such as bolding text, you select, or highlight, the text and then apply the formatting. The Selection object is always present in a document. If nothing is selected, then it represents the insertion point. In addition, it can also be multiple blocks of text that are not contiguous.
The Range object represents a contiguous area in a document, and is defined by a starting character position and an ending character position. You are not limited to a single Range object. You can define multiple Range objects in the same document. A Range object has the following characteristics:
It can consist of the insertion point alone, a range of text, or the entire document.
It includes non-printing characters such as spaces, tab characters, and paragraph marks.
It can be the area represented by the current selection, or it can represent a different area than the current selection.
It is not visible in a document, unlike a selection which is always visible.
It is not saved with a document and exists only while the code is running.
When you insert text at the end of a range, Word automatically expands the range to include the inserted text.
A Microsoft.Office.Interop.Word.Bookmark in a document is similar to a text box control on a Windows Form in that it is the easiest way to control text within a document. The Microsoft.Office.Interop.Word.Bookmark object represents a contiguous area in a document, with both a starting position and an ending position. You can use bookmarks to mark a location in a document, or as a container for text in a document. A Microsoft.Office.Interop.Word.Bookmark object can consist of the insertion point, or be as large as the entire document. A Microsoft.Office.Interop.Word.Bookmark has the following characteristics that set it apart from the Range object:
You can name the bookmark at design-time.
Microsoft.Office.Interop.Word.Bookmark objects are saved with the document, and thus do not get deleted when the code stops running or your document is closed.
Bookmarks can be hidden or made visible by setting theproperty of the object to True or False.
Visual Studio Tools for Office extends the Bookmark object into a host control. The Microsoft.Office.Tools.Word.Bookmark control behaves like a native Microsoft.Office.Interop.Word.Bookmark, but has additional events and data-binding capabilities. You can now bind data to a bookmark control on a document in the same way that you bind data to a text box control on a Windows Form. For more information, see.
T:Microsoft.Office.Tools.Word.Bookmark controls that are added to a document programmatically at run time do not get persisted with the document. Only the underlying Microsoft.Office.Interop.Word.Bookmark object is saved. For more information, see.
Extended Objects in Document-Level Projects
It is important to understand the differences between the native objects provided by the Word object model and the extended objects (host items and host controls) provided by VSTO 2005, because both types of objects are available to document-level projects. For more information, see.
Design time. When you add any of the extended Word objects at design time, they are automatically created as host items and host controls. For example, if you add a bookmark to a document in the Designer, code is automatically generated to extend the bookmark into a Microsoft.Office.Tools.Word.Bookmark control.
Run time. Host items are not automatically created at run time. If you add documents at run time using themethod, they are Microsoft.Office.Interop.Word.Document objects and do not have the additional capabilities that Microsoft.Office.Tools.Word.Document host items provide. You can programmatically add Microsoft.Office.Tools.Word.Bookmark controls to your document using the helper methods provided by VSTO 2005. For more information, see .
Data binding and events. Host items and host controls have data-binding capabilities and events, which are not available to the native objects.
Types. The native Word objects use the types defined in thenamespace, whereas host items and host controls use the aggregated types defined in the namespace.