Upgrading from Visual Studio Tools for Office, Version 2003

Article
11/16/2012

After you upgrade from Visual Studio Tools for Office, Version 2003 to Visual Studio Tools for the Office system 3.0 (Visual Studio Tools for Office), you must perform some upgrade steps for document-level projects manually.

In the new project system, the project code templates have changed significantly. Your upgraded project has the new project structure, but your code stays in the original code file that was based on the earlier project code template. To enable the solution to run immediately after the upgrade, the new project class instantiates the old imported class (the original class that by default was named OfficeCodeBehind). To make a complete upgrade, you must move the code from the old OfficeCodeBehind class to the new document, workbook, or sheet class as described in this topic.

New Project System and Structure

The project system in Visual Studio Tools for Office, Version 2003 had a single main class file for your code. The new project system features a container structure in Solution Explorer that represents the document or workbook. The class files for your code are under the container structure. Under these class files are hidden files that contain the code generated by Visual Studio Tools for Office. It is best not to modify the code in the hidden files, because they can be regenerated during development and your changes will be lost.

Excel Workbook and Template Projects

Excel workbook and template projects now contain a separate class file for each worksheet and a class file for the workbook as a whole. Code that is specific to a worksheet, such as code that responds to a control on a worksheet, should be placed in the sheet class. For new documents, by default, these classes are named Sheet1.vb or Sheet1.cs, Sheet2.vb or Sheet2.cs, and so on. Code that affects the workbook generally, such as the workbook Open event, the BeforeClose event, and actions pane code, should be placed in the workbook class. By default, this class is named ThisWorkbook.vb or ThisWorkbook.cs.

Word Document and Template Projects

Word document and template projects have one code file to contain all of the code that relates to the document. By default, this class is named ThisDocument.vb or ThisDocument.cs.

For more information, see Office Project Templates.

Upgrade Process

When you upgrade your project, Visual Studio performs the following tasks:

Upgrades the project to conform to the new file format and project structure.
Copies the existing document into the new project folder.
Removes the custom document properties _AssemblyName0 and _AssemblyLocation0 to prevent existing managed code extensions from running (these properties are added again when the project is built).
Adds the original main code file but incorporates comments to explain what happened, and changes the name of the file from <DocumentName> to <DocumentName>(old).
Adds all the files from the original project to the new project.
Adds all existing references to the new project.

None of the existing code is migrated to the new classes. Instead, the _Startup method of the old main class is called from the Startup method of the new main class. This instantiates the old class so that the solution runs the same way it did under the old version.

The default name of the class in <DocumentName>(old) is OfficeCodeBehind. In an upgraded Word project, the default name of the main class is ThisDocument. In an upgraded Excel project, the default names of the main classes are ThisWorkbook for the class that includes code that runs at the level of the workbook, and Sheet1, Sheet2, and so on for code that runs at the worksheet level.

To complete the upgrade, you must:

Move your code manually from the old class (that had the default name of OfficeCodeBehind) to the new document, workbook, and sheet classes, and then delete the old code file. However, if you want to simply maintain the existing code as it is, you can leave the old code file and run the code by calling it from the new classes. Any new code added by the tools is put into the new classes.
Update your code as described below.
Replace all ActiveX controls with managed controls.

Optionally, you can also:

Refactor your C# code.

Moving Code from the Old Main Class to the New Class

It is recommended that you move your code out of the old class and into the new classes, so that you can take advantage of the tools in Visual Studio. The tools automatically use the new classes when they generate code. For example, if you add a button to your document and double-click it to get to the code, the default event handler is added to the new class.

If you are upgrading an Excel solution, be sure to think about which class should contain each method that you move over. If the method pertains generally to the workbook and/or all of the sheets, you should put the code in the ThisWorkbook class. If the code pertains to one sheet, for example the code for a control on a sheet, the code belongs in the appropriate sheet class.

To help get you started, the generated code in the new ThisDocument or ThisWorkbook class contains commented placeholder methods. You can use these methods in one of two ways:

Take all of your code out of the old class and put it into the new classes that are provided in the upgraded solution.
Write code in the new methods to call the old methods in the old class. For this to work, you must change the methods in the old class so that they are no longer private.

Examples

The following are examples of placeholder methods that instantiate the old class and call methods in that class:

Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    OldCode = New OfficeCodeBehind()
    OldCode._Startup(Me.ThisApplication, Me)
End Sub 

''Private Sub ThisDocument_Open() Handles MyBase.Open 
''    OldCode.ThisDocument_Open() 
''End Sub 
'' 
''Private Sub ThisDocument_Close() Handles MyBase.CloseEvent 
''    OldCode.ThisDocument_Close() 
''End Sub

private void ThisDocument_Startup(object sender, System.EventArgs e)
{
    OldCode = new OfficeCodeBehind();
    OldCode._Startup(this.Application, this);
}

//private void ThisDocument_Open() 
//{ 
//    OldCode.ThisDocument_Open() 
//} 
// 
//private void ThisDocument_Close(ref bool Cancel) 
//{ 
//    OldCode.ThisDocument_Close(ref Cancel) 
//}

After all of your code has been moved over to the new classes, remove the old class.

Updating Your Code

There are a few changes you might need to make to your code if your existing code refers to Application, calls certain events or methods, or relies on the Open event.

Qualifying Application

In Visual Studio Tools for Office, Version 2003, the unqualified use of Application referred to the System.Windows.Forms.Application type. In Visual Studio Tools for Office, it refers to the Word or Excel Application object. This means that you must update any unqualified reference to Application with the fully qualified namespace System.Windows.Forms.Application to get the same results. For example, if you use code such as Application.Run(New Form1) to open a form, you must rewrite it as System.Windows.Forms.Application.Run(New Form1).

Renaming Events and Methods

Word and Excel expose some events that have the same names as methods in the object model. For example, Word documents have a Close event and a Close method. Visual Studio Tools for Office solution code requires a different name for one of the members; you must replace any existing references to the following members with the new names.

Word.Document

For the Close event, use CloseEvent.
For the Sync event, use SyncEvent.

Excel.Worksheet

For the Activate event, use ActivateEvent.
For the Calculate method, use CalculateMethod.

Excel.Workbook

For the Activate event, use ActivateEvent.
For the Sync event, use SyncEvent.

Excel.Chart

For the Activate event, use ActivateEvent.
For the Select event, use SelectEvent.

Handling the Open Event

Upgraded projects do not raise the Open event for Excel workbooks or the Open event for Word documents. If your code relies on the Open event, you should move your code to the ThisWorkbook_Open() event handler in the new ThisWorkbook class for Excel workbooks, or the ThisDocument_Open() event handler in the new ThisDocument class for Word documents. Alternatively, you can call the Open event handler from the _Startup method of the original OfficeCodeBehind class.

Replacing ActiveX Controls with Managed Controls

If you used ActiveX controls on your document or workbook, you should delete them and replace them with managed controls from the Visual Studio Toolbox. ActiveX controls have limitations in the new Visual Studio Tools for Office projects; for example, you cannot bind data to ActiveX controls, and you must use a special interop assembly to be able to code against them. For this reason, ActiveX controls are not supported for use in new Visual Studio Tools for Office projects.

Refactoring Your Code (C# Only)

Visual Studio provides tools to help you organize and arrange your C# code, a process that is known as refactoring. A Refactor menu that contains these tools is added to Visual Studio when the code file is open in the code editor. For more information, see Refactoring.