第 58 页

assembly. Document-level customizations can also be included with an Office template, which

ensures that the customization is included when you create a new document from that template.

Visual Studio 2010 allows you to create document-level customizations for the following types of

documents:

.

Microsoft Excel Workbook

.

Microsoft Excel Template

.

Microsoft Word Document

.

Microsoft Word Template

Using a document-level customization, you can modify the user interface of Word or Excel to

provide a unique solution for your end users. For example, you can add new controls to the Office

Ribbon or display a customized Actions Pane window.

Microsoft Word and Microsoft Excel also include a technology called smart tags, which enable

developers to track the user’s input and recognize when text in a specific format has been entered.

Your solution can use this technology by providing feedback or even actions that the user could take

in response to certain recognized terms, such as a phone number or address.

Visual Studio also includes a set of custom controls that are specific to Microsoft Word. Called

content controls, they are optimized for both data entry and print. You see content controls in

action later in this chapter.

application-level add-ins

Unlike a document-level customization, an application-level add-in is always loaded regardless of

the document that is currently open. In fact, application-level add-ins will run even if the application

is running with no documents open.

Earlier versions of VSTO had significant limitations when it came to application-level add-ins.

For example, you could only create add-ins for Microsoft Outlook, and even then you could not

customize much of the user interface.

Fortunately, in Visual Studio 2010 such restrictions do not exist, and you can create application-level

add-ins for almost every product in the Microsoft Office suite, including Excel, InfoPath, Outlook,

PowerPoint, Project, Visio, and Word. This applies equally to version 2007 and version 2010 of

Office. You can create the same UI enhancements as you can with a document-level customization,

such as adding new controls to the Office Ribbon.

You can also create a custom Task Pane as part of your add-in. Task Panes are very similar to the

Action Panes that are available in document-level customization projects. However, custom Task

Panes are associated with the application, not a specific document, and as such can be created only

within an application-level add-in.

382 . chaPter 19 oFFice buSineSS ApplicATionS

An Actions Pane, on the other hand, is a specifi c type of Task Pane that is customizable and is

attached to a specifi c Word document or Excel workbook. You cannot create an Actions Pane in an

application - level add - in.

Also included in Visual Studio 2010 is the ability to create custom Outlook form regions in Outlook

add - in projects. Form regions are the screens that are displayed when an Outlook item is opened,

such as a Contact or Appointment. You can either extend the existing form regions or create a

completely custom Outlook form. Later in this chapter you walk through the creation of an Outlook

2010 add - in that includes a custom Outlook form region.

creatinG a docuMent - leVel custoMization

This section walks through the creation of a Word document customization. This demonstrates how to

create a document - level customization complete with Word Content Controls and a custom Actions Pane.

This example uses the Employee warning notice that is available under the Forms, Employment

category. When you download a template from the Offi ce Online web site using Internet Explorer,

you are prompted to save it to the default templates location. Once saved, Microsoft Word then

opens with a new document based on the template. Save this new document to a convenient folder

on your computer as a Word Template in the Open XML format ( .dotx ), as shown in Figure 19 - 2 .

The example in this section uses Word 2010, which you must have installed

locally in order to debug the project. If you only have Word 2007 installed, you

can still follow the instructions and create a document - level customization using

the Word 2007 project template. Any differences between Word 2010 and Word

2007 have been noted in the instructions.

your first Vsto Project

When you create a document - level customization with Visual Studio 2010, you can either create the

document from scratch or jump - start the design by using an existing document or template. A great

source of templates, particularly for business - related forms, is the free templates available from

Microsoft Offi ce Online at http://office.microsoft.com/templates/ .

All of the templates available for download from the Offi ce Online web site

are provided in the older Word 97 - 2003 format ( .dot ). Unfortunately, some

features, such as the Word Content Controls, are only available for documents

that are saved with the newer Open XML format ( .dotx ). Therefore, you will

need to ensure that the template is in the latest format if you wish to use all the

available features.

Creating a Document-level Customization .

383

fiGure 19-2

Next, launch Visual Studio 2010 and select File . New . Project. Filter the project types by

