Office XP Primary Interop Assemblies Readme File

Copyright (c) 2002 Microsoft® Corporation. All rights reserved.

This document provides information about the Microsoft Office XP Primary Interop Assemblies.

Contents

What are the Office XP Primary Interop Assemblies?
Included assemblies
System requirements
Installing and uninstalling the Office XP PIAs
Viewing the installed assemblies
Referencing the Office XP PIAs
Distributing solutions that rely on the Office XP PIAs
Known issues

What are the Office XP Primary Interop Assemblies?

Component Object Model (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 for a given type library, 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 are 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.

Included assemblies

The Office XP PIAs include the following assemblies:

• adodb.dll
• dao.dll
• Microsoft.Office.Interop.Access.dll
• Microsoft.Office.Interop.Excel.dll
• Microsoft.Office.Interop.FrontPage.dll
• Microsoft.Office.Interop.FrontPageEditor.dll
• Microsoft.Office.Interop.Graph.dll
• Microsoft.Office.Interop.Outlook.dll
• Microsoft.Office.Interop.OutlookViewCtl.dll
• Microsoft.Office.Interop.Owc.dll
• Microsoft.Office.Interop.PowerPoint.dll
• Microsoft.Office.Interop.Publisher.dll
• Microsoft.Office.Interop.SmartTag.dll
• Microsoft.Office.Interop.Visio.dll
• Microsoft.Office.Interop.Word.dll
• Microsoft.Vbe.Interop.dll
• mscomctl.dll
• msdatasrc.dll
• office.dll
• stdole.dll

System requirements

Minimum system requirements for the Office XP Primary Interop Assemblies 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 and uninstalling 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. Once you have extracted all of the Office XP PIAs from the .exe file, you must individually install each of the Office XP PIAs that you want to reference from Microsoft Visual Studio .NET. To install the Office XP PIAs, you must individually install a copy of each Office XP PIA in the computer's global assembly cache (GAC), and then register all of that Office XP PIA's declared types, or you can run a batch file that automatically installs all of the Office XP PIAs in the computer's GAC and registers all of the Office XP PIAs' declared types.

To install the Office XP PIAs

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\

   and press ENTER.
3. To install all of the Office XP PIAs at once, type

   register.bat

   and press ENTER.

   You can skip steps 4 through 6 of this procedure, as all of the Office XP PIAs are automatically installed in the computer's GAC and all of the Office XP PIAs' declared types are registered.
   

4. If you want to install an individual Office XP PIA, type

   gacutil -i assembly_file_name

   and press ENTER, where assembly_file_name is the file name of the Office XP PIA.
   
   For example, assuming that you are in the file directory in which the Office XP PIAs were extracted, and you want to install the Microsoft Word 2002 PIA only, type

   gacutil -i Microsoft.Office.Interop.Word.dll

   and press ENTER.
5. Next, in the Visual Studio .NET Command Prompt window, type the regedit /s command and the name of the Office XP PIA file name along with a .reg file extension. For example, if the Office XP PIA file name is Microsoft.Office.Interop.Word.dll, and you are in the file directory in which the Office XP PIAs were extracted, type

   regedit /s Microsoft.Office.Interop.Word.dll.reg

   and press ENTER.
6. Repeat steps 4 and 5 above for all of the Office XP PIAs on which your application depends, as described in the following table:

Note  Failure to follow the above steps will cause Visual Studio .NET to build incompatible COM interop assemblies at design time.

To uninstall the Office XP PIAs

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. For each Office XP PIA that you want to uninstall, type

   gacutil /u assembly_display_name

   and press ENTER. In this case, assembly_display_name is the PIA's global assembly cache display name. For example, to uninstall the Word 2002 PIA from the GAC, type

   gacutil /u Microsoft.Office.Interop.Word

   and press ENTER.
   
   Note that this step does not remove any registry entries. If you want to remove registry entries associated with the assembly, you must do so manually by using a program such as the Registry Editor.

Caution   Modifying the Microsoft Windows® Registry in any manner always carries some degree of risk. Incorrect modification can cause serious problems that may require you to reinstall your operating system. It is a good practice to always back up a computer's registry first before modifying it. If you are running Microsoft Windows NT® or Microsoft Windows 2000, you should also update your Emergency Repair Disk (ERD).

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.

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 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\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 in your project's location.

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 and uninstalling 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 Office XP, Visual Studio .NET, and the Office XP PIAs installed, and another computer with Office XP and the 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:

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

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 Microsoft.Office.Interop.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, add the Word 2002 PIA registry entries to the Registry on Target Machine pane.

1. In the Solution Explorer window, right-click OfficeXPPIATestSetup, point to View, and click Registry. The Registry on Target Machine panes appear.
2. Right-click Registry on Target Machine, and click Import. The Import Registry File dialog box appears.
3. Locate and click the Microsoft.Office.Interop.Word.dll.reg file in the folder in which you extracted the original Office XP PIAs, and then click Open. The Word 2002 PIA registry entries are added, and the Import Registry File dialog box disappears.

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 has Office XP and Visual Studio .NET or the Microsoft .NET Framework Redistributable installed but the Office XP PIAs are not 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 Office XP and 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 Select Installation 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

For a list of known issues associated with developing solutions that rely on the Office XP PIAs, go to the MSDN Office Developer Center at http://msdn.microsoft.com/office.