Troubleshooting in Visual Studio at Design Time

Article
11/16/2012

The following issues might occur while you are developing solutions using Visual Studio Tools for Office.

Saving a Solution and then Running It Raises an Error

Visual Studio stores solutions in a temporary folder until they are saved. Visual Studio Tools for Office automatically changes your security policy to trust the solution in the temporary location. These changes are made when the solution is built. If you do not make any changes to the solution before you save it to a permanent folder, Visual Studio does not build the solution when you run it again from the new location. Therefore, the solution is not automatically trusted in the new location, and the solution does not run.

If you get an error after saving a new solution to a permanent location, open the Build menu and then click Rebuild Solution. This causes Visual Studio to build the solution even if you have not made any changes to it. Visual Studio Tools for Office then makes the appropriate changes to the security policy for the new location.

Cannot Build a Document-Level Project That Is Based on a Document With Restricted Permissions

Visual Studio Tools for Office cannot build document-level projects if the document has restricted permissions. If your project contains a document that has restricted permissions, the project will not compile, and you will receive the following message in the Error List window:

Failed to add the customization.

If you want to include a document that has restricted permissions, use an unrestricted document while you develop and build the solution. Then, apply the restricted permissions to the document in the publish location, after you publish the solution.

Some Events Are Not Raised When Using C#

Office objects that have a method and an event with the same name have been split into two objects in the Office primary interop assemblies: a core object with all the properties and methods, and an event object that contains events with names that conflict with a property or method. These event objects use the naming convention <objectname>_Event. If you do not see an event that you expect, cast to the <objectname>_Event interface.

For example, there is an ActivateEvent event and an Activate method for a Workbook. To handle this event, use WorkbookEvents_Event instead of Workbook.

Create member variables in the declarations section:

private Excel.Workbook wkbk;
private Excel.WorkbookEvents_Event wbEvents;
private Excel.WorkbookEvents_ActivateEventHandler activateEvent;

Connect the event in _Startup:

wbEvents = (Excel.WorkbookEvents_Event)wkbk;
activateEvent = new Excel.WorkbookEvents_ActivateEventHandler(ThisWorkbook_Activate);
wbEvents.Activate += activateEvent;

Write an event handler:

private void ThisWorkbook_Activate()
{
    // Your code goes here.
}

You must cast to WorkbookEvents_Event because Excel.Workbook.Activate returns the Activate method and not the ActivateEvent event.

As an alternative, you can cast the object to its corresponding event interface in Startup:

((Excel.WorkbookEvents_Event)(Globals.ThisWorkbook.InnerObject)).Activate += 
    new Excel.WorkbookEvents_ActivateEventHandler(ThisWorkbook_Activate);

Then write an event handler for your code:

private void ThisWorkbook_Activate()
{
    // Your code goes here.
}

References to Office Classes Are Not Recognized

Some class names, for example Application, are in multiple namespaces such as Microsoft.Office.Interop.Word and System.Windows.Forms. For this reason, the Imports/using statement at the top of the project templates includes a shorthand qualifying constant, for example:

Imports Word = Microsoft.Office.Interop.Word

using Word = Microsoft.Office.Interop.Word;

This usage of the Imports/using statement requires that you differentiate references to Office classes with the Word or Excel qualifier, for example:

Dim doc As Word.Document

Word.Document doc;

You will get errors if you use an unqualified declaration, for example:

Dim doc As Document  ' Class is ambiguous

Document doc;  // Class is ambiguous

Even though you have imported the Word or Excel namespace and have access to all the classes inside it, you must fully qualify all the types with Word or Excel to remove namespace ambiguity.

Control Properties are Lost when You Create a New Project Based on a Document from an Existing Project

If you create a new Visual Studio Tools for Office project based on a document from an existing project, the properties for any controls that are on the document are not copied into the new project. You must reset the properties for any preexisting controls manually. Alternatively, you can preserve the control properties by creating a copy of the existing project instead of creating a new project, or by loading the existing project into the new solution (in the designer) and copying and pasting the controls from the existing document to the new document.

Controls Appear as Black Rectangles on the Document or Worksheet

