Chapter 54
The InfoPathEventHandler attribute has two properties. EventType should be set to the OnClick event so it will be hooked up with the proper event, while MatchPath should contain the name (the ID value) of the button control.
The DocActionEvent argument contains the XmlDocument associated with the InfoPath form, a ReturnStatus flag you can use to indicate the success or failure of your subroutine’s functionality, and a Source XmlNode object that contains the inner XML associated with the form.
Other Considerations
Keep a couple of other things in mind when developing InfoPath solutions with the Toolkit for Visual Studio. First, even though the documentation is installed, it is neither merged into the Office Solutions Development group nor displayed if you filter the Document Explorer by Office Development. It is found under its own category filter, Microsoft Office InfoPath 2003, or in its own root node in the full table of contents, InfoPath 2003 Toolkit for Visual Studio 2005.
Second, make sure you don’t obfuscate any code that will be required by InfoPath. InfoPath requires the code to have the member names it expects, rather than obfuscated terms, and doesn’t understand obfuscation at all.
When deploying your managed code solutions, you can choose from one of two options. If neither the code nor the InfoPath form template requires full trust, you can publish the form directly by using the Tools Publish Form menu command in Visual Studio 2005. This will switch over to InfoPath and kick off the normal Publishing Wizard.
However, if you need full trust, you’ll need to take some additional steps because by default the managed code InfoPath projects belong to the semi-trust zone of InfoPath and do not have full access to the computer system.
For full-trust solutions, you’ll need to either digitally sign the form template or use the RegForm utility that comes with the InfoPath SDK. The digital certification process can be done within InfoPath as long as you have an existing certificate. In the Security tab of the Form Options dialog, select Full Trust as the security level and then select the certificate that should be attached to the form.
Summar y
Building InfoPath solutions with extensive code processing is now available from within the managed code environment of Visual Studio 2005. Using the Toolkit, you can create solutions in either Visual Basic or C#, and as this chapter demonstrated, have direct access to form and field events so that you can easily affect the solution in a way that meets your requirements, rather than write JavaScript to perform this functionality.
Visual Studio Tools
for Office
Microsoft Office applications have always been extensible via add-ins and various automation techniques. Even languages such as Visual Basic 6, which are widely known for various limitations in accessing system files, had the capability to create add-ins for Office applications such as Microsoft Word, Microsoft Excel, and Microsoft Outlook. Developers could also write applications that used an instance of an Office application to achieve certain tasks (one such example is the prevalence of applications that take advantage of Word’s spell checking feature), but it was often difficult to get the solution just right.
Microsoft then released a technology called smart tags that enabled developers to build applications that hooked into Microsoft Word and Microsoft Excel, tracking the user’s input and providing the opportunity to give feedback, and even actions that the user could take in response to certain recognized terms.
When Visual Studio .NET (2002) was released, Microsoft soon followed with the first release of Visual Studio Tools for Office (known by the abbreviation VSTO, pronounced visto). This initial version of VSTO didn’t really produce anything new except for an easier way of creating application projects that would use Microsoft Word or Microsoft Excel. However, VSTO 2003, which works with Microsoft Office 2003 and Visual Studio .NET (2003), introduced a whole new concept known as smart documents.
Smart documents are special kinds of documents based on an XML schema. The schema’s contents control the information that can be entered into the document or worksheet, and provide some limited actions that the user could perform. Although Microsoft demonstrated some advanced solutions combining smart documents with smart tags that went a long way toward solving particular problems, the reality was that smart documents were incredibly difficult to get right beyond a simple document with one or two actions.
Chapter 55
That has all changed with the release of Visual Studio 2005 and Visual Studio Tools for Office 2005. Now, developing applications with Microsoft Word and Microsoft Excel is straightforward, and the integration of Windows Forms development and Office development has come a long way since the first versions.
This chapter begins with a look at each of the new features for Office developers in VSTO 2005 in turn, showing how it can make your life easier, and ends with a walk-through for creating a sample Word document application, complete with smart tags, Actions pane commands, and interaction among user, document contents, and code.
The New Visual Studio Tools for Office
When you install Visual Studio Tools for Office 2005, the setup includes a number of items that fully integrate Office development into Visual Studio. This includes new project types, an array of code snippets to ease your way into creating Office solutions, documentation integrated into the main MSDN library, and menu and option additions.
After a successful installation of VSTO, the first things you’ll notice in Visual Studio 2005 are the new project types now available to you when creating a new project. In the Visual Basic and C# language groups, a new group named Office is added containing a number of project templates for Office solutions (see Figure 55-1). VSTO solutions are only available in these two languages, so if you normally code in some other language and want to do VSTO development, you’ll have to switch.
Figure 55-1
The project templates cover the three Office applications capable of VSTO development; with Microsoft Excel and Microsoft Word, the templates include both Document (or Workbook) projects and Template projects. The difference in development is minimal — template projects are used to create documents or workbooks from a template, whereas the others create an individual document or workbook.
Because of the prevalence of macro viruses in Windows, Microsoft has restricted programmatic access to the macro system and VBA project model in Office by default. To ease development, VSTO insists on
Visual Studio Tools for Office
having direct access to the VBA project system. When you create a new VSTO project, Visual Studio checks the access level it has for VBA in Office. When it detects that the access level is not high enough, it prompts you to allow it access (see Figure 55-2).
Figure 55-2
If you don’t allow access, Visual Studio cancels the creation of the project, so this kind of message is really just warning you that if you proceed, the security access level in Office will be lowered.
You only have one question to answer when creating a VSTO project for either Word or Excel: whether to copy an existing document or create a new one (see Figure 55-3). Using an existing document can be useful if you have first created the document in Word or Excel and now want to attach the programmatic elements to the solution to the document, but with VSTO 2005’s integrated designer directly utilizing the Word and Excel applications for editing documents, you can just as easily create a new document and work with that.
Figure 55-3
Chapter 55
The majority of the discussion in this chapter uses Microsoft Word for illustrative purposes. The differences in most functionality between Microsoft Word and Microsoft Excel are minimal, and you can usually apply what is discussed here directly to an Excel solution in the same way.
The Visual Designer
When you created applications that used Word and Excel in previous versions of VSTO, everything was achieved by writing code and designing XML files and schemas. Because this included positioning controls in the Actions pane and setting other visual properties, it was sometimes difficult to get it right, resulting in a design process that relied heavily on trial and error.
With VSTO 2005 that’s all changed, and you can now design your Word and Excel solutions directly within the Visual Studio 2005 IDE. The document or workbook that is used as the basis for the project is part of the project files list in the Solution Explorer and can be opened in the main workspace area of the IDE.
As Figure 55-4 illustrates, the editor for a Word document project includes the toolbars from Word and the same visual presentation as Word. You can type directly into the document as if you were editing it in Word (and the same applies for Excel workbooks). All the same formatting functions are available to you so you can work in a familiar environment.
Figure 55-4
Visual Studio Tools for Office
In fact, the in-place editor exactly replicates the settings you have in Word itself, so any customizations you’ve made to the different views, such as showing paragraph marks and the style area in Normal view, are applied to the Visual Studio IDE.
Word and Excel are so well integrated into the development environment that you’ll find an additional submenu under the Tools menu of the IDE containing specific tools for the particular application you’re developing. Figure 55-5 shows the Tools menu that is added for Word Document and Word Template projects. You can even change the main Word application options from within Visual Studio, avoiding the need to start Word to change the application environment configuration.
Figure 55-5
As you’ve probably guessed, the reason for such an integrated replication of Word and Excel is because Visual Studio implements an instance of the appropriate application object and uses it to get the various settings, much like you might do if you were creating your own application that housed an instance of a Word document or Excel spreadsheet.
Control Design
When designing the visual interface of the document you can use most of the Windows Forms components in the layout. You can achieve this the same way you would if you were designing a Windows form or web application in flow mode, whereby each control is added after the next. The controls will flow around the text in the document as well, so you can create richly formatted documents that include controls that the user can interact with. An example of using Windows Forms controls in this way is when you want the majority of the document locked from edits but still want the user to be able to enter limited information, such as on a form.
Because the VSTO project is fully integrated into Word and Excel, you can use these controls in the same way you would if they were on a Windows form, including trapping their events and invoking their methods.
Chapter 55
In addition to the standard Windows Forms components, VSTO projects have an additional group of custom controls associated with the particular application. Known as host controls, these controls extend objects found within Word or Excel by wrapping them with a .NET layer, thus enabling them to be used at both design time (for layout) and runtime (to trap their events and interact with them like any other control).
In Word-based projects, there is a single host control called the Bookmark control, which enables you to mark a selection in the document or template with a named bookmark, which can be used later programmatically in your application. Excel-based projects have two host controls: ListObject compo-
nents replicate the behavior of sorted and filtered list columns in Excel, and NamedRange controls enable you to specify a section of a worksheet with a unique name to identify it in your program code.
Figure 55-6 shows a portion of an Excel worksheet in the Visual Studio designer. The spreadsheet contains both Windows Forms controls (the Button1 and TextBox1 components) and a ListObject host control with its filtering menu displayed. Each of these three controls can be customized in the Properties window just as you would for a normal Windows application.
Figure 55-6
Writing Code
VSTO enables you to write code for your Office-based applications in the same way as you would for a Windows application. You have full access to the application (Word or Excel) object, the current document’s object representation, and the events, methods, and properties exposed by them and their constituent controls.
When you create a VSTO project, in addition to the .doc or .xls file that contains the actual document contents, a code-behind file is also created and added to the Solution Explorer. Figure 55-7 illustrates this with an Excel-based project, showing four additional code files associated with the .xls file: one codebehind file for each of the default worksheet objects in the workbook and one workbook module. If you’ve ever used Visual Basic for Applications, you will see how this mirrors the same internal setup when editing the VBA code in Excel for a particular workbook.
Visual Studio Tools for Office
Figure 55-7
Every code-behind file has two subroutine stubs added to account for the interface into the Office application. These two subroutines, Startup and Shutdown, are used to initialize your application ready for execution, and can be used to integrate documents and their associated Actions panes, add VSTO-specific smart tags, and customize the user interface of Word or Excel with additional menus or toolbar items.
One problem that developers new to Office programming face is how to achieve common tasks. The program code required is not necessarily difficult, but because the object models of both Word and Excel are extensive, it is easy to become overwhelmed with the sheer number of members available.
Fortunately, VSTO 2005 ships with its own set of code snippets, which are automatically integrated into the main Code Snippet library. The code snippet collection has a sizable number of Wordand Excelspecific functions, such as programmatically filtering a ListObject control and adding tables in Word, but it also has more general snippets grouped into an Office category (see Figure 55-8). The snippets in this category provide you with the code to customize the environment with your own toolbars and menu commands.
Figure 55-8
Chapter 55
The Actions Pane
One of the more difficult aspects of smart documents in the previous version of VSTO was customizing the Actions pane to do what you wanted. It involved editing XML schemas and using code to control how each component was added and how it interacted with the application, whether it was Word or Excel.
VSTO 2005 solves all this by providing you with a new control known as an Actions Pane control, which comes with its own visual designer and programming model. Adding an Actions Pane component to your project is done in the same way as you would add any other type of item. Use the Project Add New Item menu command, or right-click the project file in the Solution Explorer and select Add New Item. Either of these actions displays the regular Add New Item dialog (shown in Figure 55-9), but besides the normal Windows Forms components there will be an Actions Pane Control template. Select that template, name the file to suit the purpose of your Actions Pane, and click Add.
Figure 55-9
You can actually use all of the item templates shown in Figure 55-9 in your VSTO application, so if you need to present a dialog box or want to separate your code into separate classes and modules, then you can do so by adding whatever items you need.
The visual designer for the Actions Pane component works much like a User Control. The design area is borderless, as it is housed in the main Actions pane in Word or Excel, and unlike the design for the document itself, you can precisely place and size your Windows Forms controls just as you would in a typical User Control. Figure 55-10 shows a simple Actions Pane component with Button, Label, and TextBox controls sited on its design surface.
Figure 55-10
Visual Studio Tools for Office
You can write code to handle the events for the child controls or even for the Actions Pane itself, calling their methods and setting and retrieving properties as needed. However, once your code for the Actions Pane is complete, you still need to hook the Actions Pane component to your document in order for it to be displayed properly.
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:
Private Sub ThisDocument_Startup(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Startup
Me.ActionsPane.Controls.Add(NameOfActionsPaneComponent)
End Sub
Figure 55-11 shows a Word document project. The Document Actions pane has been populated with the sample Actions Pane component, and the document text displays visual indicators where Bookmark host controls are sited.
Figure 55-11
Smar t Tags
Smart Tag technology has been around since Microsoft Office XP, but the initial implementation was difficult to code against. Smart Tags 2.0 introduced some necessary functionality to make the feature workable in anything beyond a demonstration environment, by giving the smart tag developer the capability to create extensive nested dynamic menus of actions when a term was found by the recognizer, and providing more information internally about recognized terms.
