Office XP Primary Interop Assemblies Known Issues

  • Article

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, Frank C. Rice
Microsoft Corporation

September 2002

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

Summary: This article provides a digest of known issues regarding the Office XP Primary Interop Assemblies (PIAs).

Contents

Reregister the Office XP PIAs After an Office Repair or Modification
In Most Cases, Do Not Declare Objects Based on Office XP PIA Types that End with the Name "Class"
Accessing a Generic Outlook Item Object with Option Strict On Returns a Compile Error
Cannot Refer to a Shape Range Unless the Range Contains Only One Shape
Office XP VBA Language Reference Help is Not Available from Visual Studio .NET
Microsoft Data Analyzer PIAs Are Not Included in the Office XP PIAs
Known Issues from Microsoft Product Support Services
Special Attribute Needed When an Office Web Component 10 Control is Added to a Visual Studio .NET Form
An Error Can Occur When Running Excel 2002 on a Computer Configured for a Different Locale
Default Properties Not Supported in Visual Basic .NET
Releasing COM objects with the Nothing Keyword Doesn't Always Release Their Memory
Declaring Certain Object Types Will Generate Ambiguous Name Errors in Outlook
An Error Results When Attempting to Set the FileDialog.Filter Index Property
The Default Item Property Is No Longer Available in C# Code Implementing Office XP PIAs
using Directive in C# Requires Full PIA Name
Change to the Readme File

Reregister the Office XP PIAs After an Office Repair or Modification

Occasionally, it may be necessary to perform the Microsoft® Office XP PIA installation again. This is necessary when the user or any of the Office applications initiate an Office setup action that causes the Office type library registration to be rewritten. If you notice that you are unable to reference the Office XP PIAs from Microsoft Visual Studio® .NET, then performing the installation steps again as described in the Office XP PIA Readme will most likely solve the problem.

In Most Cases, Do Not Declare Objects Based on Office XP PIA Types that End with the Name "Class"

Many of the Office XP PIA objects end with the name Class, for example:

  • In the Microsoft Access 2002 PIA, the AllDataAccessPagesClass and OptionButtonClass objects exist.
  • In the Microsoft Outlook® 2002 PIA, the ContactItemClass and OutlookBarPaneClass objects exist.

Objects ending with the suffix Class should only be used when you are working with events or object members with ambiguous names. Otherwise, use objects that do not end with the suffix Class. For example, instead of declaring an object of type AllDataAccessPagesClass, declare an object of type AllDataAccessPages instead, unless you are working with events or object members with ambiguous names (for example, the Quit event and the Quit method of the Word Application object).

Accessing a Generic Outlook Item Object with Option Strict On Returns a Compile Error

Several Microsoft Outlook accessor methods and properties return a generic Object type. For example, the Item method of the Items, Pages, Panes, PropertyPages, Results, and Selection objects, and the Item property of the Link and Reminder objects, all return an object of type Object representing a generic Outlook Item object. In Microsoft Visual Basic® 6.0, the compiler can implicitly coerce the returned Object object into an Outlook Item object as needed when your code iterates over a collection of Outlook items by using the For Each…Next construct. This is the default behavior in Microsoft Visual Basic .NET as well. However, if for some reason the Option Strict On setting is used in this scenario, the error Option Strict On disallows late binding will occur when the code is compiled, and the build will fail.

To view the Option Strict setting:

  1. In Visual Studio .NET, open an existing Visual Basic .NET solution.
  2. In the Solution Explorer window, right-click a Visual Basic .NET project, and click Properties. The Project Property Pages dialog box appears.
  3. Open the Common Properties folder, if it is not already open.
  4. Click Build.
  5. Note the setting in the Option Strict list. If the value is set to Off, then implicit type conversion is allowed. If the value is set to On, the error Option Strict On disallows late binding will occur when implicit type conversion code is compiled.

Cannot Refer to a Shape Range Unless the Range Contains Only One Shape

The Word and Microsoft PowerPoint® Shapes collections' Range method can take, as a possible input parameter, a Variant array of Shape objects representing a collection of shapes in a range. Because the .NET Framework no longer uses the Variant data type, and cannot coerce the Variant array into an array of Object objects, an error occurs unless the Range method refers to only one shape.

Microsoft Visio Known Limitations

Query Events

When using the Microsoft Visio 2002 primary interop assembly (Microsoft.Office.Interop.Visio.dll), you can only handle query events using Visio event objects created with the AddAdvise method. (Query events are Visio Automation events prefixed with the word Query).

