Visual studio tools for office 2007

E-mail Events 461 Attachment Events 466 Custom Action Events 467 Other Events 470 Conclusion 473 Working with the Application Object 475 Methods and Properties That Return Active or Sele

Praise for Visual Studio Tools for Office 2007

“Visual Studio Tools for Office has always been one of my favorite technologies

to come out of Microsoft There are millions of people who use Office

applica-tions all day, every day; with VSTO, you can create applicaapplica-tions for them Eric

Carter and Eric Lippert helped create VSTO, so they know as much about it as

anybody, making this book a must-have After reading it, you’ll know

every-thing needed to begin building solutions that take advantage of the NET

Framework features, in the UI your users are familiar with.”

—Robert Green, senior consultant, MCW Technologies

“With the application development community so focused on the Smart Client

revolution, a book that covers VSTO from A to Z is both important and

neces-sary This book lives up to big expectations It is thorough, has tons of example

code, and covers Office programming in general terms—topics that can be

for-eign to the seasoned NET developer who has focused on ASP.NET

applica-tions for years Congratulaapplica-tions to Eric Lippert and Eric Carter for such a

valuable work!”

—Tim Huckaby, CEO, InterKnowlogy; Microsoft Regional Director

“Eric Carter and Eric Lippert really get it Professional programmers will love

the rich power of Visual Studio and NET, along with the ability to tap into

Office programmability This book walks you through programming Excel,

Word, and Outlook solutions.”

—Vernon W Hui, test lead, Microsoft Corporation

“This book is both a learning tool and a reference book, with a richness of tables

containing object model objects and their properties, methods, and events I

would recommend it to anyone considering doing Office development using

the NET Framework; especially people interested in VSTO programming.”

—Rufus Littlefield, software design engineer/tester, Microsoft Corporation

“This book will help Office NET Developers optimize their work It goes

beyond providing an introduction to VSTO and the object models of Word,

Excel, and Outlook The overview of other technologies available for

interact-ing with Office assist in analyzinteract-ing how to best approach any Office project In

addition, the authors’ insights into the design of this RAD tool make it possible

to get the most out of VSTO applications.”

—Cindy Meister, Microsoft MVP for VSTO, author of Word Programmierung, Das Handbuch

Visual Studio Tools for Office 2007 It is a must-have book for anyone doing

Office development.”

—Siew Moi Khor, programmer/writer, Microsoft Corporation

“We don’t buy technical books for light reading, we buy them as a resource for

developing a solution This book is an excellent resource for someone getting

started with Smart Client development For example, it is common to hear a

comment along the lines of, ‘It is easy to manipulate the Task Pane in Office

2007 using VSTO 2008,’ but until you see something like the example at the

start of Chapter 14, it is hard to put ‘easy’ into perspective.

“This is a thorough book that covers everything from calling Office applications

from your application, to building applications that are Smart Documents It

allows the traditional Windows developer to really leverage the power of

Office 2007.”

—Bill Sheldon, principal engineer, InterKnowlogy; MVP

“Eric Carter and Eric Lippert have been the driving force behind Office

develop-ment and Visual Studio Tools for Office The depth of their knowledge and

understanding of VSTO and Office is evident in this book Professional

devel-opers architecting enterprise solutions using VSTO 2008 and Office system

2007 now have a new weapon in their technical arsenal.”

—Paul Stubbs, program manager, Microsoft Corporation

“This book, also known as ‘The Bible of VSTO,’ has been rewritten for Office

2007 and I was delighted to read the sections on new VSTO features that were

added in Visual Studio 2008 It explains how the VSTO team hid the plumbing

and cumbersome coding tasks to allow you to be more productive and to just

create excellent business applications New or experienced in Office

develop-ment, you will want to add this book to your library!”

—Maarten van Stam, Microsoft MVP, Visual Developer, VSTO,

http://blogs.officezealot.com/maarten

“This book covers all of the ins and outs of programming with Visual Studio

Tools for Office in a clear and concise way Given the authors’ exhaustive

expe-riences with this subject, you can’t get a more authoritative description of

VSTO than this book!”

—Paul Vick, principal architect, Microsoft Corporation

ptgVisual Studio Tools

for Office 2007

John Montgomery, Series Advisor • Don Box, Series Advisor • Brad Abrams, Series Advisor

The award-winning Microsoft NET Development Series was established in 2002 to provide professional

developers with the most comprehensive and practical coverage of the latest NET technologies It is

supported and developed by the leaders and experts of Microsoft development technologies, including

Microsoft architects, MVPs, and leading industry luminaries Books in this series provide a core resource of

information and understanding every developer needs to write effective applications.

Titles in the Series

Brad Abrams, NET Framework Standard Library

Annotated Reference Volume 1: Base Class Library and

Extended Numerics Library, 978-0-321-15489-7

Brad Abrams and Tamara Abrams, NET Framework

Standard Library Annotated Reference, Volume 2:

Networking Library, Reflection Library, and XML Library,

Adam Calderon, Joel Rumerman, Advanced ASP.NET

AJAX Server Controls: For NET Framework 3.5,

978-0-321-51444-8

Charlie Calvert and Dinesh Kulkarni, Essential LINQ,

978-0-321-56416-0

Eric Carter and Eric Lippert, Visual Studio Tools for

Office 2007: VSTO for Excel, Word, and Outlook,

978-0-321-33488-6

Eric Carter and Eric Lippert, Visual Studio Tools for Office:

Using C# with Excel, Word, Outlook, and InfoPath,

978-0-321-33488-6

Eric Carter and Eric Lippert, Visual Studio Tools for

Office: Using Visual Basic 2005 with Excel, Word, Outlook,

and InfoPath, 978-0-321-41175-4

Steve Cook, Gareth Jones, Stuart Kent, Alan Cameron

Wills, Domain-Specific Development with Visual Studio

DSL Tools, 978-0-321-39820-8

Krzysztof Cwalina and Brad Abrams, Framework Design

Guidelines: Conventions, Idioms, and Patterns for Reusable

.NET Libraries, Second Edition, 978-0-321-54561-9

Joe Duffy, Concurrent Programming on Windows,

978-0-321-43482-1

Sam Guckenheimer and Juan J Perez, Software

Engineering with Microsoft Visual Studio Team System,

978-0-321-27872-2

Anders Hejlsberg, Mads Torgersen, Scott Wiltamuth,

Peter Golde, The C# Programming Language, Third Edition,

978-0-321-56299-9

Alex Homer and Dave Sussman, ASP.NET 2.0 Illustrated,

978-0-321-41834-0

Joe Kaplan and Ryan Dunn, The NET Developer’s Guide to

Directory Services Programming, 978-0-321-35017-6

Mark Michaelis, Essential C# 3.0: For NET Framework 3.5,

978-0-321-53392-0 James S Miller and Susann Ragsdale,

The Common Language Infrastructure Annotated Standard,

978-0-321-15493-4

Christian Nagel, Enterprise Services with the NET Framework: Developing Distributed Business Solutions with NET Enterprise Services, 978-0-321-24673-8 Brian Noyes, Data Binding with Windows Forms 2.0:

Programming Smart Client Data Applications with NET,

978-0-321-26892-1

Brian Noyes, Smart Client Deployment with ClickOnce:

Deploying Windows Forms Applications with ClickOnce,

Scott Roberts and Hagen Green, Designing Forms for Microsoft Office InfoPath and Forms Services 2007,

Guy Smith-Ferrier, NET Internationalization:

The Developer’s Guide to Building Global Windows and Web Applications, 978-0-321-34138-9 Will Stott and James Newkirk, Visual Studio Team System: Better Software Development for Agile Teams,

Upper Saddle River, NJ • Boston • Indianapolis • San Francisco

New York • Toronto • Montreal • London • Munich • Paris • Madrid

Capetown • Sydney • Tokyo • Singapore • Mexico City

Visual Studio Tools

for Office 2007

VSTO for Excel, Word, and Outlook

Eric Carter

Eric Lippert

are claimed as trademarks Where those designations appear in this book, and the

pub-lisher was aware of a trademark claim, the designations have been printed with initial

capital letters or in all capitals.

The NET logo is either a registered trademark or a trademark of Microsoft Corporation in

the United States and/or other countries and is used under license from Microsoft.

The authors and publisher have taken care in the preparation of this book, but make no

expressed or implied warranty of any kind and assume no responsibility for errors or

omissions No liability is assumed for incidental or consequential damages in connection

with or arising out of the use of the information or programs contained herein.

The publisher offers excellent discounts on this book when ordered in quantity for bulk

purchases or special sales, which may include electronic versions and/or custom covers

and content particular to your business, training goals, marketing focus, and branding

interests For more information, please contact:

U.S Corporate and Government Sales

Visit us on the Web: informit.com/aw

Library of Congress Cataloging-in-Publication Data

Carter, Eric.

Visual Studio tools for Office 2007 : VSTO for Excel, Word, and

Outlook / Eric Carter, Eric Lippert — 2nd ed.

p cm.

Includes bibliographical references and index

ISBN 978-0-321-53321-0 (pbk : alk paper)

1 Microsoft Visual BASIC 2 BASIC (Computer program language) 3

Microsoft Visual studio 4 Microsoft Office I Lippert, Eric II Title.

QA76.73.B3C3452 2009

Copyright © 2009 Pearson Education, Inc.

All rights reserved Printed in the United States of America This publication is protected

by copyright, and permission must be obtained from the publisher prior to any

prohib-ited reproduction, storage in a retrieval system, or transmission in any form or by any

means, electronic, mechanical, photocopying, recording, or likewise For information

regarding permissions, write to:

Pearson Education, Inc.

Rights and Contracts Department

501 Boylston Street, Suite 900

Boston, MA 02116

Fax (617) 671-3447

ISBN-13: 978-0-321-53321-0

ISBN-10: 0-321-53321-6

Text printed in the United States on recycled paper at Courier in Stoughton, Massachusetts

First printing, February 2009

To my wife, Tamsyn, and our children Jason, Hayley,

Camilla, Rand, Elizabeth, and Miles

—Eric Carter

To Leah Lippert, for embarking with me

on a fabulous adventure And to David Lippert,

who taught me to expect the unexpected along the way

—Eric Lippert

ptg

About the Authors lxi

PART III Office Programming in VSTO 571

Bibliography 1017

Index 1019

About the Authors lxi

Why Office Programming? 3

Office Business Applications 3

Office Programming and the Professional Developer 4

Why NET for Office? 4

Why Visual Studio Tools for Office? 5

How NET Is It? 6

Office Object Models 7

Optional Parameters in Word 24 Events 28

The Office Primary Interop Assemblies (PIAs) 39

Installing the PIAs 40 Referencing the PIAs 41 Browsing the PIAs 44

Conclusion 48

The Three Basic Patterns of Office Solutions 51

Hosted Code 52 How Code Gets Run After Startup 53 How Code Gets Unloaded 54

Office Automation Executables 54

Creating a Console Application That Automates an Already Running Office Application 57 Creating a Console Application That Automates Word 59

Office Add-Ins 69

Creating an Outlook 2007 Add-In in VSTO 70 Changes Between Outlook 2003 VSTO Add-Ins and Outlook 2007 VSTO Add-Ins 77

Code Behind a Document 78

XLA Add-Ins 97 Server-Generated Documents 97 Research Services 97

Programming User-Defined Functions 98

Building a Managed Automation Add-In That Provides User-Defined

Functions 99

Using Your Managed Automation Add-In in Excel 101

Some Additional User-Defined Functions 106

Debugging User-Defined Functions in Managed Automation Add-Ins 107

Deploying Managed Automation Add-Ins 107

Introduction to the Excel Object Model 108

Conclusion 112

Events in the Excel Object Model 115

New Workbook and Worksheet Events 116

Activation and Deactivation Events 120

Double-Click and Right-Click Events 128

Calculate Events 135

Change Events 139

Follow Hyperlink Events 141

Selection Change Events 145

WindowResize Events 146

Add-In Install and Uninstall Events 147

XML Import and Export Events 147

Before Close Events 148

Before Print Events 148

Before Save Events 149

Working with the Application Object 163

Controlling Excel’s Screen Updating Behavior 164

Controlling the Dialog Boxes and Alerts that Excel Displays 165

Changing the Mouse Pointer 166

Displaying a Message in Excel’s Status Bar 166

A Property You Should Never Use 167 Controlling the Editing Experience in Excel 168 Controlling the Look of Excel 169

Controlling File and Printer Settings 170 Properties That Return Active or Selected Objects 171 Properties That Return Important Collections 172 Controlling the Calculation of Workbooks 172 Using Built-In Excel Functions in Your Code 173 Selecting and Activating a Range of Cells 174 Spell Checking 174

Sending a Workbook in E-mail 175 Quitting Excel 176

Undo in Excel 176 Sending Keyboard Commands to Excel 176

Working with the Workbooks Collection 178

Iterating over the Open Workbooks 178 Accessing a Workbook in the Workbooks Collection 179 Creating a New Workbook 179

Opening an Existing Workbook 180 Closing All the Open Workbooks 181

Working with the Workbook Object 181

Properties That Return Active or Selected Objects 181 Properties That Return Important Collections 182 Accessing Document Properties 183

Saving an Excel Workbook 184 Naming Ranges of Cells 186 Creating and Activating Windows 188 Printing a Workbook 188

Protecting a Workbook 188

Working with the Worksheets, Charts,

and Sheets Collections 189

Iterating over the Open Sheets 190 Accessing a Sheet in the Collection 190 Adding a Worksheet or Chart Sheet 191 Copying a Sheet 192

Moving a Sheet 192

Working with Document Properties 192

Iterating over the DocumentProperties Collection 192

Accessing a DocumentProperty in the DocumentProperties Collection 193

Adding a DocumentProperty 194

Working with the Windows Collections 195

Iterating over the Open Windows 196

Accessing a Window in the Collection 196

Arranging Windows 197

Working with the Window Object 199

Positioning a Window 199

Display Settings Associated with a Window 200

Working with the Names Collection and Name Object 202

Iterating over the Names Collection 202

Accessing a Name in the Names Collection 202

The Name Object 203

Working with the Worksheet Object 204

Worksheet Management 204

Working with Names 206

Working with Worksheet Custom Properties 206

Protecting a Worksheet 208

Working with OLEObjects 214

Working with Shapes 215

Working with ChartObjects 216

Working with Tables 217

Working with the Range Object 219

Getting a Range Object for a Particular Cell or Range of Cells 219

Working with Addresses 223

Creating New Ranges Using Operator Methods 226

Working with Areas 227

Working with Cells 228

Working with Rows and Columns 229

Working with Regions 230

Selecting a Range 230

Editing the Values in a Range 231

Copying, Clearing, and Deleting Ranges 231

Finding Text in a Range 232 Formatting a Range of Cells 234

Special Excel Issues 235

The Excel Locale Issue for Automation Executables and COM Add-Ins 235 Converting Excel Dates to DateTime 239

Conclusion 241

Ways to Customize Word 243

Automation Executable 243 VSTO Add-Ins 244 Visual Studio Tools for Office Code Behind 245 Smart Documents and XML Expansion Packs 246 Smart Tags 247

Server-Generated Documents 248

Programming Research Services 249

Getting Started with Research Services 250 Registering the Research Service with Word 255 Using the Research Service 256

More Research Service Resources 261

Introduction to the Word Object Model 261

Conclusion 262

Events in the Word Object Model 267

Why Are There Multiple Application and Document Event Interfaces? 267 Visual Studio Generation of Event Handlers 270

Startup and Shutdown Events 271 New and Open Document Events 273 Document Close Events 276

Document Save Events 278 Document Activation Events 279 Document Print Events 282 Mouse Events 283

Selection Events 285 Window Sizing Events 287

Working with the Application Object 311

Controlling Word’s Screen Updating Behavior 312

Controlling the Dialogs and Alerts That Word Displays 313

Changing the Mouse Pointer 314

Displaying a Message in Word’s Status Bar or Window Caption 315

Controlling the Look of Word 316

Properties That Return Active or Selected Objects 319

Properties That Return Important Collections 320

Accessing Items in Collections 323

Navigating a Document 324

Working with Word’s Options 326

Working with the File Save Format Options 328

Working with File Dialogs 328

User Information 330

Checking Grammar and Spelling 330

Exiting Word 331

Working with the Dialog Object 332

Showing the Dialog and Letting Word Execute Actions 332

Selecting the Tab on a Dialog Box 333

Showing the Dialog and Preventing Word from Executing Actions 333

Getting and Setting Fields in a Dialog 334

Working with Windows 338

Creating New Windows 338

Iterating over the Open Windows 338

Accessing a Window in the Collection 339 Arranging Windows 339

Working with Templates 341

Working with Documents 343

Iterating over the Open Documents 343 Accessing a Document in the Documents Collection 344 Creating a New Document 345

Opening an Existing Document 345 Closing All Open Documents 347 Saving All Open Documents 348

Working with a Document 348

