Introduction to Office Solutions Using Visual Studio Tools for Office
- The Three Basic Patterns of Office Solutions
- Office Automation Executables
- Office Add-Ins
- Code behind a Document
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
The Three Basic Patterns of Office Solutions
Now that we have considered the basic pattern of the Office object models, let us consider how developers pattern and build their Office solutions. There are three patterns that most solutions built using Office follow.
- Office automation executable
- Office add-in
- Code behind an Office document
An automation executable is a program separate from Office that controls and automates an Office application. An automation executable can be created with development tools such as Visual Studio .NET 2005. A typical example is a stand-alone console application or Windows Forms application that starts up an Office application and then automates it to perform some task. To start a solution built this way, the user of the solution starts the automation executable that will in turn start up the Office application. Unlike the other two patterns, the automation code does not run in the Office process but runs in its own process and talks cross process to the Office process being automated.
An add-in is a class in an assembly (DLL) that Office loads and creates when needed. An add-in runs in process with the Office application rather than requiring that a separate process from the Office application is running. To start a solution built this way, the user of the solution starts the Office application associated with the add-in. Office detects registered add-ins on startup and loads them. An add-in can customize an Office application in the same ways that code behind a document can. However, code behind a document unloads when the document associated with the code is closed—an add-in can remain loaded throughout the lifetime of the Office application.
The code behind pattern was popularized by Visual Basic for Applications (VBA)—a simple development environment that is included with Office that allows the developer to write Visual Basic code against the object model of a particular Office application and associate that code with a particular document or template. A document can be associated with C# or VB.NET code behind using Visual Studio Tools for Office 2005. To start a solution built this way, the user of the solution opens a document that has code behind it or creates a new document from a template that has code behind it. The code behind the document will customize the Office application in some way while the document is open. For example, code behind the document might add menu items that are only present when the document is open or associate code with events that occur while the document is open.
We will discuss an additional pattern later in this book. The server document pattern involves running code on a server to manipulate data stored in an Office document without starting the Office application. VSTO makes this scenario possible through a feature called cached data. We will discuss this pattern in Chapter 18.
Hosted Code
The add-in and code behind patterns are sometimes called hosted code which means that your code runs in the same process as the Office application.
Discovery of Hosted Code
In order for code to run in the Office application process, the Office application must be able to discover your code, load the code into its process space, and run your code. Office add-ins are registered in the registry so Office can find and start them. Using the registry seems a little non-.NET but this is necessary because Office 2003 talks to add-ins as if they were COM objects through COM interop.
The code behind a document pattern does not require a registry entry. Instead, code is associated with a document by adding some special properties to the document file. Office reads these properties when the document opens then Office loads the code associated with the document.
Context Provided to Hosted Code
It is critical that your hosted code get context—it needs to get the Application object or Document object for the Office application into which it is loading. COM add-ins are provided with context through an interface implemented by the add-in class. Outlook add-ins in VSTO are provided with context through a class created in the project that represents the application being customized. Code behind a document in VSTO is provided with context through a class created in the project that represents the document being customized.
Entry Point for Hosted Code
At startup, Office calls into an entry point where your code can run for the first time and register for events that may occur later in the session. For a COM add-in, this entry point is the OnConnection method of the IDTExtensibility2 interface implemented by the COM add-in. For a VSTO Outlook add-in and VSTO code behind a document this entry point is the Startup event handler.
How Code Gets Run After Startup
Once hosted code starts up, code continues to run in one or more of the following ways.
Code Runs In Response to Events Fired By Office
The most common way that code runs after startup is in response to events that occur in the Office application. For example, Office raises events when a document opens or a cell in a spreadsheet changes. Listing 1-26 shows a simple class that listens to the change event that Excel's Worksheet object raises. Typically, you will hook up event listeners like the one shown in Listing 1-26 when the initial entry point of your code is called.
Interface Methods Called On Objects Provided To Office
Objects such as the startup class for a COM add-in implement an interface called IDTExtensibility2 that has methods that Office calls during the run of the Office application. For example, if the user turns off the COM add-in, Office calls the OnDisconnection method on the IDTExtensibility2 interface implemented by the COM add-in. In this way, additional code runs after the initial entry point has run.
Events Raised on Code Behind Classes
The classes generated in VSTO projects that represent the customized application or document handle the Startup and Shutdown events. After the constructor of the class executes, Office raises the Startup event. When the document is about to be closed, Office raises the Shutdown event.
How Code Gets Unloaded
Your code gets unloaded in a number of ways, depending on the development pattern you are using. If you are using the automation executable pattern, your code unloads when the automation executable you have written exits. If you are using the add-in pattern, your code unloads when the Office application exits or when the user turns off the add-in via an add-in management dialog. If you are using the code behind pattern, your code unloads when the document associated with your code is closed.
In the hosted patterns of running code there is some method that is called or event that is raised notifying you that you are about to be unloaded. For COM add-ins, Office calls the OnDisconnection method. For VSTO code behind documents and Outlook add-ins, Office raises the Shutdown event before your code is unloaded.