For more information about query events, event objects, or the AddAdvise method, see the Microsoft Visio Automation Reference included with Visio 2002 Professional, Visio 2002 Standard, and the Visio 2002 SDK, and available in the Microsoft Developer Network (MSDN) Online Library.

Compatibility with the Visio 2002 SDK PIA

The Visio 2002 PIA (Microsoft.Office.Interop.Visio.dll) has a different name and namespace than the Visio 2002 SDK PIA (Microsoft.Visio.Interop.dll).

The Visio 2002 PIA includes several important bug fixes, and is installed in the global assembly cache (GAC). When using the Visio SDK PIA, Page and Application properties and parameters in methods appear as IVPage and IVApplication (respectively) types. In the Visio 2002 PIA, Page and Application properties and parameters are correctly typed as Page and Application. In addition, when using the Visio 2002 PIA, you will not be able to start Visio in an invisible state.

It is strongly recommended that you use the Visio 2002 PIA included in the Office XP PIAs, not the Visio 2002 SDK PIA.

All managed code components that share Visio objects must use the same Visio PIA. If you have built a managed code application using the Visio 2002 SDK PIA (Microsoft.Visio.Interop.dll), you must modify your application to reference the Visio 2002 PIA (Microsoft.Office.Interop.Visio.dll) included in the Office XP PIAs instead.

Starting Visio in an Invisible State

When using the Visio 2002 PIA, you will not be able to start Visio in an invisible state.

System.Array Objects

In the Visio 2002 PIA, SAFEARRAY types in the Visio Object Model have been converted to a System.Array type. System.Array is the base class of all Visual Basic .NET arrays. A System.Array can represent anything a SAFEARRAY type can represent.

Note   Using these generic arrays means that the array is now loosely typed and no longer strongly typed.

The CreateInstance method of the System.Array object allows you to control the bounds, dimension and length of the array. You can access elements of a System.Array by using methods such as GetValue and SetValue. You can also get and set array elements by first casting the System.Array type to a strongly managed array of an appropriate type. You will not be able to do this type of casting with an array with non-zero lower bounds. This affects the SAFEARRAY types returned by Visio for the following properties and methods. In each case, Visio creates a one dimensional SAFEARRAY with the lower bound equal to 1.

  • Event.GetFilterObjects
  • Event.GetFilterCommands
  • Event.GetFilterSRC
  • Document.SnapAngles
  • Document.EmailRoutingData
  • Application.AvailablePrinters

Office XP VBA Language Reference Help is Not Available from Visual Studio .NET

The Office XP VBA Language Reference Help does not ship with the Office XP PIAs. Additionally, the VBA Language Reference Help that ships with the Office XP applications currently is available in the Microsoft HTML Help 1.x format only. Because Visual Studio .NET relies on the Microsoft Help 2.0 format for both content display and IntelliSense®, the Office XP VBA Language Reference Help is not integrated with Visual Studio .NET. To view the Office XP VBA Language Reference Help files, open the appropriate compiled Help (.chm) file from Microsoft Windows® Explorer or set a reference to the appropriate type library in the Office Visual Basic Editor and access the .chm file from the Visual Basic Editor's Object Browser.

Microsoft Data Analyzer, Microsoft MapPoint, and Microsoft Project PIAs Are Not Included in the Office XP PIAs

The PIAs for the Microsoft Data Analyzer, Microsoft MapPoint, and Microsoft Project were not ready at the time that the Office XP PIAs were released, and therefore are not available as part of the Office XP PIAs.

Known Issues from Microsoft Product Support Services

Special Attribute Needed When an Office Web Component 10 Control is Added to a Visual Studio .NET Form

ActiveX® controls, including Office Web Components (OWC), need a managed code wrapper in order to be placed on a Windows Form. This wrapper is called an ActiveX Interop Assembly (AXIOP) and Visual Studio .NET generates this automatically for you when you import a control into the Toolbox. This AXIOP takes care of communicating with the control by providing a number of events. For OWC, this assembly appears as Interop.AxOWC10 or AxOWC10.

An issue arises when an OWC 10 control is placed on a Visual Studio .NET Form in that OWC fires its events differently than other types of controls. OWC always provide its events via a generic interface (IDispatch) instead of using a specific interface (such as its event sink interface). In other words, it uses the same pointer as the sink interface, but asks for a dispatch. This causes the common language runtime (CLR) to generate a class with internal DISPID's, and not the ones defined in the sink interface.

