Troubleshooting in Office at Run Time

If end users report error messages, or if error messages from Microsoft Office appear as you are building your solution, look for the following common mistakes or problems.

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

This problem causes the following error message to appear:

The common language runtime could not be loaded by <application>. Contact your administrator for further assistance.

The version of the Microsoft .NET Framework on the end user's computer must be the same as or older than the version on the computer that was used to develop the solution. For more information about how to install the .NET Framework and the common language runtime, see the Microsoft .NET Framework downloads page.

Custom Macros Require the Common Language Runtime

This problem causes the following error message to appear:

The custom macros in this document require the common language runtime, version 2.0, to be installed. Contact your administrator for further assistance.

The end user might have installed a version of the Microsoft .NET Framework that is not compatible with your solution. The version of the .NET Framework that is installed on the user's computer must be the same as or older than the version that you used to develop your solution. A newer version of the .NET Framework may be installed, side-by-side with the existing version. For more information about how to install the .NET Framework and the common language runtime, see the Microsoft .NET Framework downloads page.

Security Policy Does Not Permit Assembly to Run

This problem causes the following error message to appear:

The current .NET security policy does not permit <assembly> to run from the folder <path>. Do not change the security policy in your computer. The .NET security policy is controlled by your administrator or the developer who wrote the custom macros. You can still edit and save the document. Contact your administrator or the author of this document for further assistance.

The managed assembly is not trusted and it might be harmful. If you are sure that the assembly is safe, you must grant it full trust in the user's .NET security policy before it will run. For more information, see How to: Grant Permissions to Folders and Assemblies (2003 System).

Security Policy Does Not Permit Document to Load Assembly

This problem causes the following error message to appear:

The current .NET security policy does not permit <document> to load custom macros. Do not change the security policy in your computer. The .NET security policy is controlled by your administrator or the developer who wrote the custom macros. You can still edit and save the document. Contact your administrator or the author of this document for further assistance.

Likely explanations for the error include the following:

• The document was opened from an untrusted location or from an e-mail attachment, and it might be harmful.

  Note

  If you are sure that this document is safe, save it to the user's computer and then open it. Once it is saved on the computer, the document is in the My Computer zone, which has full trust. If the document is an e-mail attachment, it is saved in the Internet zone, which does not have full trust.

• The correct version of the Microsoft .NET Framework was on the computer at one time, but it was deleted before the solution ran. If a user installs two .NET Framework versions side-by-side and then removes one, this security message appears rather than a message stating that the required version of the .NET Framework is not installed.

  Note

  To run the solution, install the required version of the .NET Framework.

For more information, see Security Requirements to Run Office Solutions (2003 System).

Security Exception Appears when Project Assembly Has Full Trust

If you receive a security exception when you are sure that the main project assembly has full trust, a referenced assembly may have attempted to perform an action that it lacks the required permissions to complete. You must grant referenced assemblies any required permissions manually.

When a project is built on a developer computer, the referenced assemblies that are contained in the project's output folder receive Execution permissions. Only the main project assembly is automatically granted full trust.

Assembly Cannot Be Found or Loaded

This problem causes the following error message to display:

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:

• Make sure 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, a smart tag, or a smart document. The customization may have explicitly loaded a version of the .NET Framework common language runtime (CLR) that is incompatible with the Visual Studio Tools for Office runtime. To resolve the issue, disable any customizations that explicitly load a version of the .NET Framework CLR that does not match the runtime used by your solution.

  Note

  A running application can load only one instance of the .NET Framework CLR. If a customization forces Word or Excel to load an earlier version of the .NET Framework CLR, the Visual Studio Tools for Office solutions will not load.

• 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 and General, Debugging, Options Dialog Box.

Assembly Cannot Be Initialized

This problem causes the following error message to appear:

The custom macros in <project> could not be initialized correctly. You can still edit and save the document. Contact your administrator or the author of this document for further assistance.

Possible reasons for this error message include the following:

• The main Office project assembly is partially trusted. For example, if you create a project on a network share that only has Intranet Zone permissions in its machine-level security policy, this error message will display even if you granted the Office project assembly full trust at the user level. The assembly loads without a security warning, but because the machine-level policy is more restrictive than the policy for the assembly, the assembly does not have the required permissions to access the Office object model (which requires full trust) and the assembly is not initialized. A network administrator must grant full trust to the Office project assembly at the machine level if the assembly you are working on is not stored on the local computer. For more information, see Security Requirements to Run Office Solutions (2003 System).

