Troubleshooting Run Time Errors in Office Solutions

  • Article

You might encounter issues when you perform the following tasks at run time in Office solutions that were created in Visual studio:

  • Installing solutions

  • Loading or running solutions

  • Using specific properties, methods, and events in solutions

  • Customizing UI

  • Binding data to controls and caching data

  • Using the ServerDocument class

Installing Solutions

The Visual Studio Tools for Office runtime writes messages to the Event Viewer in Windows for all exceptions that are thrown when you install or uninstall Office solutions. You can use these messages to resolve installation and deployment problems. For more information, see Event Logging for Office Solutions.

You might encounter the following errors when installing Office solutions.

An Add-in Cannot Be Installed by Using the COM Add-Ins Dialog Box

If you try to use the COM Add-Ins dialog box in an Office application to install an add-in that you created by using the Office developer tools in Visual Studio, you will see the following error.

"your add-in name.dll is not a valid Office Add-in."

You cannot use the COM Add-Ins dialog box to install an add-in that you created by using the Office developer tools in Visual Studio. Instead, do one of the following:

  • If you are trying to run the add-in on your development computer, build the project and then start the Office application. Your add-in should load automatically. Alternatively, click Start Without Debugging on the Debug menu in Visual Studio. For more information, see Office Solution Build Process Overview.

  • If you are trying to debug the add-in on your development computer, press F5 or click Start Debugging on the Debug menu in Visual Studio. For more information, see Debugging in Application-Level Projects.

  • If you are trying to install the add-in on an end user computer, use ClickOnce or Windows Installer to deploy the add-in. For more information, see Deploying Office Solutions.

Solution Installs Successfully But FrameworkVersionMismatchException Is Reported in Event Viewer

When you install an Office solution that was created by using Visual Studio, you might see an error in the Event Viewer that refers to a Microsoft.VisualStudio.Tools.Applications.Deloyment.FrameworkVersionMismatchException being thrown. This exception does not indicate an actual error with the solution, and you can typically ignore it.

This exception is thrown and caught internally by the Visual Studio Tools for Office runtime when you install an Office solution that targets the .NET Framework 4 on a computer that has both the .NET Framework 3.5 and the .NET Framework 4 installed. The Visual Studio Tools for Office runtime uses this exception to determine which version of the common language runtime (CLR) to load for the solution.

Loading or Running Solutions

The Visual Studio Tools for Office runtime can write all errors that occur during startup to a log file or display each error in a message box. By default, these options are turned off. You can turn the options on by creating environment variables. For more information, see Debugging in Document-Level Projects and Debugging in Application-Level Projects.

You might encounter the following errors when Office solutions are loaded or run.

Common Language Runtime or Microsoft .NET Framework Could Not Be Loaded

The end user's computer must have the version of the .NET Framework that is targeted by the solution. For more information about versions of the .NET Framework that you can target in Office solutions, see Designing and Creating Office Solutions.

Assembly Cannot Be Found or Loaded

This problem causes the following error message to be displayed.

"The customization assembly could not be found or could not be loaded. You can still edit and save the document. Contact your administrator or the author of this document for further assistance."

To resolve this error, try the following options:

  • Check that the user has access to the assembly location and that the named assembly exists. For more information, see Assemblies in Office Solutions Overview.

  • If the assembly is available, check whether Word or Excel is running a customization, such as an add-in, smart tag, or smart document, that explicitly loaded the .NET Framework 1.1. To resolve the issue, disable any customizations that explicitly load the .NET Framework 1.1. This version of the .NET Framework cannot be loaded in the same application process with later versions of the .NET Framework. For more information, see In-Process Side-by-Side Execution.

    Note

    Smart tags are deprecated in Excel 2010 and Word 2010. For more information, see Smart Tags Overview.

  • Check whether an unhandled exception in the customization assembly is preventing the assembly from loading. Debug your solution with the debugger set to break on common language runtime exceptions, or with the Break when exceptions cross AppDomain or managed/native boundaries option selected in the Options dialog box. For more information, see How to: Handle Errors in Office Projects.

  • You can get additional troubleshooting information by setting environment variables that make the Visual Studio Tools for Office runtime display detailed error messages and write all actions to a log file. For more information, see Debugging in Document-Level Projects and Debugging in Application-Level Projects.

An Add-in Does Not Load or Is Disabled

