Outlook 2007 Sample Add-ins: Rules Add-in, Travel Agency Add-in, and Prepare for Meeting Add-in

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary:   Learn about enhancements to the Outlook 2007 object model, as demonstrated by three sample add-ins. These solutions are available in Visual Basic .NET and C# versions and include an add-in project, a COM shim project to provide application domain (AppDomain) isolation, and a setup project. Versions of the sample add-ins are also available for VSTO 2005 SE. They can help new and experienced Outlook add-in developers begin programming with the Outlook 2007 object model. (8 printed pages)

Randy Byrne, Senior Program Manager

Ryan Gregg, Program Manager

Microsoft Corporation

Published: June 2006

Updated: February 2007

Applies to: Microsoft Office Outlook 2007

Download: Outlook 2007 Add-Ins: RulesAddin, TravelAgencyAddin, and PrepareMeAddin

Contents

• Add-Ins Overview

• Building and Running the Sample Add-Ins

• Rules Add-In

• Travel Agency Add-In

• Prepare for Meeting Add-In

• Conclusion

• Additional Resources

Add-Ins Overview

The sample add-ins described in this article are designed to show you how to use several of the new features of the Microsoft Office Outlook 2007 object model. The add-ins range from the Rules add-in, which is relatively simple, to the complex Prepare for Meeting sample add-in. The following list highlights the object model features demonstrated in the samples:

• Form regions

• Custom task panes

• Rules object model

• Table object

• PropertyAccessor object

• Ribbon extensibility

• Context menu events

• Enhancements to Namespace and Application objects

Additionally, the release versions of the sample add-ins use a COM shim or Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE) to provide AppDomain isolation for each of the add-ins. Among other benefits, AppDomain isolation ensures that an unhandled exception in one add-in does not cause other add-ins running in the shared AppDomain to fail. The beta sample add-ins used a shared AppDomain.

You are welcome to extract code from these samples to use in your own solution.

Requirements

To use the sample add-ins, the following components are required:

• Microsoft Office Outlook 2007

• Microsoft Visual Studio 2005

• Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System

Note
The Outlook 2007 sample add-ins run only on Visual Studio 2005 Standard Edition, Visual Studio 2005 Professional Edition, or Visual Studio 2005 Team System. If you are using Microsoft Visual C# Express Edition or Microsoft Visual Basic Express Edition to open the sample add-ins, you will not be able to build the setup/deployment project and install the sample add-ins.

Building and Running the Sample Add-Ins

You can build and install a sample add-in or run the add-in in debug mode. The following instructions are generic. To build and run a specific sample add-in, substitute the specific solution name, add-in project name, and setup project name for the placeholder in the following instructions.

To use the sample add-ins

1. Close Outlook 2007.

2. In the My Documents\Visual Studio 2005\Projects\SolutionName folder, open the SolutionName solution.

3. Select AddinNameSetup in Solution Explorer.

4. Select Rebuild AddinName Setup on the Build menu.

5. [Optional] After the build process has completed, select Install on the Project menu to install the solution. For the Travel Agency sample add-in, you must install the sample to write form region registry keys to the Windows registry. If the keys are not written to the registry, the sample will not operate correctly. This installation step is mandatory only for the Travel Agency sample add-in.

6. Start Outlook to start the add-in in Run mode or press F5 to start the add-in in Debug mode.

Note
If you install the sample add-ins on Windows Vista, you must run Visual Studio 2005 as Administrator to build the PrepareMeCS or PrepareMeVB solutions.

To run Visual Studio 2005 as Administrator

1. Click Start, and locate Microsoft Visual Studio 2005.

2. Right-click Microsoft Visual Studio 2005.

3. Select the Run As Administrator command.

   Note

   The Visual Studio Tools for Office sample add-ins run correctly without additional steps in Debug mode. If you want to run the VSTO sample add-ins in Run mode, you must run the Microsoft .NET Framework 2.0 Configuration tool in the Administrative Tools group in Windows Control Panel to grant Full Trust for the folder into which you installed the sample code assembly. For additional details about Code Access Security policy and VSTO add-ins, see How to: Grant Permissions to Folders and Assemblies.

If Outlook does not launch in Debug mode, follow these steps

1. Select AddinName in Solution Explorer.

2. On the Project menu, click AddinNameProperties, and then click the Debug tab.

3. Under Start Action, select the Start External Program check box and click the Browse (...) button.

4. In the folder, Drive:\Program Files\Microsoft Office\Office12, select Outlook.exe.

