第 59 页

c#

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

{

this.ActionsPane.Controls.Add(new NameOfActionsPaneControl());

}

Code Snippet ThisDocument.cs

Vb

Private Sub ThisDocument_Startup() Handles Me.Startup

Me.ActionsPane.Controls.Add(new NameOfActionsPaneControl())

End Sub

Code Snippet ThisDocument.vb

For application-level add-ins, add the user control to the CustomTaskPanes collection.

The next time you run the project, it will display the document in Word with the Actions Pane

window shown during startup, as shown in Figure 19-6.

fiGure 19-6

388 .

chaPter 19 oFFice buSineSS ApplicATionS

creatinG an aPPlication add-in

This section walks through the creation of an add-in to Microsoft Outlook 2010. This will

demonstrate how to create an application-level add-in that includes a custom Outlook form region

for a Contact item.

Never develop Outlook add-ins using your production e-mail account! There’s

too much risk that you will accidentally do something that you will regret later,

such as deleting all of the e-mail in your Inbox. With Outlook, you can create

a separate mail profile; one for your normal mailbox and one for your test

mailbox.

some outlook concepts

Before creating an Outlook add-in, it is worth understanding some basic concepts that are specific

to Outlook development. Though there is a reasonable degree of overlap, Outlook has always had a

slightly different programming model from the rest of the products in the Office suite.

The Outlook object model is a heavily collection-based API. The Application class is the highest-

level class and represents the Outlook application. This can be directly accessed from code as a

property of the add-in; this.Application in C# or Me.Application in Visual Basic. With the

Application class you can access classes that represent the Explorer and Inspector windows.

An Explorer window in Outlook is the main window that is displayed when Outlook is first opened

and displays the contents of a folder, such as the Inbox or Calendar. Figure 19-7 (left) shows

the Calendar in the Explorer window. The Explorer class represents this window, and includes

properties, methods, and events that can be used to access the window and respond to actions.

fiGure 19-7

Creating an application add-in .

389

An Inspector window displays an individual item such as an e-mail message, contact, or

appointment. Figure 19-7 (right) shows an Inspector window displaying an appointment item. The

Inspector class includes properties and methods to access the window, and events that can be

handled when certain actions occur within the window. Outlook form regions are hosted within

Inspector windows.

The Application class also contains a Session object, which represents everything to do with the

current Outlook session. This object provides you with access to the available address lists, mail

stores, folders, items, and other Outlook objects. A mail folder, such as the Inbox or Calendar,

is represented by a MAPIFolder class and contains a collection of items. Within Outlook, every

item has a message class property that determines how it is presented within the application. For

example, an e-mail message has a message class of IPM.Note and an appointment has a message

class of IPM.Appointment.

creating an outlook form region

Now that you understand the basics of the Outlook object model, you can create your first Outlook

add-in. In Visual Studio 2010, select File . New . Project. Filter the project types by selecting

Visual C# followed by Office, and then choose a new Outlook 2010 Add-in project.

If you only have Outlook 2007 installed, select the Outlook 2010 Add-In

project instead.

Unlike a document-level customization, an application-level add-in is inherently code-based. In the

case of a Word or Excel add-in, there may not even be a document open when the application is first

launched. An Outlook add-in follows a similar philosophy; when you first create an Outlook add-in

project, it will consist of a single nonvisual class called ThisAddIn.cs (or ThisAddIn.vb). You can

add code here that performs some actions during startup or shutdown.

To customize the actual user interface of Outlook you can add an Outlook form region. This is a

user control that is hosted in an Outlook Inspector window when an item of a certain message class

is displayed.

To add a new Outlook form region, right-click the project in the Solution Explorer and select

Add . New Item. From the list of available items select Outlook Form Region, provide it with a

meaningful name, and click Add. Visual Studio then opens the New Outlook Form Region Wizard

that will obtain some basic properties needed to create the new item.