The solution involves adding an attribute to the EventSink class in the AXIOP (using the /source option in AXIMP.EXE). This attribute will tell the CLR to always look at the sink interfaces. The following code demonstrates this change:

[System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.None)]

public class AxChartSpaceEventMulticaster : OWC10.IChartEvents {. . .}

Note   This change is needed for each event sink interface in the assembly.

In addition, the knowledge base article HOW TO: Handle Events for the Office XP Spreadsheet Component on a Windows Form in Visual C# .NET (Q319341) gives a little more background and explains a workaround for this issue specifically for the OWC.

An Error Can Occur When Running Excel 2002 on a Computer Configured for a Different Locale

An error can occur if:

  • You use early binding to call an Office XP method in Visual Studio .NET, and
  • The method requires an LCID (locale identifier) in Visual Studio .NET, and
  • You are running a language version of Excel 2002 on a computer whose regional settings are configured for a different language.

The knowledge base article BUG: "Old Format or Invalid Type Library" Error When Automating Excel 2002(Q320369) provides various workarounds that can be adapted to work for this issue.

Default Properties Not Supported in Visual Basic .NET

Unlike Visual Basic 6.0, Visual Basic .NET does not support default properties except in special circumstances when the property has arguments. For example, a Label control has the default Caption property. In Visual Basic 6.0, you could do the following:

Dim L1 as Label

Dim L2 as Label

L1 = "Important"

L2.Caption = "Important"

In Visual Basic .NET, the Text property replaces the Caption property for the Label control. Therefore, you can rewrite the preceding example as follows:

Dim L1, L2 as Label 'Both L1 & L2 are type Label in Visual Basic .NET.

L1.Text="Saving" 'Assign the Text property of L1.

L2.Text=L1.Text 'Copy Text property of L1 to Text property of L2.

L2=L1 'Copy the L1 Label object to the L2 Label object.

More information can be found in the knowledge base article INFO: Visual Basic .NET Does Not Support Default Properties(Q311328).

Releasing COM objects with the Nothing Keyword Doesn't Always Release Their Memory

Releasing Component Object Model (COM) objects by using the Nothing keyword in Visual Basic .NET doesn't necessarily release the memory associated with that object. This may result in unexpected behavior such as if you declare a new object with the same data type as the object you set to Nothing, Visual Basic .NET might use the old object instead.

Essentially, the common language runtime may hold onto a COM object even though the managed code has released all pointers and even set the pointers to Nothing. If this occurs, it's possible that Visual Basic .NET will reuse the same COM object when the managed code asks for the COM object again.

One possible workaround is to call Marshal.ReleaseCOMObject which would release just that specific COM object; however, if the managed code had tried to handle that object by using the WithEvents keyword, you would instead need to call the GC.Collect() method. Unfortunately, the GC.Collect() method can cause some significant performance issues as it attempts to reclaim all memory associated with the various COM object. For this reason, it is recommended that the GC.Collect() method be used sparingly.

Declaring Certain Object Types Will Generate Ambiguous Name Errors in Outlook

Declaring certain types of event-aware objects in Outlook will generate 'ambiguous name' errors. For example, the Close method is used across the interfaces Microsoft.Office.Interop.Outlook._Explorer and Microsoft.Office.Interop.Outlook.ExplorerEvents_10_Event. Thus, the following code will generate an 'ambiguous name' error:

Module Class1
   Public WithEvents m_olExplorer As Outlook.Explorer

   'Ambiguous Name problem for Handles m_olExplorer.Close.
   Public Sub m_olExplorer_Close() Handles m_olExplorer.Close 
   'Event Code here.
   End Sub
End Module

A workaround is to use the ExplorerClass, as in the following example:

Module Class1
   Public WithEvents m_olExplorer As Outlook.ExplorerClass
   'This fixes Ambiguous Name issue.
   Public Sub m_olExplorer_Close() Handles  _olExplorer.ExplorerEvents_Event_Close
      'Event code here.
   End Sub
End Module

An Error Results When Attempting to Set the FileDialog.FilterIndex Property

An unhandled exception of type System.ArgumentException occurs when trying to set the FileDialog.FilterIndex property for applications (such as Excel, Word, etc.). A fix will be available at a later date. The following code will generate an error:

Imports Microsoft.Office.Interop.Word
Imports Microsoft.Office.Core
Module Module1
   ' Global Constants\Variables.
   Dim oFileDialog As FileDialog
        
   Sub main()
      ' Local Constants\Variables.
      ' Setup Test Object.
      Dim objHost As ApplicationClass = New Application()
      Dim shtActValue As Short
      Dim shtSetValue As Short

      oFileDialog = objHost.FileDialog(MsoFileDialogType.msoFileDialogFilePicker)
      shtActValue = oFileDialog.FilterIndex
      shtSetValue = 2
      oFileDialog.FilterIndex() = shtSetValue
   End Sub
End Module

A workaround for this issue is to first add a filter to the FileDialog object, and then add one or more values to the filter such as in the following code:

Sub main()
   Dim objHost As ApplicationClass = New Application()     
   Dim oFileDialog As FileDialog
   Dim shtActValue As Short
   Dim shtSetValue As Short

   oFileDialog = objHost.FileDialog(MsoFileDialogType.msoFileDialogFilePicker)
   shtActValue = oFileDialog.FilterIndex
   shtSetValue = 2
   oFileDialog.Filters.Add("Images", "*.gif; *.jpg; *.jpeg", 1)
   oFileDialog.Filters.Add("Documents", "*.doc", 2)
   oFileDialog.FilterIndex() = shtSetValue
End Sub

To avoid running into this issue in the future, it is recommended that you first verify that at least one filter has been added to the FileDialog object before you attempt to set the FileDialog.FilterIndex() property. You can do this simply by using the Get method on the FileDialog.FilterIndex() property, and making sure that it does not return 0.

The Default Item Property Is No Longer Available in C# Code Implementing Office XP PIAs

In order to streamline the referencing of some objects and collections, the Office XP PIAs implement a default Item property. In Visual Basic .NET projects implementing PIAs, this permits developers to use the following syntax:

wrdTable.Columns(1).SetWidth(51, Word.WdRulerStyle.wdAdjustNone)

instead of:

wrdTable.Columns.Item(1).SetWidth(51, Word.WdRulerStyle.wdAdjustNone)

In addition, the Item property also appears in the Object Browser in a Visual Basic .NET project.

C#, however, treats the default property as an Indexer which means that you must

refer to an instance of an object by using the [] syntax rather than the property syntax illustrated above. Previously, C# code implementing the earlier Interop Assemblies used the Item method. In the Office XP PIAs, the Item method was changed to a property which C# implements as an Indexer. Thus, in C# projects implementing PIAs, instead of using code like the following:

wrdTable.Columns.Item(1).SetWidth(51, Word.WdRulerStyle.wdAdjustNone);

You must use the following C# syntax:

wrdTable.Columns[1].SetWidth(51, Word.WdRulerStyle.wdAdjustNone);

Unlike in Visual Basic .NET, the Item property isn’t available in C# and doesn't appear in the Object Browser in a C# project (with the exception of the Excel PIA). Therefore, any legacy C# code written to include the Item method will not work in the Office XP PIAs (with the exception of Excel).

Note   Indexers permit instances of a Class or Struct to be indexed in the same way as arrays. For more information on Indexers, see the C# Programmer's Reference.

using Directive in C# Requires Full PIA Name

In order to use the using directive in C#, you need to include the entire PIA assembly’s name. For example, to use the directive with the Excel PIA, you would

type the following:

using Excel = Microsoft.Office.Interop.Excel;

You can then refer to objects in that PIA with the shorter "Excel" qualifier rather than the full name. For example, you could type:

Excel.Application objApp;

The full statement without using the using directive would be: Microsoft.Office.Interop.Excel.Application objApp2;

Note   The Imports directive (the Visual Basic .NET equivalent of the using directive) in Visual Basic .NET projects allows a partial name. For example, the following statement works correctly in Visual Basic .NET:

Imports Microsoft.Office.Interop

Dim objApp as Excel.Application

Change to the Readme File

The following information should replace the existing paragraph in the section titled Distributing solutions that rely on the Office XP PIAs in the Readme file that is included in the Office XP PIA downloadable:

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.

    Note   Perform the next step only if the end user’s computer has Office XP and Visual Studio .NET installed. If the end user’s computer has Office XP and the Microsoft .NET Framework Redistributable installed but not Visual Studio .NET, you can skip this step.

  2. Repeat the previous step for the Office.dll and stdole.dll dependencies.