• You did not install the primary interop assembly for a referenced COM component in the global assembly cache before you created the COM reference. Visual Studio generates an interop assembly that might not work fully in all cases: it puts the assembly in the project directory rather than in the global assembly cache.

To reference the correct interop assembly

1. Find all references in your project to COM components (such as Office applications) that have the Copy Local property set to True.

2. Right-click the reference, and then click Remove on the shortcut menu.

3. Run Add or Remove Programs and install the primary interop assembly for the component in the global assembly cache. For more information, see How to: Install Office Primary Interop Assemblies.

4. Open your project in Visual Studio and add a new reference to the component. For more information, see How to: Target Office Applications Through Primary Interop Assemblies.

Assembly Is Not Available for Offline Use

This situation causes the following message to appear:

The custom macro in <path> is not available offline. Do you want to go online to download the customization? This may affect other programs running on your computer, such as Internet Explorer.

This message displays if the computer is in offline mode and if a copy of the assembly is not already in the cache. To work offline, the following conditions must be met:

• The assembly must exist on a Web server.

• The assembly must be accessed through an HTTP or HTTPS path in the custom properties.

To cache an assembly that meets the previous criteria, you must go online and open the Office document to download a copy of the assembly. You must download a copy of the assembly at least one time. Thereafter, the assembly is available for offline work. For more information, see Offline Model for Office Solutions (2003 System) and How to: Deploy for Offline Use of Documents (2003 System).

Assembly Is Not Available Online

This situation causes the following message to appear:

The custom macro in <path> is not available online, but a local copy is available. Do you want to go offline and use the cached copy? This may affect other programs running on your computer, such as Internet Explorer.

This message appears if your computer is not connected to a network, or if the network is down and the computer is in online mode. To use a cached assembly, you must set your computer to offline mode, either by clicking OK in the dialog box or by selecting Work Offline on the File menu in Internet Explorer. For more information, see Offline Model for Office Solutions (2003 System) and How to: Deploy for Offline Use of Documents (2003 System).

Assembly Cannot Be Loaded

This problem causes the following error message to appear:

Could not load type <projectname> from assembly <assemblyname>.

This message might appear if you obfuscate the solution code. The error occurs because 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 worksheet and the workbook classes to the obfuscator's list of classes not to rename.

Regional Settings Cause Some Excel Methods to Return an Error

If the locale selected in an end user's regional settings does not match the installed language for Microsoft Office Excel 2003, the user might receive the following errors when he or she calls certain Excel methods and properties:

A first chance exception of type 'System.Runtime.InteropServices.COMException' occurred in mscorlib.dll.

Additional information: Exception from HRESULT: 0x800A03EC.

-or-

A first chance exception of type 'System.Runtime.InteropServices.COMException' occurred in ExcelProject.dll.

Additional information: Old format or invalid type library.

For details about how to correct this problem, see Globalization and Localization of Office Solutions.

Office Document Opens with No Errors, but Code Does Not Execute

Even if no error messages appear, code may not run for the following reasons:

• The Office primary interop assemblies are not installed in the global assembly cache, possibly because the .NET Framework is not installed on the computer, or because the assemblies are marked Not Available in Office setup.

• The version of Word or Excel on the end user's computer does not support Visual Studio Tools for Office solutions. End users must install Word and/or Excel from an edition of Microsoft Office 2003 that supports Visual Studio Tools for Office. For more information, see How to: Install Visual Studio Tools for Office to Develop for Microsoft Office 2003.

The document is opened from an HTTP or an HTTPS location. The Browse in same window option for .doc or .xls files is not selected in Windows Explorer. The Browse in same window option is used by Internet Explorer to determine whether the document is hosted inside the active window or a separate window. If the document is hosted in a separate window, the customizations do not load and run. To access the Browse in same window option for a Word document or an Excel worksheet, open Windows Explorer, click the Tools menu, and then click Folder Options. On the File Types tab, select DOC or XLS in the list of file types, click Advanced, and verify that Browse in same window is selected.

• 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.

Macro Security Is Set to High but Code Still Runs

A Microsoft Office 2003 solution created by using managed code extensions runs even if the Security setting in the end user's Office application is set to High. The code extensions run because managed assembly code security is governed by the Microsoft .NET Framework, not by Microsoft Office Word 2003 or Microsoft Office Excel 2003.

Excel and Word Exit Unexpectedly When an Unhandled Exception Occurs on a Modeless Form

