Working with the Office XP Primary Interop Assemblies

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

Paul Cornell
Microsoft Corporation

September 2002

Applies to:
   Microsoft® Office XP
   Microsoft Visual Studio® .NET

Summary: Learn how to install, view, reference, and distribute solutions based on the Office XP Primary Interop Assemblies.

Download Office XP Primary Interop Assemblies.

Contents

Introduction
What Are the Office XP Primary Interop Assemblies?
System Requirements
Installing the Office XP PIAs
Viewing the Installed Assemblies
Referencing the Office XP PIAs
Distributing Solutions That Rely On the Office XP PIAs
Known Issues
Sample Walkthrough: Exporting Excel 2002 Worksheet Data to a .NET Windows Form ListBox Control
More Information

Introduction

Using Microsoft Visual Studio 6.0 development languages such as Microsoft Visual Basic® 6.0 to create solutions that interoperate with Microsoft Office XP applications is a straightforward process. This is because Visual Studio 6.0 and Office XP both rely on Component Object Model (COM) technology. However, Microsoft .NET development languages such as Microsoft Visual Basic .NET rely on Microsoft .NET technology instead of COM technology. Microsoft .NET allows code written in either the .NET or COM technologies to interoperate. Unfortunately, this interoperability framework does not account for all of the technology issues with software applications or components developed with COM. To address some of the specific technology issues when developing Visual Studio .NET solutions that interoperate with Office XP applications, Microsoft created the Office XP Primary Interop Assemblies.

What Are the Office XP Primary Interop Assemblies?

COM interop assemblies allow unmanaged (COM) code to be called from managed (.NET) code by using the Microsoft .NET Framework and the common language runtime. COM interop assemblies allow managed applications to bind to unmanaged types at compile time and provide information to the common language runtime about how the unmanaged types should be marshaled at run time.

While any number of COM interop assemblies may exist, only one COM interop assembly is designated as the primary interop assembly (PIA). The PIA contains the official description of the unmanaged types as defined by the publisher of those unmanaged types. The PIA usually also contains certain customizations that make the types easier to use from managed code. The PIA is always digitally signed by the publisher of the original unmanaged type.

Microsoft has created several PIAs that contain the official description of commonly-used Microsoft Office XP type libaries for products such as Microsoft Access 2002, Microsoft Excel 2002, Microsoft FrontPage® 2002, and so on. This group of PIAs is known as the Office XP Primary Interop Assemblies. Microsoft has customized the Office XP PIAs to make them easier for managed code to interoperate with the Office XP COM type libraries. Any Office XP COM interop assembly that is not provided as part of the Office XP PIAs, or any Office XP COM interop assembly that is generated by Microsoft Visual Studio .NET at design time, should be considered unofficial and their use should be avoided.

For general information about primary interop assemblies, see Primary Interop Assemblies (PIAs).

For more technical information about interoperating with unmanaged code, see:

• Interoperating with Unmanaged Code
• Advanced COM Interop

System Requirements

Minimum system requirements for the Office XP Primary Interop Assemblies (besides Microsoft Office XP) include Microsoft Visual Studio .NET for solution developers, or the Microsoft .NET Framework Redistributable for end users. For more information on these products, including additional system requirements, go to the Microsoft Developer Network (MSDN) Web site at http://msdn.microsoft.com/vstudio or http://msdn.microsoft.com/net.

Installing the Office XP PIAs

The Office XP PIAs are included as part of a self-extracting executable (.exe) file. To extract the Office XP PIAs to a file directory folder of your choice, simply open the .exe file available at the link in the beginning of this article. Once you have extracted all of the Office XP PIAs from the .exe file:

1. On a computer with Visual Studio .NET installed and the extracted Office XP PIAs, on the Start menu, click (All) Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and click Visual Studio .NET Command Prompt. The Visual Studio .NET Command Prompt window appears. This facilitates the use of the .NET Framework SDK tools.
2. In the Visual Studio .NET Command Prompt window, use the cd (change directory) command to change to the file directory in which the Office XP PIAs were extracted. For example, if you extracted the Office XP PIAs to a C:\Office XP PIAs\ folder, type cd C:\Office XP PIAs\.
3. In the Visual Studio .NET Command Prompt window, type register.bat, press ENTER, and wait while the Office XP PIAs are installed and registered.