Note
If you install the sample add-ins on Windows Vista, an update to Microsoft Visual Studio 2005 might be required. To build add-ins such as the Prepare Me sample, you need to start Visual Studio with elevated privilege.

Rules Add-In

This add-in is available in a Visual Basic .NET version (RulesAddinVB or RulesAddinVB_VSTO) and in a C# version (RulesAddinCS or RulesAddinCS_VSTO).

The Rules add-in demonstrates how you can substitute a custom Microsoft Windows Form dialog box for the default Outlook Create Rule dialog box that can be invoked from the context menu for an item. Figure 1 shows the default Outlook Create Rule dialog box.

Figure 1. Outlook Create Rule dialog box

Suppose your organization wants to take advantage of some of the new features in Outlook 2007, such as task flagging or category coloring. To help your users with these new features, you decide to customize the built-in Create Rule dialog box with a dialog box that makes it easier for users to create rules based on task flagging or category coloring. The Rules add-in provides a simple add-in solution for you to get started on this assignment.

The enhanced Outlook 2007 object model provides the following new objects to help you create rules programmatically:

• RuleAction object and its derived classes such as MoveToFolderRuleAction, AssignToCategoryRuleAction, and MarkAsTaskRuleAction.

• RuleCondition object and its derived classes such as TextRuleCondition, ToOrFromRuleCondition, CategoryRuleCondition, or AddressRuleCondition.

• Rules collection object and Rule object. You can use the Rules.Create method to return a Rule object; enable Rule.Actions, Rule.Conditions, and Rule.Exceptions for the rule; call Rules.Save to save the rule, and optionally call Rule.Execute to run the rule immediately.

Figure 2 shows the custom Create Rule dialog box created by the sample Rules add-in.

Figure 2. Outlook custom Create Rule dialog box

The custom dialog box is displayed when the user selects Create Rule in the shortcut menu for an item, as shown in Figure 3. In earlier versions of Outlook, context menu customization was not possible. In Outlook 2007, the following events enable you to perform context menu customization:

• Application.AttachmentContextMenuDisplay

• Application.FolderContextMenuDisplay

• Application.ItemContextMenuDisplay

• Application.ShortcutContextMenuDisplay

• Application.StoreContextMenuDisplay

• Application.ViewContextMenuDisplay

Figure 3. Custom command replaces built-in context menu command

The Rules add-in demonstrates the following new features of the Outlook 2007 object model:

• Creating a rule programmatically

• Repurposing the Create Rule command on the item context menu, the Outlook Explorer toolbar, and the Ribbon for a mail read note

• Displaying the address book using the SelectNamesDialog object

• Accessing properties that are not exposed directly in the Outlook object model by using the PropertyAccessor object

To use the Rules add-in

1. Follow the procedures described earlier in the Building and Running the Sample Add-Ins section.

2. Start Outlook, and right-click a message in your Inbox.

3. On the shortcut menu, select the Create Rule command.

4. Under When I get e-mail with any of the following conditions, select a condition.

5. Under Do the following, select an action.

6. To create the rule, click OK.

Travel Agency Add-In

This add-in is available in a Visual Basic .NET version (TravelAgencyAddinVB or TravelAgencyAddinVB_VSTO) and in a C# version (TravelAgencyAddinCS or TravelAgencyAddinCS_VSTO).

The Travel Agency add-in demonstrates how to employ the new form region technology in Outlook 2007 to use a separate form region and an adjoining form region to add user interface elements to an Outlook form. Figure 4 shows a separate form region that occupies a single page in the Outlook form. This form region is displayed in an inspector for a Contact item. It contains Outlook controls such as the Electronic Business Card control, the edit box control for entering the full name, and the combo box control for entering the seat preference. All these controls automatically bind to Outlook data.

Figure 4. Separate Itineraries form region on a built-in Contact Item

Figure 5 shows an adjoining form region in the Reading Pane. This form region is displayed in the Reading Pane of the currently selected mail item if the sender of the message is represented by a Contact in the default Contacts folder. The form region shows recent itinerary information for the sender's contact.

Figure 5. Adjoining form region displays recent itinerary information for the sender of a message

When you examine the sample code, note that you must implement the FormRegionStartup interface to hook up your form region definitions that are stored as resources in the Travel Agency add-in. The sample code shows you how to use all of the members of the FormRegionStartup interface:

• GetFormRegionStorage

• BeforeFormRegionShow

• GetFormRegionManifest

• GetFormRegionIcon