Preserving the Dirty State of a Document 349 Closing and Saving a Document 350 Working with Windows Associated with a Document 352 Changing the Template Attached to a Document 353 Important Collections Associated with Both Document and Range 353 Important Collections Associated with Document Only 356

Working with Document Properties 357 Checking Spelling and Grammar in Documents and Ranges 362 Printing a Document 364

Working with Read-Only Document Protection 365 Working with Password Protection 367

Undo and Redo 369

Working with the Range Object 369

Getting a Range 370 Identifying a Range 373 Changing a Range 374 Moving a Range 377 Ranges and Stories 380 Navigating a Range 380 Collapsing a Range 382 Getting Text from a Range 382 Setting the Text in a Range 384 Inserting Nonprinting Characters and Breaks 385

Working with Formatting 387

Find and Replace 389

Working with Bookmarks 392

Working with Tables 394

Working with Content Controls 396

Working with Content Controls Programmatically 400

Properties and Methods of Content Control 402

Custom Property Pages 410

Introduction to the Outlook Object Model 419

Conclusion 422

Events in the Outlook Object Model 425

View and Selection Change Events 436

Folder Change Events 439

Context Menu Events 442

Form Region Events 447

Outlook Item Events 448

Item Addition, Deletion, Change, and Move Events 448

Copy, Paste, Cut, and Delete Events 453

Property Change Events 455

Open, Read, Write, and Close Events 456

Item Load, Unload, and BeforeAutoSave Event 459

E-mail Events 461 Attachment Events 466 Custom Action Events 467

Other Events 470

Conclusion 473

Working with the Application Object 475

Methods and Properties That Return Active or Selected Objects 476 Properties That Return Important Collections 477

Performing a Search and Creating a Search Folder 479 Copying a File into an Outlook Folder 485

Quitting Outlook 486

Working with the Explorers and Inspectors Collections 486

Working with the Explorer Object 488

Working with the Selected Folder, View, and Items 489 Working with an Explorer Window 494

Adding Buttons and Menus to an Explorer Window 495 Working with the Navigation Pane Associated with the Explorer Window 496

Associating a Web View with a Folder 499 Setting and Clearing the Active Search for an Explorer Window 500

Working with the Inspector Object 501

Working with the Outlook Item Associated with the Inspector 501 Working with an Inspector Window 501

Working with an Inspector’s Word Editor 501 Adding Buttons and Menus to an Inspector Window 505

Working with the NameSpace Object 506

Working with the Root Folders of the Open Outlook Stores 507 Another Way to Iterate over Open Outlook Stores 508

Adding and Removing Outlook Stores 509 Managing the Master Category List 509 Checking Whether Outlook Is Offline 510 Getting Standard Folders Such As the Inbox Folder 510 Getting a Folder, Outlook Item, Store, or AddressEntry by ID 510

Determining the Current User and an Introduction to Recipient,

AddressEntry, ContactItem, ExchangeUser, and

ExchangeDistributionList 514

Accessing Address Books and Address Entries 515

Displaying the Outlook Select Folder Dialog Box 518

Displaying the Select Names Dialog Box 518

Working with the Folder Object 519

MAPIFolder and Folder 519

Other Identifiers for a Folder 519

Getting the Store for a Folder 520

Accessing Subfolders Contained in a Folder 520

Accessing Items Contained in a Folder 523

Working with a Folder’s View Settings 529

Working with StorageItem Objects 531

Copying or Moving a Folder to a New Location 534

Displaying a Folder in an Explorer View 534

Working with the Items Collection 534

Iterating over Outlook Items 534

Finding an Outlook Item 537

Adding an Outlook Item to an Items Collection 541

Working with the Table Object 545

Properties and Methods Common to Outlook Items 548

Creating an Outlook Item 548

Identifying the Specific Type of an Outlook Item 551

Other Properties Associated with All Outlook Items 556

Copying or Moving an Outlook Item to a New Location 558

Deleting an Outlook Item 558

Displaying an Outlook Item in an Inspector View 560

Working with Built-In and Custom Properties Associated

with an Outlook Item 561

PropertyAccessor: Accessing Advanced Properties 565

Saving an Outlook Item 566

Showing the Color Categories Dialog Box for an Outlook Item 566

Mail Properties and Methods 566

Conclusion 569

PART III Office Programming in VSTO 571

The VSTO Programming Model for Documents 573

Separation of Data and View 574 Model-View-Controller 575 Benefits of Separation 576

VSTO Extensions to Word and Excel Document Objects 576

Aggregation, Inheritance, and Implementation 576 Hooking Up the Aggregates 578

Obtaining the Aggregated Object 580 Aggregation and Windows Forms Controls 581 Improving C# Interoperability 582

The Tag Field 583 Event Model Improvements 583

Dynamic Controls in the Document 584

The Controls Collection 585 Enumerating and Searching the Collection 585 Adding New Word and Excel Host Controls Dynamically 586 Removing Controls 590

Dynamic Controls Information Is Not Persisted 590

Advanced Topic: Class Hookup and Cookies 591

Advanced Topic: Inspecting the Generated Code 594

The Startup and Shutdown Sequences 596 The Globals Class in Excel 598

VSTO Extensions to the Word and Excel Object Models 599

The Word Document Class 599 The Word Bookmark Host Control 605 The Word XMLNode and XMLNodes Host Control Classes 607 The Word Content Control Classes 609

The Excel Workbook Host Item Class 613 The Excel Worksheet Host Item Class 614 The Excel Chart Sheet Host Item Class and Chart Host Control 615 The Excel NamedRange, XmlMappedRange, and ListObject

Host Controls 615

The VSTO Programming Model for Add-Ins 619

Using VSTO Document Features in Application-Level Add-Ins 621

Preparing an Add-In Project to Use Document Features 621