The first step of the wizard asks you to either design a new form or import an Outlook Form

Storage (.ofs) file, which is a form designed in Outlook. Select Design a New Form Region and

click Next.

390 .

chaPter 19 oFFice buSineSS ApplicATionS

The second step in the wizard allows you to select

what type of form region to create. The wizard

provides a handy visual representation of each type

of form region, as shown in Figure 19-8. Select the

Separate option and click Next.

The next step in the wizard allows you to enter a

friendly name for the form region, and, depending

on the type of form region you’ve chosen, a title and

description. This step also allows you to choose the

display mode for the form region. Compose mode is

displayed when an item is first being created, such as

when you create a new e-mail message. Read mode

is displayed when you subsequently open an e-mail

message that has already been sent or received.

Ensure that both of these checkboxes are ticked,

enter Custom Details as the name, and click Next.

The final step in the wizard allows you to choose

what message classes will display the form region.

You can select from any of the standard message

classes, such as mail message or appointment, or

specify a custom message class. Select the Contact

message class as shown in Figure 19-9 and click

Finish to close the wizard.

Once the wizard exits, the new form region will be

created and opened in the Designer. As mentioned

earlier, an Outlook form region, like an Actions

Pane and a Task Pane, is simply a user control.

However, unlike an Actions Pane, it contains an

embedded manifest that defines how the form

region appears in Outlook. To access the manifest,

ensure that the form is selected in the Designer

and open the Properties window. This will show

a property called Manifest, under which you can set various properties to how it appears. This

property can also be accessed through code at run time.

In this scenario you will use the Outlook form

region to display some additional useful information

about a Contact. The layout of an Outlook form

region is created in the same way as any other user

control. Drag four Label controls and four textbox

controls onto the design surface and align them

as shown in Figure 19-10. Rename the textbox

controls txtPartner, txtChildren, txtHobbies,

and txtProfession, and change the text on the

labels to match these fields.

fiGure 19-8

fiGure 19-9

fiGure 19-10

Creating an application add-in .

391

The ContactItem class contains a surprisingly large number of properties that are not obviously

displayed in a standard Contact form in Outlook. In fact, with well over 100 contact-specific fields,

there is a high chance that any custom property you want to display for a contact is already defined.

In this case, the fields displayed on this form (spouse/partner, children, hobbies, and profession) are

available as existing properties. You can also store a custom property on the item by adding an item

to the UserProperties collection.

The code behind the form region will already have stubs for the FormRegionShowing and

FormRegionClosed event handlers. Add the following code to those properties to access the current

Contact item and retrieve and save these custom properties:

c#

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

{

var myContact = (Outlook.ContactItem)this.OutlookItem;

this.txtPartner.Text = myContact.Spouse;

this.txtChildren.Text = myContact.Children;

this.txtHobbies.Text = myContact.Hobby;

this.txtProfession.Text = myContact.Profession;

}

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

{

var myContact = (Outlook.ContactItem)this.OutlookItem;

myContact.Spouse = this.txtPartner.Text;

myContact.Children = this.txtChildren.Text;

myContact.Hobby = this.txtHobbies.Text;

myContact.Profession = this.txtProfession.Text;

}

Code Snippet CustomFormRegion.cs

Vb

Private Sub CustomFormRegion_FormRegionShowing(ByVal sender As Object, _

ByVal e As System.EventArgs) _

Handles MyBase.FormRegionShowing

Dim myContact = CType(Me.OutlookItem, Outlook.ContactItem)

myContact.Spouse = Me.txtPartner.Text

myContact.Children = Me.txtChildren.Text

myContact.Hobby = Me.txtHobbies.Text

myContact.Profession = Me.txtProfession.Text

End Sub

Private Sub CustomFormRegion_FormRegionClosed(ByVal sender As Object, _

ByVal e As System.EventArgs) _

Handles MyBase.FormRegionClosed

Dim myContact = CType(Me.OutlookItem, Outlook.ContactItem)