There are several possibilities to check for if an application-level add-in does not load correctly:

  • If the Microsoft Office application quits unexpectedly or an error occurs while an add-in is initializing, the application might disable the add-in. For more information, see How to: Re-enable an Add-in That Has Been Disabled.

  • The Microsoft Office application might be running an add-in that explicitly loaded the .NET Framework 1.1. To resolve the issue, disable any add-ins that explicitly load the.NET Framework 1.1. This version of the .NET Framework cannot be loaded in the same application process with later versions of the .NET Framework. For more information, see In-Process Side-by-Side Execution.

  • You can get additional troubleshooting information by setting environment variables that make the Visual Studio Tools for Office runtime display detailed error messages and write all actions to a log file. For more information, see Debugging in Application-Level Projects.

Type Cannot Be Loaded

This problem causes the following error message to be displayed:

"Could not load type projectname from assembly assemblyname."

This message might appear if you obfuscate the code in your Office project. Obfuscating the code changes the names of all of the classes. However, the original class names are referenced in the manifest, and the obfuscator does not change the manifest.

To avoid this error, add the names of the generated classes in your project to the obfuscator's list of classes not to rename.

Office Document Opens With No Errors, But Code Does Not Execute

Reasons that the code does not run and no error messages appear include:

  • The Office primary interop assemblies (PIAs) are not installed in the global assembly cache, possibly because the .NET Framework is not installed on the computer, or because the PIAs were not installed during Office setup.

  • A Word document project is open in Visual Studio on the same computer. Close Visual Studio and re-open the document.

For more information, see Debugging in Document-Level Projects.

Using Specific Properties, Methods, and Events in Solutions

You might encounter the following issues related to specific properties, methods, and events in the Microsoft Office primary interop assemblies (PIAs) and the Visual Studio Tools for Office runtime.

DocumentChange Event Is Not Raised When a Document Is Opened in Word

The DocumentChange event is raised when the active document changes. Also, it is often raised when a document is opened. However, because of the different ways that Word can open documents (for example from a command line, from Windows Explorer, or from the File menu in Word), the DocumentChange event is not always raised when the document is opened. It should always be raised when the active document is changed after opening. If you want to perform actions when the document is opened, use the Startup event.

Excel Events Are Raised Differently in Internet Explorer than in Excel

If a workbook is hosted inside Internet Explorer, the events are raised in a different order than if the workbook is opened in Excel. In addition, some of the events are raised twice. If your solution includes Internet Explorer, test how the different event sequence affects your solution's operation.

New Event Is Not Raised When a Document Is Created from a Template

When you use a Command Prompt to open a Word template and create a new document, you must use the /z switch to raise the New event. Do not include a space after /z, or Word opens the template for editing instead of creating a new document based on the template. For example: winword.exe /z"mytemplate.dot"

This is similar to using the /t switch, with the addition that /z raises the New event.

Open Event Is Not Raised When an XML Worksheet Is Opened

If you base an Excel project on an existing non-native worksheet (such as Excel XML format), the Open event is not raised when the worksheet is opened.

BeforeClose Method Runs But User Keeps Workbook Open

It is possible for an end user to cancel the close operation of a workbook and continue to use your solution after the BeforeClose event handler has been called. This happens when the user makes changes in a worksheet and then takes an action to close the workbook without saving first. The BeforeClose event handler is called, and then the user is presented with a dialog box that has the option to cancel the close operation.

If you put code in the BeforeClose event handler that closes database connections or performs other clean-up actions, that code might be called while the user is still working with your solution.

Setting the Cancel Parameter of the SaveAs Dialog Returns Inaccurate Warning or Causes Word to Exit Unexpectedly

If you show the SaveAs dialog box from an event handler for the DocumentBeforeSave event and set the Cancel parameter to false, the application might exit unexpectedly. If you set the Cancel parameter to true, an error message appears indicating that Autosave has been disabled.

Close Method Causes Word and Excel to Exit Unexpectedly

When you call the Close method of a document or workbook from a modeless form, the application might exit unexpectedly. All open documents or workbooks will close and data might be lost. If Microsoft Office Outlook uses Word as its e-mail editor, all open e-mail messages might also close. This might also occur if you display Windows Forms or message boxes while handling the AppDomain.DomainUnload event.

To work around this problem, do not call the Close method from a modeless form or in an event for a modeless form. Instead, use the following procedures:

  • Use modal forms (for example by using ShowDialog instead of Show) if you must close the document from the form.

  • If you must use a modeless form, ensure that the modeless form is closed and that your form references are completely destroyed before attempting to close the document or workbook. The following code shows an example. To use this code, run it from the ThisDocument class in a document-level project for Word.

    Dim form1 As SampleForm