Getting a VSTO Host Item Object for a Document, Worksheet,

or Workbook 622

Getting a VSTO Host Item Control for ListObject and Other

Host Item Controls 623

Other Applications and Limitations 623

Advanced Topic: Creating Worksheets Dynamically 624

Conclusion 625

Introduction 627

Moving from ActiveX to Windows Forms 627

Using WPF Controls via the ElementHost Control 628

When to Use Controls on the Document Surface 629

When to Use a Modal or Modeless Form 631

Adding Windows Forms Controls to Your Document 634

Modes for Adding Controls 635

Controls That Are Not in the Control Toolbox 636

Control Insertion Behavior in Word 638

Control Insertion Behavior in Excel 640

Layout of Controls on the Document or Worksheet Surface 641

Writing Code Behind a Control 641

The Windows Forms Control Hosting Architecture 643

The Windows Forms Control Host ActiveX Control 644

Why Are VSTO Controls Derived from Windows Forms Controls? 645

Security Implications of the VSTO Control Hosting Model 648

Limitations of the Control Hosting Model 649

Control State Is Not Saved in the Document 650

Why Are Controls Sometimes Slightly Blurry? 653

Properties Merged from OLEObject or OLEControl 654

Excel Control Properties That Are Added from OLEObject 654

Word Control Properties Added from OLEControl 654

Adding Controls at Runtime 658

Working with the Controls Collection 661

AddControl 663

Deleting Controls at Runtime 664 Why Are Controls Added at Runtime Not Saved in the Document? 664 Why Are Controls in the Controls Collection Typed as Object

Instead of Control? 666 Creating Controls in a Document Using an Application-Level Add-In 666

Using WPF Controls in the Document 669

Conclusion 671

Introduction to the Document Actions Task Pane 673

Working with the ActionsPane Control 680

The ActionsPane Architecture 680 Adding Windows Forms Controls to the Actions Pane 681 Adding a Custom User Control to the Actions Pane 684 Contextually Changing the Actions Pane 686

Detecting the Orientation of the Actions Pane 689 Scrolling the Actions Pane 691

Showing and Hiding the Actions Pane 691 Attaching and Detaching the Actions Pane 695 Some Methods and Properties to Avoid 697

Using WPF Controls in an Actions Pane 697

Conclusion 699

Introduction to the Application-Level Custom Task Panes 701

Working with Custom Task Panes 704

The CustomTaskPane Architecture 704 The CustomTaskPanes Collection 705 The CustomTaskPane Object 706 Adding a Custom User Control to the Custom Task Pane 708

Custom Task Panes and Application Windows 710

Custom Task Panes and Outlook-Specific Issues 711 Custom Task Panes and Word-Specific Issues 714 Custom Task Panes and Excel-Specific Issues 717

Using WPF Controls in a Custom Task Pane 719

Conclusion 722

Introduction to Form Regions 723

Creating a New Form Region 723

Customizing a Form Region 735

Form Region Types and Custom Message Classes 743

Built-In and Custom Message Classes 744

Creating an Outlook Forms-Based Form Region 749

Outlook Form Region Programmability 765

The VSTO Form Region Class 765

The Form Region Factory 766

The Manifest Object 767

Other Key Properties and Methods 773

Globals Support 773

Conclusion 774

Introduction to the Office Ribbon 777

Introduction to Office Ribbon Programmability 780

Ribbon Limitations 780

Introduction to the Office Ribbon Controls 781

Working with the Ribbon in the Ribbon Designer 800

The Toolbox 802

Properties Window, Tasks, and Events 803

Adding Child Controls to the Office Button, Split Button, and Menu

Creating a Ribbon in an Excel Workbook Project 812

Creating a Ribbon in an Outlook Add-In Project 825

Advanced Ribbon Topics 836

Multiple Ribbons in Word and Excel 837

Replacing the Entire Ribbon 838

Dynamism and the Ribbon 838 Modifying the Office Button Menu 840 Adding Commands to a Built-In Tab 845 Using the Position Property 846 Using Built-In Office Images 847 Using Windows Forms Components 848 Coordinating Ribbons and Task Panes 848 Exporting a Ribbon to XML 848

Delay Loading an Add-In with a Ribbon 848

Conclusion 850

Introduction to Smart Tags 851

Configuring Smart Tags in Word and Excel 853 The Persistent Tagging Generated by Smart Tags 855

Creating Document-Level Smart Tags with VSTO 855

Action Events 860 Using Varying Numbers of Terms 863 Using Regular Expressions 864 Using Varying Numbers of Actions 866 Creating a Custom Smart Tag Class 869 Using Smart Tag Properties Wisely 873

Creating Application-Level Smart Tags 874

Conclusion 880

Creating a Data-Bound Customized Spreadsheet with VSTO 882

Defining a Data Source 882 Creating Data-Bound Controls the Easy Way 886

Creating a Data-Bound Customized Word Document

with VSTO 889Datasets, Adapters, and Sources 891

Data Sources and Security Best Practices 892 Datasets 894

Adapters 897 Using Binding Sources as Proxies 900 Data-Bindable Controls 900

Another Technique for Creating Data-Bound Documents 901

Complex and Simple Data Binding 905

Data Binding in Word Documents 908

Caching Data in the Data Island 908

Caching Your Own Data Types 909

Dynamically Adding and Removing Cached Members from the Data

Island 910

Advanced Topic: Using ICachedType 911

Manipulating the Serialized XML Directly 913

Advanced ADO.NET Data Binding: Looking Behind

the Scenes 913

Binding-Related Extensions to Host Items

and Host Controls 914

Extensions to the List Object Host Control in Excel 915

Using Data Binding and Dynamic Controls from

an Application-Level Add-In 921

Conclusion 928