myContact.Spouse = Me.txtPartner.Text

myContact.Children = Me.txtChildren.Text

myContact.Hobby = Me.txtHobbies.Text

myContact.Profession = Me.txtProfession.Text

End Sub

Code Snippet CustomFormRegion.vb

392 .

chaPter 19 oFFice buSineSS ApplicATionS

Press F5 to build and run the add-in in Debug mode. If the solution compiled correctly, Outlook

will open with your add-in registered. Open the Contacts folder and create a new Contact item.

To view your custom Outlook form region, click the Custom Details button in the Show tab

group of the Office Ribbon. Figure 19-11 shows how the Outlook form region should appear in

the Contact Inspector window.

fiGure 19-11

debuGGinG office aPPlications

You can debug Office applications by using much the same process as you would with any other

Windows application. All the standard Visual Studio debugger features, such as the ability to insert

breakpoints and watch variables, are available when debugging Office applications.

The VSTO run time, which is responsible for loading add-ins into their host applications, can

display any errors that occur during startup in a message box or write them to a log file. By default,

these options are disabled, and they can be enabled through environment variables.

To display any errors in a message box, create an environment variable called

VSTO_SUPPRESSDISPLAYALERTS and assign it a value of 0. Setting this environment variable to 1,

or deleting it altogether, will prevent the errors from being displayed.

To write the errors to a log file, create an environment variable called VSTO_LOGALERTS and assign

it a value of 1. The VSTO run time will create a log file called <manifestname>.manifest.log

in the same folder as the application manifest. Setting the environment variable to 0, or deleting it

altogether, will stop errors from being logged.

unregistering an add-in

When an application-level add-in is compiled in Visual Studio 2010, it automatically registers the

add-in to the host application. Visual Studio will not automatically unregister the add-in from

your application unless you run Build . Clean Solution. Therefore, you may find your add-in will

Debugging office applications .

393

continue to be loaded every time you launch the application. Rather than reopen the solution in

Visual Studio, you can unregister the add-in directly from Office.

To unregister the application you will need to open the Add-Ins window. Under Outlook 2010,

select File . Options . Add-ins to bring up the window shown in Figure 19-12. For Outlook

2007, select Tools . Trust Center from the menu and click Add-ins. For all the other Microsoft

Office applications, open the File or Office menu and click the Options button on the bottom of

the menu screen.

fiGure 19-12

If it is registered and loaded, your application

will be listed under the Active Application

Add-ins list. Select COM Add-ins from the

drop-down list at the bottom of the window

and click the Go button. This brings up the

COM Add-Ins window shown in Figure 19-13

that will allow you to remove your add-in from

the application.

fiGure 19-13

You can also disable your add-in by clearing the checkbox next to the add-in name in this window.

394 .

chaPter 19 oFFice buSineSS ApplicATionS

disabled add-ins

When developing Office applications, you will inevitably do something that will generate an

unhandled exception and cause your add-in to crash. If your add-in happens to crash when it is

being loaded, the Office application will disable it. This is called soft disabling.

A soft-disabled add-in will not be loaded and will appear in the Trust Center (see Figure 19-12) under

the Inactive Application Add-ins list. Visual Studio 2010 will automatically re-enable a soft-disabled

add-in when it is recompiled. You can also use the COM Add-Ins window that was displayed earlier

in Figure 19-13 to re-enable the add-in by ticking the checkbox next to the add-in name.

An add-in will be flagged to be hard disabled

when it causes the host application to crash,

or when you stop the debugger, while the

constructor or the Startup event handler is

executing. The next time the Office application

is launched, you will be presented with a dialog

box similar to the one shown in Figure 19-14. If

you select Yes the add-in will be hard disabled.

When an add-in is hard disabled it cannot be

re-enabled from Visual Studio. If you attempt to debug a hard-disabled add-in, you will be

presented with a warning message that the add-in has been added to the Disabled Items list and