Sub OpenForm()
    form1 = New SampleForm
    form1.Show()  ' Show the form modelessly.
End Sub

Sub ForceShutdown()

    ' Completely close the form if it is still running.
    ' Note that hiding the form might not work by itself.

    If (Not form1 Is Nothing) Then
        form1.Close()
        form1.Dispose()
        form1 = Nothing
    End If

    Me.Close()
End Sub

    SampleForm form1;

private void OpenForm()
{
    form1 = new SampleForm();
    form1.Show();  // Show form modelessly.
}

private void ForceShutdown()
{
    // Completely close the form if it is still running.
    // Note that hiding the form might not work by itself.

    if (form1 != null)
    {
        form1.Close();
        form1.Dispose();
        form1 = null;
    }
    object saveChanges = Word.WdSaveOptions.wdSaveChanges; 
    this.Close(ref saveChanges, ref missing, ref missing);
}

For information about passing the parameter missing in C#, see Optional Parameters in Office Solutions.

InvalidCastException Is Thrown when Passing an Excel Host Control to a Method

Some methods and properties in Excel require that you pass them a native Office object. If the Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute attribute is set to false in a project that targets the .NET Framework 3.5 and you pass in a host control that is based on the native Office object, it throws an InvalidCastException. You can use the InnerObject property of host controls to pass the underlying native Office objects to these methods and properties. For more information about localization issues in Excel, see Formatting Data in Excel with Various Regional Settings.

Customizating UI

You might encounter the following errors related to specific types of UI customizations in Office solutions.

Windows Forms Controls Behave Unpredictably When the Excel Worksheet Window is Split

If you split a worksheet window that contains Windows Forms controls, the controls might not behave similarly in both windows. For example, if you run code to change the BackColor property of a TextBox on a worksheet, the change might appear in only one of the windows.

Cannot Add Custom Property Pages in Outlook Add-ins

If your Outlook add-in creates a custom property page for the Options dialog box of Outlook or the Properties dialog box of an Outlook folder, you must explicitly make the custom property page visible to COM (by default, the assembly is not visible to COM). Otherwise, your add-in will fail create the custom property page, and you might receive a COMException while debugging your add-in.

There are two ways to make a custom property page visible to COM:

  • Add a ComVisibleAttribute to the class that implements the custom property page in your project. For information about applying attributes to classes, see Applying Attributes.

  • Use Visual Studio to make your entire add-in assembly visible to COM.

    To make the add-in assembly visible to COM using Visual Studio

    1. In Visual Studio, right-click your project in Solution Explorer, and then click Properties.

    2. Click the Application tab.

    3. Click the Assembly Information button.

    4. Select the Make assembly COM-Visible check box.

    5. Click OK.

Binding Data to Controls and Caching Data

You might encounter the following errors in Office solutions that use data binding or cached data.

Data Binding of a ListObject Fails if a Modal Dialog is Displayed

If Excel displays a modal dialog box while the dataset that is bound to a ListObject is being updated, the data binding of the ListObject fails. When the ListObject loses data binding, it raises the DataBindingFailure event. To bind the ListObject to the data source again, handle the DataBindingFailure event and call the SetDataBinding method.

Cached Visual Basic Dataset Names Do Not Appear Correctly in the Data Cache

DataSet objects created using Visual Basic that are marked as Cached and WithEvents (including DataSet objects that are dragged from the Data Sources window or the Toolbox that have the CacheInDocument property set to True) have an underscore prefixed to their names in the cache. For example, if you create a DataSet and name it Customers, the CachedDataItem name will be _Customers in the cache. When you use ServerDocument to access this cached item, you must specify _Customers instead of Customers.

Using the ServerDocument Class

You might encounter the following errors in Office solutions that use the Microsoft.VisualStudio.Tools.Applications.ServerDocument class.

Cannot Run Legacy Applications that Use ServerDocument on Computers That Have Only the Visual Studio 2010 Tools for Office Runtime Installed

If you try to run an application that uses the Microsoft.VisualStudio.Tools.Applications.ServerDocument class in the Visual Studio Tools for Office system (version 3.0 Runtime) on a computer that has only the Visual Studio 2010 Tools for Office Runtime installed, the application might fail unexpectedly. To run the application, install the Visual Studio Tools for Office system (version 3.0 Runtime) on the computer. Both versions of the runtime can be installed on the same computer.

See Also

Tasks

Troubleshooting Design Time Errors in Office Solutions

Troubleshooting Office Solution Security

Concepts

Troubleshooting Office Solution Deployment

Other Resources

Troubleshooting Office Solutions