Populating a Document with Data on the Server 929

Data-Bound VSTO Documents 930

XML File Formats 930

Accessing the Data Island 931

Using ServerDocument and ASP.NET 931

Setting Up the Server 934

An Alternative Approach: Create a Custom Handler 936

A Handy Client-Side ServerDocument Utility 939

The ServerDocument Object Model 941

ServerDocument Class Constructors 942

Saving and Closing Documents 943

Static Helper Methods 944

Cached Data Objects, Methods, and Properties 948

Be Careful 952

Conclusion 952

Visual Studio Tools for the Office System 3.0 Runtime 958

Deploying Add-Ins 958

Publish Location 959 Install Settings 961 Publish Version 963 Publishing 963 Post Publishing 965 Installing 966 Installation: The Aftermath 974 Updating 978

Variations on the Deploying Add-ins Theme 980

Deploying Document Solutions 982

Publishing a Document Solution to a Web Server 982 Installing a Document Solution from a Web Server 986 Document Installation Aftermath 991

Updating a Document Solution from a Web Server 992 Variations on the Deploying Documents Theme 994

ClickOnce Security 995

Certificates 995 Trust Prompting 1002 Office Trusted Locations 1004 Inclusion List 1004

Security Checks 1005

Other Deployment Scenarios 1009

Deploying to a Web Site Other Than IIS 7 1009 Deploying to a CD or USB Key 1009

Deploying to SharePoint 1010 Custom Windows Installer Setups 1010

Advanced Topic: Editing Manifests Using Mage 1010

Setting the Product Name, Publisher Name, and Support URL

ptg

Figures

F IGURE 1-1: Hierarchy in the Word object model 7

F IGURE 1-2: Hierarchy in the Excel object model 8

F IGURE 1-3: Installing the Office 2007 PIAs 41

F IGURE 1-4: Adding a reference to a project 43

F IGURE 1-5: The Add Reference dialog box 43

F IGURE 2-1: Creating a console application from the New Project dialog box 61

F IGURE 2-2: The Console application project WordWiki shown in Solution

Explorer 62

F IGURE 2-3: Adding a reference to the Microsoft Word 2007 PIA 62

F IGURE 2-4: When you add the Word 2007 PIA, dependent PIA references are

automatically added to the project 63

F IGURE 2-5: Creating a new Outlook add-in project 71

F IGURE 2-6: The Outlook add-in project in Solution Explorer 71

F IGURE 2-7: Using the New Project dialog box to create an Excel Workbook

project 80

F IGURE 2-8: Selecting the workbook to associate with your code behind 81

F IGURE 2-9: The design view for VSTO Excel code behind 81

F IGURE 2-10: Creating a ListObject in the designer 83

F IGURE 2-11: The result of running Listing 2-8 and clicking the button we added to

the Document Actions task pane 85

F IGURE 3-1: The COM Add-Ins dialog box in Excel 91

F IGURE 3-2: The XML Expansion Packs dialog box in Excel 93

F IGURE 3-3: A custom Document Actions task pane in Excel 94

F IGURE 3-4: Smart Tags in Excel 95

F IGURE 3-5: The Smart Tags page in the AutoCorrect dialog box 96

F IGURE 3-6: The Research task pane 98

F IGURE 3-7: Checking the Register for COM Interop check box in the project

properties designer 102

F IGURE 3-8: Launching Visual Studio 2008 as administrator under Vista 102

F IGURE 3-9: Selecting AutomationAddin.MyFunctions from the Automation Servers

dialog box 103

F IGURE 3-10: AutomationAddin.MyFunctions is now installed 104

F IGURE 3-11: A simple spreadsheet to test the custom formula in 104

F IGURE 3-12: Picking MultiplyNTimes from the Insert Function dialog box 105

F IGURE 3-13: Setting arguments using the Function Arguments dialog box 105

F IGURE 3-14: The final spreadsheet 105

F IGURE 3-15: Setting Debug options to start Excel 108

F IGURE 3-16: Adding the Primary Output of the AutomationAddin project to the

setup project 109

F IGURE 3-17: The basic hierarchy of the Excel object model 109

F IGURE 3-18: Inserting various kinds of “sheets” into an Excel Workbook 110

F IGURE 3-19: A more detailed hierarchy of some major objects in the Excel object

F IGURE 4-1: Pop-up tooltip for generating event handlers 119

F IGURE 4-2: The Insert Hyperlink dialog box 142

F IGURE 4-3: Window Resize events are raised only if the workbook window is not

maximized to fill the application window 146

F IGURE 4-4: The hierarchy of CommandBar objects 153

F IGURE 5-1: Excel prompts when you call Quit and a workbook needs to

be saved 176

F IGURE 5-2: Naming a range of cells myCells using the Name Box 187

F IGURE 5-3: The Protect Sheet dialog box 208

F IGURE 5-4: The Allow Users to Edit Ranges dialog box 210

F IGURE 5-5: Inserting a chart 216

F IGURE 5-6: A table in Excel 218

F IGURE 5-7: Result of running Listing 5-27 222

F IGURE 5-8: A range with three noncontiguous areas 223

F IGURE 5-9: The Find and Replace dialog box 232

F IGURE 6-1: The COM Add-Ins dialog box in Word 244

F IGURE 6-2: The XML Expansion Packs tab of the Templates and Add-Ins dialog

box 246

F IGURE 6-3: Some recognized text 247

F IGURE 6-4: Dropping down the Smart Tag menu 247

F IGURE 6-5: The AutoCorrect dialog box 248

F IGURE 6-6: The Research task pane 249

F IGURE 6-7: Creating a Web Service Application project 250

F IGURE 6-8: Word’s Add Services dialog box 255

F IGURE 6-9: Word’s Research Service Setup dialog box 257