Viewing the Installed Assemblies

To view the installed assemblies in the global assembly cache (GAC):

1. Open Microsoft Windows® Explorer.
2. Open the system root folder (for example, C:\WINDOWS\ or C:\WINNT\).
3. Open the \assembly folder.

- OR -

1. On the Start menu, click Run. The Run dialog box appears.
2. Type C:\WINDOWS\assembly\ or C:\WINNT\assembly\ (depending on the name of your computer's system root folder) in the Open box.
3. Click OK.
4. The Office XP PIAs are displayed along with all of the other assemblies registered in the GAC.

Referencing the Office XP PIAs

Unlike standard COM interop assemblies, you cannot browse to a PIA and set a reference to it as you would with other assemblies in the Microsoft Visual Studio .NET integrated development environment (IDE). Instead, you set a reference to an existing COM type library; if a PIA exists in the GAC for that COM type library, the PIA will be silently referenced instead. To demonstrate this behavior, perform the following steps on a computer with Visual Studio .NET and the Microsoft Word 2002 PIA installed:

1. Start Visual Studio .NET.
2. On the File menu, point to New, and click Project. The New Project dialog box appears.
3. Click the Visual Basic Projects folder in the Project Types pane.
4. Click Console Application in the Templates pane.
5. Type OfficeXPPIATest in the Name box.
6. Type or browse to a location in the Location list that is easy for you to remember.
7. Click OK to create the solution.
8. On the Project menu, click Add Reference. The Add Reference dialog box appears.
9. Click the COM tab.
10. Select the Microsoft Word 10.0 Object Library entry in the list of COM type libraries.
11. Click Select to select the Word object library entry.
12. Click OK to add the reference.
13. In the Solution Explorer window, in the References folder, click the Word reference.
14. In the Properties window, notice that the Path property is set to a string similar to C:\WINDOWS\assembly\GAC\Microsoft.Office.Interop.Word\...\Microsoft.Office.Interop.Word.dll. This indicates that the Word PIA is being used instead of forcing Visual Studio .NET to create its own COM interop assembly.

One you have successfully set a reference to a specific Office XP PIA, you can use it just like any other COM interop assembly. For example, with the Microsoft PowerPoint® 2002 PIA, you can type Imports Microsoft.Office.Interop.PowerPoint at the beginning of a Microsoft Visual Basic® .NET code module to keep from typing Microsoft.Office.Interop.PowerPoint every time you want to reference a specific PowerPoint object or member.

For a list of all of the available namespaces, objects, and members associated with a specific Office XP PIA, go to the Visual Studio .NET Object Browser (on the View menu, point to Other Windows, and click Object Browser) after you have successfully set a reference to the Office XP PIA.

Distributing Solutions That Rely On the Office XP PIAs

You have several options to distribute a Visual Studio .NET solution that relies on one or more of the Office XP PIAs:

1. Have the end user of your solution manually install the required Office XP PIAs on their computer before running your solution. This option is only recommended for technically advanced end users. See the Installing the Office XP PIAs section above for details.
2. Place the required Office XP PIAs in the same directory as your solution and distribute your solution and the Office XP PIAs as a single unit. This option is only recommended for simple solution deployments, such as copying solutions from one file directory folder to another across a computer network. The main disadvantage with this option is that multiple copies of the same Office XP PIAs may be installed on end users' computers, which reduces these computers' available hard disk space.
3. Install the required Office XP PIAs on end users' computers through the use of a Visual Studio .NET Setup project. This option is recommended for most deployments as it automatically installs and registers the required Office XP PIAs, as well as reduces the number of duplicate Office XP PIAs on end users' computers.

These first and second options are straightforward and are self-explanatory. To demonstrate and practice the third option (using a Visual Studio .NET Setup project), you will need two computers, one computer with Visual Studio .NET and the Office XP PIAs installed, and another computer with Visual Studio .NET or the Microsoft .NET Framework Redistributable installed but the Office XP PIAs are not installed.

On the computer with Visual Studio .NET and the Office XP PIAs installed:

First, create the executable project.

1. Create a Visual Basic .NET console application solution as described in steps 1 through 12 of the Referencing the Office XP PIAs section above.

2. Add the following code to the Module1.vb file:

   Module Module1
   
       Sub Main()
   
           ' Purpose: Tests the Microsoft Word 2002 primary
           ' interop assembly (PIA).
   
           Dim wdApp As New Microsoft.Office.Interop.Word.Application()
   
           Console.WriteLine("The version of Microsoft Word installed " & _
               "on this computer is " & wdApp.Version & ".")
           Console.ReadLine()
   
       End Sub
   
   End Module
   

Next, create the Setup project.

1. Right-click the solution in the Solution Explorer window, point to Add, and click New Project. The Add New Project dialog box appears.
2. Click the Setup and Deployment Projects folder in the Project Types pane. Click Setup Project in the Templates pane.
3. Type OfficeXPPIATestSetup in the Name box.
4. Type or browse to a location in the Location list that is easy for you to remember.
5. Click OK to add the OfficeXPPIATestSetup project to the OfficeXPPIATest solution.

Next, add the Setup project to the build.

1. In the Solution Explorer window, right-click OfficeXPPIATestSetup, and click Properties. The OfficeXPPIATestSetup Property Pages dialog box appears.
2. Click Configuration Manager. The Configuration Manager dialog box appears.
3. In the Project Contexts list, for the OfficeXPPIATestSetup entry, check the Build box.
4. Click Close to close the Configuration Manager dialog box.
5. Click OK to close the OfficeXPPIATestSetup Property Pages dialog box.

Next, add the executable project output to the Setup project.

1. In the Solution Explorer window, right-click OfficeXPPIATestSetup, point to Add, and click Project Output. The Add Project Output Group dialog box appears.
2. Accept the default settings by clicking OK. The Add Project Output Group dialog box closes.

Next, add the Word 2002 PIA to the Global Assembly Cache output folder.

1. In the Solution Explorer window, right-click OfficeXPPIATestSetup, point to View, and click File System. The File System panes appear.
2. Right-click File System on Target Machine, point to Add Special Folder, and click Global Assembly Cache Folder. The Global Assembly Cache Folder is added to the File System on Target Machine folder list.
3. In the Project Explorer window, right-click Word.dll, and click Properties. The Property window appears.
4. In the Property window, in the Folder box, click the ellipses (...) button. The Select Folder dialog box appears.
5. Click Global Assembly Cache Folder, and click OK to close the Select Folder dialog box.

Next, exclude unneeded dependencies from the Setup project.

1. In the Project Explorer window, right-click MSWORD.OLB, and check Exclude. A strikeout symbol appears next to the MSWORD.OLB dependency.
2. Repeat the previous step for the Office.dll and stdole.dll dependencies.

Now, build the solution.

1. On the Build menu, click Build Solution. Wait while the solution is built.
2. When the solution is finished building, copy all of the files in the <Project Location>\OfficeXPPIATestSetup\Debug\ folder on the computer with Visual Studio and the Office XP PIAs installed, to a location accessible the computer that does not have the Office XP PIAs installed. There should be five files in the accessible location: InstMsiA.exe, InstMsiW.exe, OfficeXPPIATestSetup.msi, Setup.exe, and Setup.ini.

On another computer that has Visual Studio .NET or the Microsoft .NET Framework Redistributable installed but does not the Office XP PIAs installed:

1. Run the Setup.exe file that was copied from the <Project Location>\OfficeXPPIATestSetup\Debug\ folder on the first computer. The OfficeXPPIATestSetup Wizard appears.
2. Click Next. The SelectInstallation Folder page appears.
3. Click Next. The Confirm Installation page appears.
4. Click Next, and wait while the OfficeXPPIATestSetup.exe program is installed.
5. When the Installation Complete page appears, click Close.
6. Locate and run the OfficeXPPIATest.exe file. The message The version of Microsoft Word installed on this computer is 10.0 appears.
7. Press any key to end the program and complete this exercise.

Known Issues

We have compiled a list of known issues associated with developing solutions that rely on the Office XP PIAs.

Sample Walkthrough: Exporting Excel 2002 Worksheet Data to a .NET Windows Form ListBox Control

This sample walkthrough demonstrates how to use Visual Studio .NET, the Excel 2002 PIA, and Excel 2002 to get data from an Excel worksheet and place the data in a control on a .NET Windows form.

To complete this sample walkthrough, you must have the following items installed on the same computer:

• Microsoft Visual Studio .NET
• Microsoft Excel 2002
• Microsoft Excel 2002 primary interop assembly (included with the Office XP Primary Interop Assemblies)
• The sample SOLVSAMP.XLS file that is included with Excel 2002.

First, create the Visual Basic .NET Windows Application project.

1. Start Visual Studio .NET.
2. On the File menu, point to New, and click Project.
3. In the Project pane, click Visual Basic Projects.
4. In the Templates pane, click Windows Application.
5. In the Name box, type ExcelPIATest.
6. Click OK.

Next, set a reference to the Excel 2002 primary interop assembly.

1. On the Project menu, click Add Reference.
2. Click the COM tab.
3. In the list of components, double-click Microsoft Excel 10.0 Object Library, and then click OK.

Next, ensure that the project references the correct assembly.

1. In the Solution Explorer window, in the References folder, right-click Excel, and then click Properties.
2. Make sure that the Path property is set to something like C:\WINDOWS\assembly\GAC\Microsoft.Office.Interop.Excel\...\Microsoft.Office.Interop.Excel.dll.

Note   If the Path property is set to something like C:\Visual Studio Projects\ExcelPIATest\obj\Interop.Excel.dll, then the Excel 2002 PIA is not installed correctly.

Next, customize the Windows form and add code.

1. Place a ListBox control and a Button control onto Form1. Do not rename the controls or the form.

2. Double-click the Button control, and type or copy the following code:

   Private Sub Button1_Click(ByVal sender As System.Object, _
           ByVal e As System.EventArgs) Handles Button1.Click
   
       Dim xlApp As New Microsoft.Office.Interop.Excel.Application()
       Dim objWorkbook As Microsoft.Office.Interop.Excel.Workbook
       Dim objWorksheet As Microsoft.Office.Interop.Excel.Worksheet
       Dim objRange As Microsoft.Office.Interop.Excel.Range
       Dim intRow As Integer
       Dim intCell As Integer
       Dim strRow As String
   
       ' Change the path to SOLVSAMP.XLS to match the path on your computer.
       objWorkbook = xlApp.Workbooks.Open _
           ("C:\Program Files\Microsoft Office\Office10\Samples\SOLVSAMP.XLS")
       objWorksheet = objWorkbook.Worksheets.Item("Quick Tour")
       objRange = objWorksheet.Range("A2", "F16")
   
       For intRow = 1 To 15
   
           For intCell = 1 To 6
   
               strRow = strRow & objRange.Cells(intRow, intCell).value & vbTab
   
           Next intCell
   
           Me.ListBox1.Items.Add(strRow)
           strRow = ""
   
       Next intRow
   
   End Sub
   

Last, run and test the solution.

1. On the Debug menu, click Start.
2. Click Button1. The ListBox control displays data from the SOLVSAMP.XLS file.

More Information

For more information on developing Microsoft Office XP solutions with Microsoft Visual Studio .NET, please see the following technical articles:

General Information

• Introducing .NET to Office Developers
• Microsoft Office and .NET Interoperability
• Developing Microsoft Office Solutions Using C#
• Working with ADO.NET Datasets in Microsoft Office

Microsoft Office XP COM Add-Ins

• Creating Office Managed COM Add-Ins with Visual Studio .NET
• Deployment of Managed COM Add-Ins in Office XP
• Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP

Microsoft Excel 2002

• Building Excel Real-Time Data Components in Visual Basic .NET

Microsoft Access 2002

• Unlocking Microsoft Access Data with ADO.NET

Microsoft Office XP Smart Tags

• Building Smart Tags in Microsoft Visual Basic .NET
• Integrating Office XP Smart Tags with the Microsoft .NET Platform
• Using the Smart Tag Shim Solution to Deploy Managed Smart Tags in Office XP

Microsoft Office XP and XML Web Services

• Integrating XML Web Services Into Microsoft Office Solutions
• Consuming XML Web Services with FrontPage
• How to Create and Deploy XML Web Services Using Visual Studio .NET and Office XP
• Excel Investor's Assistant Demo (Download)