If you group controls on a document or worksheet, Visual Studio Tools for Office no longer recognizes the controls. Grouped controls cannot be accessed in the Properties window and they appear as black rectangles on the document or worksheet. You must ungroup the controls in order to restore their functionality.

Controls on a Word Template are Not Visible in Visual Studio.

If you open a Word template in the Visual Studio designer, controls on the template that are not in line with text might not be visible. This is because Visual Studio opens Word templates in Normal view. To view the controls, click the View menu, point to Microsoft Office Word View and then click Print Layout.

Cached Visual Basic Dataset Names Do Not Appear Correctly in the 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.

Compiler Errors Occur When a Microsoft Office 2003 Project Is Named Excel or Word

Excel and Word are reserved keywords in Office projects.

Compiler Errors Occur After a NamedRange Control Is Deleted

If you delete a NamedRange control from a worksheet that is not the active worksheet in the designer, the auto-generated code might not be removed from your project and compiler errors might occur. To make sure the code is removed, you should always select the worksheet that contains the NamedRange control to make it the active worksheet before deleting the control. If auto-generated code is not deleted when you delete the control, you can cause the designer to delete the code by activating the worksheet and making a change so that the worksheet becomes marked as modified. When you rebuild the project, the code is removed.

Using an HTTP Path to the Assembly Is Not Working

Two of the main possibilities are:

The Visual Studio Tools for Office Project Wizard does not modify security policy for assemblies created at HTTP locations. You must grant full trust to the assembly manually. For more information, see How to: Grant Permissions to Folders and Assemblies (2003 System).
ASP.NET disables downloading of DLLs by default. For assemblies to download to the user, the Web server administrator must change Internet Information Services (IIS) properties to allow DLLs to be downloaded from the directory where the assembly is stored. For more information, see Internet Information Services (IIS) Help by browsing to https://localhost/iisHelp/ on the Web server.

To test if this is the trouble, you can check the log of the Web server for denied requests to the DLL. If it appears to be another cause, set the debugger to break on all exceptions and check the error messages.

Projects Created at UNC Network Locations Do Not Automatically Modify Security Policy

The Visual Studio Tools for Office Project Wizard modifies security policy at the User level. If you create a project at a UNC network location, security policy must be modified at the machine level to grant full trust to the assembly before you can run it. You must make machine level policy changes manually. For more information, see How to: Grant Permissions to Folders and Assemblies (2003 System).

DocumentChange Event Is Not Raised When Document Is Opened

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.

Threads Are Not Stopped Correctly After Debugging

Visual Studio Tools for Office follows a thread naming convention that enables the debugger to close the program correctly. If you create threads in your solution, you should name each thread with the prefix VSTA_ to ensure that these threads are handled correctly when you stop debugging. For example, you might set the Name property of a thread that waits for a network event to VSTA_NetworkListener.

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.

Insert Clip Art Command Does Nothing in the Visual Studio Designer

Opening the Insert menu, pointing to Picture, and then clicking Clip Art does not open the Clip Art task pane when Excel or Word is open in the Visual Studio designer. To add clip art using the menu commands, you must open the copy of the workbook or document that is in the main project folder (not the copy that is in the \bin folder) outside of Visual Studio, add the clip art, and then save the workbook or document.

Cannot Create a 2003 Document-Level Project Even Though Office 2003 Is Installed

This problem can occur if you uninstall the 2007 Microsoft Office system and then install Office 2003. You might receive the following error message when you create a 2003 document-level customization project:

"A compatible version of Microsoft Office is not installed on this computer."

To resolve this issue:

Close Visual Studio.
Open the appropriate Microsoft Office application, and then close the application. For example, if you want to create an Excel 2003 workbook project, open and then close Excel 2003.
Start Visual Studio and create the project.

Excel Workbooks Become Disabled When an Excel Document-Level Customization Project Is Open in Visual Studio

When you open Excel 2007 and then create an Excel 2007 document-level customization project in Visual Studio, the workbook that you opened first stops responding.

To resolve this issue, click the worksheet that is visible in the Visual Studio designer. The workbook that you opened first begins responding.