F IGURE 6-10: Research Service Confirmation and Options dialog box 257

F IGURE 6-11: Research Options dialog box 258

F IGURE 6-12: The Research task pane shows results from the new research

service 261

F IGURE 6-13: The basic hierarchy of the Word object model 262

F IGURE 6-14: Objects associated with Word’s Application object 263

F IGURE 6-15: Objects associated with Word’s Document object 264

F IGURE 6-16: Objects associated with Word’s Range object 265

F IGURE 6-17: Objects associated with Word’s Shape object 266

F IGURE 7-1: Adding an event handler using the pop-up tooltip 270

F IGURE 7-2: Adding a Document event handler using the Properties window

in VSTO 271

F IGURE 7-5: Step 1 of the Mail Merge Wizard 290

F IGURE 7-6: Step 3 of the Mail Merge Wizard 291

F IGURE 7-7: Selecting a data source 291

F IGURE 7-8: The Mail Merge Recipients dialog box 292

F IGURE 7-9: Step 6 of the Mail Merge Wizard 293

F IGURE 7-10: Selecting the records to merge 293

F IGURE 7-11: Content controls in Word’s Developer tab 297

F IGURE 7-12: A rich text control in a Word document 297

F IGURE 7-13: The Author property bound to a content control and displayed in the

document information pane 300

F IGURE 7-14: The custom toolbar created by Listing 7-14 in the Add-Ins tab and the

context menu that appears when you right-click in the document, 306

F IGURE 8-1: Visual Studio IntelliSense does not show the get_Item method when

Hide Advanced Members is checked in the Options dialog box 324

F IGURE 8-2: Word’s browser control 325

F IGURE 8-3: The Templates and Add-Ins dialog box showing the attached template

and global templates 342

F IGURE 8-4: The Protect Document task pane 366

F IGURE 8-5: The Start Enforcing Protection dialog box 366

F IGURE 8-6: A document with protection enforced but with an exception to allow

editing of the first sentence 367

F IGURE 8-7: The General Options dialog box 369

F IGURE 8-8: The result of running Listing 8-27—a range of length 9, including

nonprinting paragraph characters 371

F IGURE 8-9: Result of calling Expand(WdUnits.wdWord) or Words(1) on a

F IGURE 8-19: Result of calling MoveUntil(“abc”, WdConstants.wdForward) on a

Range containing h from The 379

F IGURE 8-20: Result of running Listing 8-34 385

F IGURE 8-21: The Breaks drop-down list from the Page Layout tab 386

F IGURE 8-22: Result of running Listing 8-35 389

F IGURE 8-23: The Bookmark dialog box 392

F IGURE 8-24: Result of checking the Show Bookmarks check box in the Advanced page

of Word’s Options dialog box 393

F IGURE 8-25: An example of all eight content control types 398

F IGURE 8-26: The UI shown when a user clicks a drop-down list content control 399

F IGURE 8-27: The Content Control Properties dialog box for a drop-down list 399

F IGURE 9-1: The COM Add-Ins dialog box in Outlook 407

F IGURE 9-2: Turning on Smart Tags in Outlook 2007 408

F IGURE 9-3: Smart Tags in an e-mail message 409

F IGURE 9-4: When you right-click a person’s name in Outlook, Smart Tag actions

appear under the Additional Actions submenu 410

F IGURE 9-5: The user control designer 411

F IGURE 9-6: A custom property page added to Outlook’s Options dialog box 416

F IGURE 9-7: A custom property page added to a folder’s Properties dialog box 416

F IGURE 9-8: The basic hierarchy of the Outlook object model 420

F IGURE 9-9: Some of the objects in the Outlook object model Gray objects are all

“Outlook items” 423

F IGURE 10-1: An Explorer window and an Inspector window 428

F IGURE 10-2: A custom action called My custom action 468

F IGURE 10-3: The Shortcuts pane showing two groups (Shortcuts and Group1) and

two shortcuts (Outlook Today and Inbox) 470

F IGURE 11-1: The Customize View dialog box 481

F IGURE 11-2: The Filter dialog box 482

F IGURE 11-3: The SQL tab of the Filter dialog box displays a filter string 483

F IGURE 11-4: The Custom View Organizer dialog box shows views associated with a

folder 491

F IGURE 11-5: Outlook’s Navigation Pane 497

F IGURE 11-6: Associating an HTML page with a folder 500

F IGURE 11-7: Adding commands to an Inspector window by using CommandBars

results in commands being added to the Add-Ins tab in Outlook

2007 506

F IGURE 11-8: Outlook’s Select Folder dialog box 518

F IGURE 11-9: Outlook’s Create New Folder dialog box 524

F IGURE 11-10: Outlook’s Color Categories dialog box 567

F IGURE 11-11: PostItem created by Listing 11-31 568

F IGURE 12-1: Model-View-Controller architecture 575

F IGURE 12-2: Examining the Document host item class in the Object Browser 577

F IGURE 12-3: Using the Show All Files button to examine hidden code 592

F IGURE 13-1: Two Windows Forms controls on a spreadsheet 630

F IGURE 13-2: DateTimePicker controls on a spreadsheet 630

F IGURE 13-3: Using the DateTimePicker control in the Document Actions task

pane 632

F IGURE 13-4: Displaying a Windows Forms dialog box when the user double-clicks

a cell 632

F IGURE 13-5: Drag and drop of a Button control from the toolbox to an Excel

worksheet 635

F IGURE 13-6: Drawing a Button control on an Excel worksheet 636

F IGURE 13-7: Changing the default insertion behavior in Word’s Options dialog

box 639

F IGURE 13-8: Changing the wrapping style for a control with Word’s Format Object

dialog box 639

F IGURE 13-9: Setting object positioning options for a control in Excel 640