selecting your preferred language (C# or Visual Basic) followed by Office, and then choose a new

Word 2010 Template. You are presented with a screen that prompts you to create a new document

or copy an existing one. Select the option to copy an existing document and then navigate to and

select the document template you saved earlier. When you click OK, the project is created and the

document opens in the Designer as shown in Figure 19-3.

fiGure 19-3

384 .

chaPter 19 oFFice buSineSS ApplicATionS

VSTO requires access to Visual Basic for Applications (VBA) even though

the projects do not use VBA. Therefore, the first time you create an Office

application you are prompted to enable access to VBA. You must grant this

access even if you work exclusively in C#.

A few things are worth pointing out in Figure 19 - 3 . First, you ’ ll notice that along the top of the

Designer is the Office Ribbon. This is the very same Ribbon that is displayed in Word, and you can use

it to modify the layout and design of the Word document. Second, in the Solution Explorer to the right,

the file that is currently open is called ThisDocument.cs (or ThisDocument.vb if you are using Visual

Basic). You can right - click this file and select either View Designer to display the design surface for the

document, currently shown in Figure 19 - 3 , or View Code to open the source code behind this document

in the code editor. Finally, in the Toolbox to the left, there is a tab group called Word Controls, which

contains a set of controls that allow you to build rich user interfaces for data input and display.

To customize this form, first drag four PlainTextContentControl controls onto the design surface for

the Employee Name, Employee ID, Job Title, and Manager. Rename these controls to txtEmpName,

txtEmpID, txtJobTitle, and txtManager, respectively.

Next, drag a DatePickerContentControl for the Date field, and rename it to be dtDate. Then drag a

DropDownListContentControl next to the Department field, and rename it ddDept.

Following this, drag a RichTextContentControl into the Details section of the document, and place

it under the Description of Infraction label.

Finally, to clean up the document a little, remove

the sections titled Type of Warning and Type

of Offense, and all of the text that is below the

RichTextContentControl you added. Once you

have done this, your form should look similar to

what is shown in Figure 19-4.

Before you run this project you will need to

populate the Department drop - down list.

Although you can do this declaratively via the

Properties fi eld, for this exercise you will perform

it programmatically. Right - click the ThisDocument

fi le in the Solution Explorer and select View Code

to display the managed code that is behind this

document. Two methods will be predefi ned: a function that is run during startup when the document

is opened, and a function that is run during shutdown when the document is closed.

Add the following code for the ThisDocument_Startup method to populate the Department

drop - down list:

c#

private void ThisDocument_Startup(object sender, System.EventArgs e)

{

ddDept.PlaceholderText = "Select your department";

ddDept.DropDownListEntries.Add("Finance", "Finance", 0);

fiGure 19-4

Creating a Document-level Customization .

385

ddDept.DropDownListEntries.Add("HR", "HR", 1);

ddDept.DropDownListEntries.Add("IT", "IT", 2);

ddDept.DropDownListEntries.Add("Marketing", "Marketing", 3);

ddDept.DropDownListEntries.Add("Operations", "Operations", 4);

}

Code Snippet ThisDocument.cs

Vb

Private Sub ThisDocument_Startup() Handles Me.Startup

ddDept.PlaceholderText = "Select your department"

ddDept.DropDownListEntries.Add("Finance", "Finance", 0)

ddDept.DropDownListEntries.Add("HR", "HR", 1)

ddDept.DropDownListEntries.Add("IT", "IT", 2)

ddDept.DropDownListEntries.Add("Marketing", "Marketing", 3)

ddDept.DropDownListEntries.Add("Operations", "Operations", 4)

End Sub

Code Snippet ThisDocument.vb

You can now run the project in Debug mode by pressing F5. This compiles the project and opens the

document in Microsoft Word. You can test out entering data in the various fields to obtain a feel for

how they behave.

Protecting the document design

While you have the document open you may notice that in addition to entering text in the control

fields that you added, you can also edit the surrounding text and even delete some of the controls.

This is obviously not ideal in this scenario. Fortunately, Office and VSTO provide a way to prevent

the document from undesirable editing. For this, you will need to show the Developer tab.

For Word 2010, click the File tab and then click the Options button. In the Word Options dialog

window, select Customize Ribbon and then check the box next to Developer under the Main

Tabs list.

For Word 2007, click the Office button and then click the Word Options button on the bottom of the

screen. In the Word Options dialog window, check the box next to the Show Developer Tab in the

Ribbon option.

When you stop debugging and return to Visual Studio, you will see a new tab on the toolbar above

the Ribbon, as shown in Figure 19-5. This provides some useful functions for Office development-

related tasks.

fiGure 19-5

386 .

chaPter 19 oFFice buSineSS ApplicATionS

To prevent the document from being edited, you must perform a couple of steps. First, ensure that

the Designer is open and then press Ctrl+A to select everything in the document (text and controls).

On the Developer tab click Group . Group. This allows you to treat everything on the document as

a single entity, and easily apply properties to all elements in one step.

With this new group selected, open the Properties window and set the LockContentControl property

to True. Now when you run the project you will find that the standard text on the document cannot

be edited or deleted, and you can only input data into the content controls that you have added.

adding an actions Pane

The fi nal customization you will add to this document is an Actions Pane window. An Actions Pane is

typically docked to one side of a window in Word, and can be used to display related information or

provide access to additional information. For example, on an employee leave request form you could

add an Actions Pane that retrieved and displayed the current employees ’ available leave balance.

An Actions Pane, or custom Task Pane in the case of application - level add - ins, is

nothing more than a standard user control. In the case of an Actions Pane, Visual

Studio has included an item template; under the covers, however, this does little

more than add a standard user control to the project with the Offi ce namespace

imported. For application - level add - ins there is no custom Task Panes item

template, so you can simply add a standard user control to the project.

To add an Actions Pane to this document customization, right-click the project in the Solution

Explorer and select Add . New Item. Select Actions Pane Control, provide it with a meaningful

name, and click Add. The Actions Pane will open in a new designer window. You are simply going

to add a button that retrieves the username of the current user and adds it to the document. Drag a

button control onto the form and rename it btnGetName. Then double-click the control to register

an event handler and add the following code for the button click event:

c#

private void btnGetName_Click(object sender, EventArgs e)

{

var myIdent = System.Security.Principal.WindowsIdentity.GetCurrent();

Globals.ThisDocument.txtEmpName.Text = myIdent.Name;

}

Code Snippet GetUserName.cs

Vb

Private Sub btnGetName_Click(ByVal sender As System.Object, _

ByVal e As System.EventArgs) _

Handles btnGetName.Click

Creating a Document-level Customization .

387

Dim myIdent = System.Security.Principal.WindowsIdentity.GetCurrent()

Globals.ThisDocument.txtEmpName.Text = myIdent.Name

End Sub

Code Snippet GetUserName.vb

The Actions Pane components are not added automatically to the document because you may want

to show different Actions Panes, depending on the context users find themselves in when editing

the document. However, if you have a single Actions Pane component and simply want to add it

immediately when the document is opened, add the component to the ActionsPane.Controls

collection of the document at startup, as demonstrated in the following code: