This chapter is from the book
This chapter is from the book
This chapter is from the book
VSTO and Managed Code
When you create VBA solutions for Word and Excel, your code typically is stored in the document or in an attached or global template. To access code in a template separate from your solution, you set a reference from your document to the template.
However, when you create VSTO solutions, your code is stored in an assembly. You can set references in your project to other assemblies, such as .NET Framework assemblies and interop assemblies, but you cannot set a reference to other VSTO solution assemblies. Only one VSTO solution assembly can be associated with a document or workbook. However, multiple documents can reference the same solution assembly. This is the case when you create multiple documents based on a VSTO-customized template. Note that because Outlook solutions are application-level, you can load multiple add-ins into Outlook. The same is true for add-ins created with VSTO 2005 SE.
Primary Interop Assemblies
Office applications, such as Word and Excel, are written in unmanaged code. For your VSTO solution (managed code) to interoperate with the unmanaged COM objects in the Office application, it must use an interoperability assembly. Visual Studio can create an interoperability assembly for you when you set a reference to a COM type library, but generating an interoperability assembly in this way is not recommended. Instead, you should use the official interoperability assembly that is provided by the publisher of the type library. This is known as the primary interop assembly (PIA). If the PIAs are installed on your computer and you set a reference to the type library, Visual Studio automatically loads the PIA instead of generating a new interop assembly.
Microsoft provides PIAs for its Office applications. The name of the Excel PIA is Microsoft.Office.Interop.Excel.dll. Word and Outlook follow the same naming convention for their PIAs: Microsoft.Office.Interop.Word.dll and Microsoft.Office.Interop.Outlook.dll.
The PIAs get installed in your computer's GAC when you run a complete installation of Office 2003. Whenever you create a new VSTO solution, Visual Studio automatically adds to your solution a reference to the appropriate Office PIA and any of its dependent assemblies. You can view the contents of the GAC by opening the Windows\assembly directory of your root drive. Figure 3.7 shows the Microsoft PIAs.
)
Figure 3.7 Microsoft Office PIAs displayed in the GAC
The namespace for these PIAs is determined by the name of the assembly. VSTO automatically creates an alias for these namespaces, as shown in Table 3.3.
Table 3.3. Excel, Word, and Outlook PIAs, Namespaces, and Aliases
|
PIA |
Namespace |
Alias |
|
Microsoft.Office.Interop.Excel.dll |
Microsoft.Office.Interop.Excel |
Excel |
|
Microsoft.Office.Interop.Word.dll |
Microsoft.Office.Interop.Word |
Word |
|
Microsoft.Office.Interop.Outlook.dll |
Microsoft.Office.Interop.Outlook |
Outlook |
If the PIAs have not been correctly installed on your development machine because a complete installation of Office 2003 was not performed, you can run a reinstall or repair of Office 2003, assuming that .NET Framework 1.1 or later is already installed on your computer. Alternatively, you can use Add or Remove Features in the Maintenance Mode Options section of the Microsoft Office 2003 Setup, and click Next (see Figure 3.8). For information on redistributing the PIAs when you deploy your solutions, see Chapter 11.
)
Figure 3.8 Maintenance Mode Options in Microsoft Office 2003 Setup
On the next page of the Setup wizard, select Choose Advanced Customization of Applications, and then click Next.
Set each of the following components to Run from My Computer. See Figure 3.9 for an example.
)
Figure 3.9 Advanced Customization in Microsoft Office 2003 Setup
- Microsoft Office Excel | .NET Programmability Support
- Microsoft Office Outlook | .NET Programmability Support
- Microsoft Office Word | .NET Programmability Support
- Office Tools | Microsoft Forms 2.0 .NET Programmability Support
- Office Tools | Smart Tag .NET Programmability Support
- Office Tools | Microsoft Graph, .NET Programmability Support
Solution Assemblies
As you learned earlier in this chapter, an assembly is a collection of classes and functionality that is stored as an executable file (.exe) or a library (.dll). When you build a VSTO solution, the code is compiled and stored in a single assembly (DLL file) located in the \bin\debug (or \bin\release) directory of your solution. The assembly isn't stored inside the document, but the document does include an application manifest, which contains information about the name and location of the assembly. There are two manifests: an application manifest (which is stored in the document via an embedded control called the Runtime Storage Control) and a deployment manifest, which is located in the same directory where the assembly is deployed.
Even though you can associate a VSTO solution assembly only with a particular document (you can have only one solution assembly associated with a document), your solution assembly can reference other assemblies. For example, to add a common group of user controls to the actions pane, you can save a library of user controls in an assembly and then reference that assembly from multiple VSTO solutions.
How do you determine which VSTO assembly is associated with a particular document? You look at the document properties. You can view the document properties of a Word document or Excel workbook by clicking Properties in the File menu. A VSTO-enabled document has two custom document properties that indicate that the document is a VSTO solution. The first custom property is named _AssemblyName. If the value of _AssemblyName is an asterisk (*), it means that the document has an associated VSTO customization (assembly). The second custom property, _AssemblyLocation, stores the globally unique identifier (GUID) of the Runtime Storage Control (which contains the application manifest and information about where to locate the associated assembly). Figure 3.10 shows the custom document properties of a Word solution.
)
Figure 3.10 Custom document properties of a Word solution
Adding Customization to Existing Documents
You can attach an existing solution assembly to an uncustomized document or worksheet in one of two ways. The first is to add the _AssemblyName property with a value of asterisk (*), add the _AssemblyLocation custom property with the location of the deployment manifest as its value, and then save, close, and reopen the document. The second approach involves using the AddCustomization method of the ServerDocument class. These techniques are described in more detail in Chapter 13, Advanced Topics in VSTO 2005.
Running VSTO Solutions
For a VSTO solution to run, the assemblies must have full trust permissions. On the development machine, full trust is automatically granted to your solution's assembly and any referenced assemblies whenever you build the project. The evidence used for this trust is based on location (the URL of the assembly). When you deploy your solution, you need to grant full trust to the document and the assembly by using a strong name or by digitally signing the assembly. This procedure is discussed in greater detail in Chapter 11.
As a developer, you can run your customization by pressing F5 or by clicking Start Debugging from the Debug menu in Visual Studio. You can also open the document or workbook that is stored in the /debug/bin directory of the location in which you saved your solution, or press Ctrl+F5 to run the solution without debugging it.
An end user can run a solution in one of two ways.
- To run a document-level customization, the user opens the document or workbook that has an associated customization assembly. Alternatively, the user can create a new document or workbook that is based on a template that has an associated customization assembly.
- To run an application-level customization (add-in), users have two options. They can open the application, which contains instructions to load an add-in when the application starts. Or they can manually enable the add-in in the COM Add-ins dialog box of the application.