F IGURE 13-10: The control positioning toolbar in VSTO 641

F IGURE 13-11: The basic hosting architecture for Windows Forms controls on the

document 644

F IGURE 13-12: Excel shows the ProgID of the underlying ActiveX hosting control 645

F IGURE 13-13: The result of running Listing 13-3 The Refresh button has been offset

relative to the VSTOContainerControl in the VSTO hosting

architecture 648

F IGURE 13-14: A DateTimePicker control in a Word document 651

F IGURE 14-1: The Styles task pane in Word 674

F IGURE 14-2: The drop-down menu for a task pane 675

F IGURE 14-3: The result of running Listing 14-1 677

F IGURE 14-4: The four layers of the ActionsPane architecture From left to right: The

Document Actions task pane, the VSTO ActiveX control, the ActionsPane

control, and controls parented to the ActionsPane control 680

F IGURE 14-5: The result of changing the ActionsPane StackOrder setting From top

left: ‘‡, ”‘‡ˆ–, ”‘‘––‘, ”‘‘’, and ”‘‹‰Š– 682

F IGURE 14-6: The design view for creating a custom user control 684

F IGURE 14-7: A custom user control 685

F IGURE 14-8: The result of running Listing 14-4 686

F IGURE 14-9: The actions pane in a horizontal orientation 689

F IGURE 14-10: The actions pane when AutoScroll is set to true 691

F IGURE 14-11: The actions pane solution attached to a Word document is visible in

Word’s Templates and Add-Ins dialog box and can be removed if

ActionsPane.AutoRecover is not set to true 696

F IGURE 14-12: The actions pane solution attached to an Excel workbook is visible in

Excel’s XML Expansion Packs dialog box and can be removed if ActionsPane.AutoRecover is not set to true 696

F IGURE 14-13: The visual designer for the Windows Forms UserControl2 after the WPF

UserControl1 is dropped on the surface Note the WPF User Controls in the toolbox and the tasks list where you can select Dock in Parent Container 698

F IGURE 14-14: A WPF User Control shown in the Document Actions task pane 699

F IGURE 15-1: The result of running Listing 15-1 703

F IGURE 15-2: The four layers of the CustomTaskPane architecture, from left to right:

the custom task pane, the VSTO ActiveX control, the UserControl, and controls parented to the UserControl 704

F IGURE 15-3: The design view for creating a custom user control 709

F IGURE 15-4: A custom user control 709

F IGURE 15-5: Custom task panes in Excel are associated with the application

window 718

F IGURE 15-6: The visual designer for the WPF User Control 720

F IGURE 15-7: The visual designer for the Windows Forms UserControl2 after the WPF

UserControl1 is dropped on the surface Notice the WPF User Controls

in the toolbox and the tasks list where you can choose Dock in Parent Container 720

F IGURE 15-8: A WPF User Control shown in a custom task pane 721

F IGURE 16-1: Creating a new Outlook 2007 add-in 724

F IGURE 16-2: Adding an Outlook form region to an Outlook 2007 add-in project 725

F IGURE 16-3: Selecting the form technology to use to create the form region 725

F IGURE 16-4: Selecting the type of form region to create: Separate 726

F IGURE 16-5: A task Inspector window with the Task page selected 727

F IGURE 16-6: A Task Inspector window with the Details page selected 727

F IGURE 16-7: Selecting the type of form region to create: Replacement 728

F IGURE 16-8: Selecting the type of form region to create: Replace-All 729

F IGURE 16-9: Replacement and Replace-All form regions can be associated only with

custom message classes 730

F IGURE 16-10: Selecting the type of form region to create: Adjoining 731

F IGURE 16-11: Setting descriptive text and display preferences 732

F IGURE 16-12: Picking which message classes will display a form region 733

F IGURE 16-13: The newly created form region project item in visual design view 734

F IGURE 16-14: A simple form region 735

F IGURE 16-15: An Adjoining form region in the reading pane 736

F IGURE 16-16: An Adjoining form region in the default page of an Inspector

window 736

F IGURE 16-17: A collapsed Adjoining form region 737

F IGURE 16-18: The effect of default height on the form region’s vertical scroll bar 737

F IGURE 16-19: A Separate form region version of the Subtasks form region 744

F IGURE 16-20: A Replacement form region version of the Subtasks form region 748

F IGURE 16-21: A Replace-All form region version of the Subtasks form region 748

F IGURE 16-22: The Design Form dialog box in the Outlook Forms Designer 750

F IGURE 16-23: Creating a new form region in the Outlook Forms Designer 750

F IGURE 16-24: Add all the controls that start with Microsoft Office Outlook to the

Controls toolbox 751

F IGURE 16-25: The Outlook Forms Designer with the toolbox, Properties window, and

Field Chooser tool 752

F IGURE 16-26: The Properties dialog box with the Layout tab selected 752

F IGURE 16-27: A form region designed in the Outlook Form Designer 753

F IGURE 16-28: Saving the form region to an Outlook form region file (.OFS file) 754

F IGURE 16-29: Importing an OFS file in the New Outlook Form Region wizard 755

F IGURE 16-30: Setting properties on the manifest object for a Windows Forms-based

form region 768

F IGURE 16-31: Creating a new Outlook Item by using the Choose Form button 769

F IGURE 16-32: The Choose Form dialog box 770

F IGURE 17-1: Key elements of the Office Fluent user interface: Microsoft Office

Button, Quick Access toolbar, tabs, contextual tabs, and groups 778

F IGURE 17-2: The drop-down menu that appears when you click the Microsoft Office

Button 778

F IGURE 17-3: A Gallery control for configuring margins 779

F IGURE 17-4: Box controls 782

F IGURE 17-5: Five variations on a button 783

F IGURE 17-6: The screen tip and super tip for the Bold button in Word 783