Understanding Office Primary Interop Assembly Classes and Interfaces

Understanding Office Primary Interop Assembly Classes and Interfaces

The Office Primary Interop Assemblies (PIAs) expose many classes and interfaces that were previously hidden. Most of these classes and assemblies are displayed in the Object Browser in Visual Studio; however, some do not appear. Although these classes and interfaces can be confusing at first glance, it helps to understand the relationships between them, and how they are used.

This topic outlines some key points to keep in mind while working with PIA classes and interfaces.

Application Classes and Interfaces

Although the Object Browser displays Application interfaces for the Microsoft Word and Microsoft Excel PIAs, it does not directly expose Application classes for Word and Excel. However, when you use the Application interface to instantiate an Application object, the common language runtime internally uses the Application class.

For example, the following code uses the Excel Microsoft.Office.Interop.Excel.Application interface. At run time, it uses the Application class to instantiate an Excel Application object and open a worksheet.

Private Sub btnRunExcel_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnRunExcel.Click

    Dim xl As Microsoft.Office.Interop.Excel.Application
    xl = New Microsoft.Office.Interop.Excel.Application
    Dim wb As Microsoft.Office.Interop.Excel.Workbook
    wb = xl.Workbooks.Add()
    Dim ws As Microsoft.Office.Interop.Excel.Worksheet
    ws = wb.ActiveSheet

    xl.Visible = True

End Sub

classidClass Classes

It is possible to use a classidClass class, such as the ApplicationClass class in Microsoft Word and Microsoft Excel, or the WorkbookClass or WorksheetClass classes in Microsoft Excel, to instantiate an object. However, this practice should be avoided.

Using these classes has the potential to cause ambiguities if some members share the same name. For example, Microsoft Word exposes both an Microsoft.Office.Interop.Word._Application.Quit(System.Object,System.Object,System.Object) method and an Microsoft.Office.Interop.Word.ApplicationEvents4_Event.Quit event. These ambiguities can generate a compiler error.

Instead, use the exposed interface for a class—such as the Application, Microsoft.Office.Interop.Excel.Workbook, or Microsoft.Office.Interop.Excel.Worksheet interface—to instantiate an object of that class. The following Visual Basic example uses the Microsoft.Office.Interop.Word.Application interface with the Quit method in Microsoft Word.

Private wd As Microsoft.Office.Interop.Word.Application

Private Sub btnRunWord_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnRunWord.Click
    wd = New Microsoft.Office.Interop.Word.Application
    wd.Visible = True
End Sub

Private Sub btnQuitWord_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnQuitWord.Click
    wd.Quit()
    wd = Nothing
End Sub

_classid Interfaces

To avoid the potential for ambiguities, members of classes in which some members share the same name are displayed in the Object Browser as members of the corresponding _classid interface. For example, Application class members are displayed as members of the _Application interface. Although they are not displayed as members of their class interface in the Object Browser, internally they are associated with the class when you use them in code.

The following table lists the classes that have corresponding _classid interfaces.

Event Interfaces

The classidEventsx interfaces displayed in the Object Browser, such as ApplicationEvents4 in the Word PIA, map directly to interfaces in the original Component Object Model (COM) type libraries and expose a set of corresponding methods. However, these methods are not directly usable.

Similarly, the PIAs implement ClassIdEventsx_SinkHelper classes, such as ApplicationEvents4_SinkHelper, which expose methods and delegates corresponding to each event. These methods and delegates are also for internal use only.

To work with events, use the ClassIdEventsx_Event interfaces, such as ApplicationEvents4_Event, which are also based on the classidEventsx interfaces. In addition, the PIAs implement classidEventsx_eventEventHandler delegates for each event. Use these delegates to create event handlers.

For more information, see Understanding Office Primary Interop Assembly Events.

Dual Interfaces

The Office PIAs implement a dual interface for many interfaces, with each interface having a corresponding Iinterfaceid interface. For example, the AppEvents interface in the Excel PIA has a corresponding IAppEvents interface. The Iinterfaceid interfaces are for internal use only and can be ignored.

See Also

Concepts

Overview of Classes and Interfaces in the Office Primary Interop Assemblies
Office Primary Interop Assembly Reference Documentation Conventions
Office Primary Interop Assembly Code Examples