Because multiple inspectors can be opened simultaneously, each FormRegion object is wrapped in the BaseFormRegionWrapper class and its derived classes, ContactFormRegionWrapper and MailPreviewFormRegionWrapper. To edit or add itineraries, the sample uses a simple WinForm, FormEditItinerary. Unlike legacy custom forms in previous versions of Outlook, the code behind a form region lives in an add-in.

The Travel Agency add-in persists data for each Contact item in a hidden attachment stored with the item. The hidden attachment contains XML that serializes the itineraries for a given Contact.

To use the Travel Agency add-in

1. Follow the procedures described in the section Building and Running the Sample Add-Ins.

2. In the navigation pane, click the Contacts module.

3. In your Contacts folder, open a contact.

4. On the Show group of the Ribbon, click the Itineraries command.

5. Click New Itinerary to add an itinerary, Edit Itinerary to edit an existing itinerary, or Delete Itinerary to remove an existing itinerary.

6. You must save the contact in order to save the itineraries with the item.

Prepare for Meeting Add-In

This add-in is available in a Visual Basic .NET version (PrepareMeVB or PrepareMeVB_VSTO) and in a C# version (PrepareMeCS or PrepareMeCS_VSTO).

The Prepare for Meeting add-in demonstrates how to add an Office 2007 custom task pane to an Outlook appointment item that represents a meeting for which you are the organizer or an attendee. It best showcases its functionality if you are connected to a Microsoft Exchange server. Being the most complex of the sample add-ins, the Prepare for Meeting add-in also provides sample code for the following:

• Creating an Office 2007 custom task pane in an Outlook inspector.

• Customizing a context menu to add an Open with Planner command.

• Using the new Table object to obtain rows representing messages from attendees and related appointments.

• Using the new PropertyAccessor object to obtain MAPI properties that are not exposed on Outlook objects.

• Enumerating the Categories collection object and adding categories for the meeting to the tree view control in the custom task pane.

• Using the object model to display a separate Outlook Explorer window and displaying search results programmatically using the Explorer.Search method.

• Providing details from the Exchange directory using the new ExchangeUser and ExchangeDistributionList objects.

• Adding a custom command to the Ribbon in an Outlook Inspector. A resource named CustomUI.xml provides the markup for the custom commands.

• Using the new StorageItem object to store add-in settings that roam and are available online and offline. If you click Options on the custom Planner group on the Ribbon, the Options dialog box is displayed.

• Using resource files to localize strings for all custom user interface created by the add-in.

The Prepare for Meeting add-in is the most complex sample add-in provided and is targeted for advanced development scenarios.

The custom task pane shown in Figure 6 is implemented as a WinForm user control. It contains a TreeView control that shows all attendees for the meeting and the most recent messages received from each attendee. It also shows categories assigned to the meeting and related meetings in the custom task pane.

Figure 6. Prepare for Meeting Custom Task Pane

To use the Prepare for Meeting add-in

1. Follow the procedures described in the Building and Running the Sample Add-Ins section.

2. In the Navigation pane, click the Calendar module.

3. Right-click an appointment in your calendar, and select the Open with Planner command.

   The appointment must represent a meeting in order for the Open with Planner command to appear. If the appointment is a simple appointment (that is, it has no attendees), the Open with Planner command will not appear.

4. The appointment displays a custom task pane with a tree view that contains attendees for the meeting, categories for the meeting, and related appointments.

5. To view a configurable number of messages from the attendee in your Inbox, expand an attendee node. You can double-click the message to open it.

6. Right-click an attendee node. If you select the Properties command on the node context menu, you can display the address details of the attendee. If you select the Display All Messages command, you will display an Outlook Explorer window that uses the enhanced search capabilities of Outlook to find all messages in your mailbox from the attendee.

7. If the appointment is categorized, double-click the category under the Categories node to display all messages that are marked with that category.

8. In the Planning group on the Ribbon, click the Meeting Planner button to show or hide the custom task pane.

9. In the Planning group on the Ribbon, click the Options button to display the Options dialog box. Using the Options dialog box, you can configure the number of messages displayed per attendee, whether to expand distribution lists, and the number of related appointments displayed.

Conclusion

Use the sample add-ins to explore the new object model features in Outlook 2007. These samples provide you with working code to get you started with creating a new solution or converting an existing solution. While the sample add-ins do not use every new object in the Outlook 2007 object model, they use all the important new features such as form regions, custom task panes, the Table object, and the PropertyAccessor object.

Additional Resources

• Outlook Developer Portal

• What's New for Developers in Outlook 2007 (Part 1 of 2)

• What's New for Developers in Outlook 2007 (Part 2 of 2)