If Excel or Word exits unexpectedly after a user triggers an event on a modeless form, check to see whether there are any places where unhandled exceptions may be raised in the code. Add error handling to prevent possible data loss.

Outlook Add-in Does Not Load or Is Disabled

If an Outlook add-in does not load correctly, check the following possibilities:

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

• An Outlook add-in may not always load if the add-in manifest file is not located in the same directory as the add-in assembly. If you deploy the manifest file to a different directory, you must update the codebase attribute of the asmv2:installFrom element in the add-in manifest file so that it points to the location of the add-in assembly.

• Outlook might be running an add-in that explicitly loads a version of the .NET Framework common language runtime (CLR) that is incompatible with the Visual Studio Tools for Office runtime. To resolve the issue, disable any add-ins that explicitly load an incompatible version of the .NET Framework.

  A running application can load only one instance of the .NET Framework. If an add-in forces Outlook to load an earlier version of the .NET Framework, then any add-ins that were created by using Visual Studio Tools for Office will not load.

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

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

Do not use the COM Add-Ins dialog box to install Outlook add-ins that are created by using Visual Studio Tools for Office. Use the deployment project included in the Outlook project template. Outlook add-ins use a proxy .dll file that is named AddinLoader.dll, to extend Outlook's functionality. The proxy enables the managed assembly to communicate with Outlook through COM. For more information, see Deploying Application-Level Add-Ins (2003 System).

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. Otherwise, the add-in will not create the custom property page, and you might receive a COMException as you are 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 how to apply 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.

Quit Event is Never Raised in Outlook Add-ins

When you close an instance of Outlook that is running an add-in created by using Visual Studio Tools for Office, the add-in is unloaded before it receives the Quit event. In other words, if you create an event handler for the Quit event of the Microsoft.Office.Tools.Outlook.Application class in an Outlook add-in, it will never run. Alternatively, you can put any code that should run when Outlook closes in your project's ThisAddIn_Shutdown event handler. For more information, see 2007 Microsoft Office Add-in Project Templates and 2003 Microsoft Office Add-in Project Templates.

Close Method Causes Word and Excel to Exit Unexpectedly

When you call the Close method of the Excel Workbook object or the Word Document object from a modeless form, the application might exit unexpectedly. Possible outcomes include the following:

• 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 when handling the AppDomain.DomainUnload event.

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

• If you must close the document from the form, use modal forms (for example by using ShowDialog instead of [M:System.Windows.Forms.Form.Show(System.Windows.Forms.IWin32Window]).

• If you must use a modeless form, make sure that that the modeless form is closed and that the form references are completely destroyed before you try to close the document or workbook. The following code shows an example:

  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 how to pass the missing parameter in C#, see The Variable missing and Optional Parameters in Office Solutions.

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

The application might exit unexpectedly if you:

• Show the SaveAs dialog box inside the DocumentBeforeSave event handler of ThisDocument.

• Then set the Cancel parameter to false.

  Note

  If you set the Cancel parameter to true, an error message indicates that Autosave has been disabled.

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.

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 ExcelLocale1033Attribute attribute is set to false, and you pass in a host control that is based on the native Office object, Excel 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.

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

If Excel displays a modal dialog box as the dataset that is bound to a ListObject is being updated, the data binding for 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.

Double-Clicking Deployment Manifest Causes Error

If you double-click a deployment manifest, you receive the following message:

Cannot continue. The application is improperly formatted. Contact the application vendor for assistance.

Unlike ClickOnce deployment, you cannot run a Visual Studio Tools for Office solution by double-clicking the deployment manifest. To run the solution, open the Office application. For Word and Excel, open the solution document inside the application. Alternatively, you can double-click the document file.

For more information about how to deploy Visual Studio Tools for Office solutions, see Deploying Document-Level Customizations (2003 System) and Deploying Application-Level Add-Ins (2003 System). For more information about deployment manifests, see Deployment Manifests for Office Solutions (2003 System).

Cannot Run or Debug any Office Solution on the Development Computer

If you cannot run or develop Visual Studio Tools for Office solution on your development computer, you may receive the following error message:

Customization could not be loaded because the application domain could not be created.

Visual Studio Tools for Office uses Fusion, the .NET Framework assembly loader, to cache the assemblies before it loads Office solutions. Ensure that Visual Studio can write to the Fusion cache, and try again. For more information, see Shadow Copying Assemblies.

See Also

Tasks

Troubleshooting in Visual Studio at Design Time

Concepts

Common Tasks in Office Programming

Other Resources

Troubleshooting Office Solutions