Upgrading Solutions from Visual Studio Tools for Office, Version 2003

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

The structure of document-level projects for Word and Excel in Visual Studio 2010 differs from similar projects created by using Visual Studio Tools for Office, Version 2003. When you upgrade a project from Visual Studio Tools for Office, Version 2003, Visual Studio automatically changes the project to comply with the new structure. However, you must also perform additional upgrade steps manually. 

Changes to the Project System and Structure

Word and Excel projects created by using Visual Studio Tools for Office, Version 2003 contain a single main class file that, by default, is named OfficeCodeBehind. The code that defines the structure of the project is stored in this file.

Excel workbook and template projects in Visual Studio 2010 contain a separate class file for each worksheet and a class file for the workbook. 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 workbooks, these classes are named Sheet1, Sheet2, and Sheet3 by default. Code that affects the workbook generally, such as event handlers for the workbook Open and BeforeClose events, should be added to the workbook class. By default, this class is named ThisWorkbook.

Word document and template projects in Visual Studio 2010 have one code file that contains all the code that relates to the document in the project. By default, this class is named ThisDocument.

For more information about the new generated classes, see Programming Document-Level Customizations.

Upgrade Steps Performed by Visual Studio

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

  • Updates the project to comply with 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 adds comments that explain what happened. The name of the original code file is changed from DocumentName to DocumentName(old).

  • Adds all other files from the original project to the new project.

  • Adds all existing references to the new project.

Visual Studio does not automatically move the existing code to the new document, workbook, or sheet class. Instead, the _Startup method of the old OfficeCodeBehind class in the DocumentName(old) file is called from the Startup method of the new class. This instantiates the old class so that the solution runs the same way it did under the old version.

Upgrade Steps You Must Perform

To complete the upgrade, you must follow these steps:

  • Move your code manually from the old class to the new document, workbook, and sheet classes.

  • Update your code.

  • Replace all ActiveX controls with managed controls.

Moving Code from the Old Main Class to the New Classes

It is recommended that you move your code out of the old OfficeCodeBehind class and into the new classes so that you can take advantage of automatic code generation in Visual Studio. However, if you want to 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.

Visual Studio automatically uses the new classes when it generates code. For example, if you add a button to your document and double-click it, a default event handler is added to the new class. If you move your code out of the old OfficeCodeBehind class, you can delete the DocumentName(old) file.

To help get you started, the generated code in the new ThisDocument or ThisWorkbook class contains commented placeholder methods. These methods correspond to the event handlers in the old OfficeCodeBehind class. You can use them in one of two ways:

  • If you move all your code from the old OfficeCodeBehind class to the new classes, you can move the implementations of the old event handlers into these new methods.

  • If you leave your code in the old OfficeCodeBehind class, you can call the old event handlers from these new methods. For this to work, you must change the event handlers in the old class so that they are no longer private.

The following code example shows the generated code in the ThisDocument class of a Word project.

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)
//}

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

Updating Your Code

You may need to make the following additional changes to your code in the following scenarios.

Qualifying Use of the Application Object

In Visual Studio Tools for Office, Version 2003, the unqualified use of Application in the OfficeCodeBehind class referred to the System.Windows.Forms.Application type. In Visual Studio 2010, the unqualified use of Application in document-level Office projects refers to the Document.Application, Workbook.Application, or Worksheet.Application property. 

If you want to use the System.Windows.Forms.Application type in the upgraded project, you must update any unqualified reference to Application with the fully qualified type name, System.Windows.Forms.Application. For example, if your original solution uses code such as Application.Run(New Form1) to open a Windows form, you must rewrite it as System.Windows.Forms.Application.Run(New Form1).

Renaming Events and Methods

Some objects in the Word and Excel object models have events and methods with the same name. For example, Word documents have a Close event and a Close method. Because Visual Basic and Visual C# does not allow types to have different members with the same name, some Word and Excel events have different names in document-level projects in Visual Studio 2010. You must replace any existing references to the following events with the new names.

For Word projects:

  • To access the Close event of the document in your project, use the CloseEvent event of the ThisDocument class.

  • To access the Sync event of the document in your project, use the SyncEvent event of the ThisDocument class.

For Excel projects:

  • To access the Activate event of a worksheet in your project, use the ActivateEvent event of one of the Sheetn classes.

  • To access the Calculate method of a worksheet in your project, use the CalculateMethod method of one of the Sheetn classes.

  • To access the Activate event of the workbook in your project, use the ActivateEvent event of the ThisWorkbook class.

  • To access the Sync event of the workbook in your project, use the SyncEvent event of the ThisWorkbook class.

  • To access the Activate event of a chart in your project, use the ActivateEvent event of a Microsoft.Office.Tools.Excel.Chart object.

  • To access the Select event of a chart in your project, use the SelectEvent event of a Microsoft.Office.Tools.Excel.Chart object.

Handling the Open Event

Upgraded projects do not automatically generate event handlers for the Open event for Excel workbooks or the Open event for Word documents. If you have code that runs when the workbook or document opens, you should move your code to the ThisWorkbook_Startup event handler in the new ThisWorkbook class, or the ThisDocument_Startup event handler in the new ThisDocument class. Alternatively, you can call these event handlers 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 Office projects in Visual Studio 2010. For example, you cannot bind data to ActiveX controls, and you must use a special interop assembly to code against them. For this reason, ActiveX controls are not supported for use in new Office projects.

For more information about the new managed controls that you can use on Word documents and Excel worksheets, see Controls on Office Documents.

See Also

Tasks

How to: Upgrade Office Solutions

Concepts

Document Host Item

Workbook Host Item

Worksheet Host Item

Chart Control

Other Resources

Upgrading and Migrating Office Solutions

Controls on Office Documents