Word has a very rich object model that consists of 248 objects that combined have more than 4,200 properties and methods. Word also supports several models for integrating your code, including add-ins and code behind documents. Most of these models were originally designed to allow the integration of COM components written in VB 6, VBA, C, or C++. However, through COM interop, managed objects written in C# or Visual Basic can masquerade as COM objects and participate in most of these models. This chapter briefly considers several of the ways that you can integrate your code with Word and refers you to other chapters that discuss these approaches in more depth. This chapter also explores building research services and introduces the Word object model.
As mentioned in Chapter 2, "Introduction to Office Solutions," the simplest way to integrate with Word is to start Word from a console application or Windows Forms application and automate it from that external program. Chapter 2 provides a sample of an automation executable that automates Word.
Word can load add-insin particular COM add-ins. A COM add-in is a DLL that contains a class that implements IDExtensibility2. The class that implements IDExtensibility2 must be registered in the registry so that it looks like a COM object to Word. A COM add-in is typically written to add application-level functionalityfunctionality that is available to any document opened by Word.
Word has a COM Add-Ins dialog box that enables users to turn COM add-ins on and off. To access the COM Add-Ins dialog, you must perform the following steps:
Right-click a menu or toolbar in Word and choose Customize from the pop-up menu, or from the Tools menu choose Customize to display the Customize dialog box.
Click the Commands tab of the Customize dialog.
Choose Tools from the list of Categories.
Scroll down the list of commands until you see a command that says COM Add-Ins.
Drag the COM Add-Ins command and drop it on a toolbar.
Close the Customize dialog box.
After you have completed these steps, click the COM Add-Ins toolbar button you added to a toolbar. Figure 6-1 shows the COM Add-Ins dialog.
Figure 6-1. The COM Add-Ins dialog box in Word.
You can add COM add-ins by using the Add button and remove them by using the Remove button. Typically, you will not have your users use this dialog to manage COM add-ins. Instead, you will install and remove a COM add-in by manipulating registry settings with the installer you create for your COM add-in.
Word discovers the installed COM add-ins by reading from the registry. You can view the registry on your computer by going to the Windows Start menu and choosing Run. In the Run dialog box, type regedit for the program to run, and then click the OK button. Word looks for COM add-ins in the registry keys under HKEY_CURRENT_USERSoftwareMicrosoftOfficeWordAddins. Word also looks for COM add-ins in the registry keys under HKEY_LOCAL_MACHINE SoftwareMicrosoftOfficeWordAddins. COM add-ins registered under HKEY_LOCAL_MACHINE are not shown in the COM Add-Ins dialog box and cannot be turned on or off by users. It is recommended you do not register your COM add-in under HKEY_LOCAL_MACHINE because it hides the COM add-in from the user.
COM add-ins are discussed in detail in Chapter 23, "Developing COM Add-Ins for Word and Excel."
Visual Studio Tools for Office Code Behind
Visual Studio 2005 Tools for Office (VSTO) enables you to put C# or Visual Basic code behind Word templates and documents. VSTO was designed from the ground up for C# and Visual Basicso this model is the most ".NET" of all the models used to customize Word. This model is used when you want to customize the behavior of a particular document or a particular set of documents created from a common template. For example, you might want to create a template that is used whenever anyone in your company creates an invoice. This template can add commands and functionality that are always available when the document created with it is opened.
Note that Word templates in VSTO do not behave in the same way that templates behave in VBA. In VBA, both the code associated with the template and the code associated with the document run concurrently. In VSTO, the code associated with the template is associated with the document when a new document is created, and only the code associated with the document runs.
VSTO's support for code behind a document is discussed in detail in Part Three of this book.
Smart Documents and XML Expansion Packs
Smart documents are another way to associate your code with a Word template or document. Smart documents rely on attaching an XML schema to a document or template and associating your code with that schema. The combination of the schema and associated code is called an XML Expansion Pack. An XML Expansion Pack can be associated with a Word document by choosing Templates and Add-Ins from the Tools menu and clicking the XML Expansion Packs tab. Figure 6-2 shows the Templates and Add-Ins dialog.
Figure 6-2. The XML Expansion Packs tab of the Templates and Add-Ins dialog.
When an XML Expansion Pack is attached to a document, Word loads the associated code and runs it while that document is opened. Smart document solutions can create a custom user interface in the Document Actions task pane that can be brought up in Word by choosing Task Pane from the View menu.
It is possible to write smart document solutions from scratch in C# or Visual Basic. This book does not cover this approach. Instead, this book focuses on the VSTO approach, which was designed to make smart document development much easier and allow you to create a custom Document Actions task pane using Windows Forms. Chapter 15, "Working with Actions Pane," discusses this capability in more detail.
Smart Tags enable a pop-up menu to be displayed containing actions relevant for a recognized piece of text in a document. You can control the text that Word recognizes and the actions that are made available for that text by creating a Smart Tag DLL or by using VSTO code behind a document.
A Smart Tag DLL contains two types of components that are used by Word: a recognizer and associated actions. A recognizer determines what text in the document is recognized as a Smart Tag. An action corresponds to a menu command displayed in the pop-up menu.
A recognizer could be created that tells Word to recognize stock-ticker symbols (such as the MSFT stock symbol) and display a set of actions that can be taken for that symbol: buy, sell, get the latest price, get history, and so on. A "get history" action, for instance, could launch a Web browser to show a stock history Web page for the stock symbol that was recognized.
When a recognizer recognizes some text, Word displays red-dotted underlining under the recognized text, as shown in Figure 6-3. If the user hovers over the text, a pop-up menu icon appears next to the text that the user can click to drop down a menu of actions for the recognized piece of text. Figure 6-4 shows an example menu. When an action is selected, Word calls back into the associated action to execute your code.
Figure 6-3. Some recognized text.
Figure 6-4. Dropping down the Smart Tag menu.
Smart Tags are managed from the Smart Tags page of the AutoCorrect dialog shown in Figure 6-5. To display the Smart Tags page, you choose the AutoCorrect Options from the Tools menu. Here the user can turn on and off individual recognizers as well as control other options relating to how Smart Tags display in the document.
Figure 6-5. The Smart Tags page in the AutoCorrect dialog.
VSTO provides a simple model for creating a Smart Tag that works at the workbook or template level. Chapter 16, "Working with Smart Tags in VSTO," describes the VSTO model for working with Smart Tags in more detail.
It is possible to write Smart Tag recognizer and action classes in a DLL that works at the application level, but it is much more complex than the VSTO model. Chapter 16 also describes that approach.
VSTO enables you to write code on the server that populates a Word document with data without starting Word on the server. For example, you might create an ASP.NET page that reads some data out of a database and then puts it in a Word document and returns that document to the client of the Web page. VSTO provides a class called ServerDocument that makes it easy to do this. Chapter 18, "Server Data Scenarios," describes generating documents on the server using the ServerDocument class.
You can also use the XML file formats of Office to generate Word documents in XML formats on the server, but this is much more complex. Chapter 22, "Working with XML in Word," discusses VSTO support for this scenario.
Part One. An Introduction to VSTO
An Introduction to Office Programming
Introduction to Office Solutions
Part Two. Office Programming in .NET
Working with Excel Events
Working with Excel Objects
Working with Word Events
Working with Word Objects
Working with Outlook Events
Working with Outlook Objects
Introduction to InfoPath
Part Three. Office Programming in VSTO
The VSTO Programming Model
Using Windows Forms in VSTO
Working with Actions Pane
Working with Smart Tags in VSTO
VSTO Data Programming
Server Data Scenarios
.NET Code Security
Part Four. Advanced Office Programming
Working with XML in Excel
Working with XML in Word
Developing COM Add-Ins for Word and Excel
Creating Outlook Add-Ins with VSTO