|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Upgrading and Migrating Office Solutions
Use the Visual Studio Conversion Wizard to upgrade projects from Visual Studio Tools for Office, Version 2003 and Microsoft Visual Studio 2005 Tools for the Microsoft Office System to Visual Studio Tools for the Office system 3.0. To upgrade a Microsoft Office solution, open the solution in Visual Studio with Visual Studio Tools for the Office system 3.0 installed. The Visual Studio Conversion Wizard appears and guides you through the steps required to complete the upgrade. For more information, see How to: Upgrade Solutions from Visual Studio Tools for Office.
The wizard does not modify your code. If you upgrade an Outlook 2003 add-in project, you might need to manually update your code. For more information, see Outlook Projects.
The Visual Studio Conversion Wizard upgrades the project file and the reference to the primary interop assembly of the main Microsoft Office application for the solution. In addition, it adds references to new or updated versions of dependent assemblies. However, the wizard does not add references to new or updated versions of assemblies that you manually add to the project after the original project was created.
For example, if you upgrade a Word 2003 add-in project that has references to a helper method assembly and the PowerPoint primary interop assembly, the Visual Studio Conversion Wizard ensures that references to the Word primary interop assembly and the helper assembly are correct. However, you must update the reference to the PowerPoint primary interop assembly manually.
By default, if you have the 2007 Microsoft Office system installed, the wizard upgrades Microsoft Office 2003 projects so that they become projects for the 2007 Microsoft Office system. However, the process is different for document-level customizations and application-level add-ins.
Document-Level Customization Projects
If you are upgrading a document-level customization, there is no way to prevent the wizard from upgrading the project version. This is because the designer that appears when you open a document-level customization uses the currently installed version of Office. The project can open in the designer only if it matches the version of Office that is installed.
To upgrade a document-level customization project, you must have the appropriate Office application installed. For example, you must have Word 2003 or Word 2007 installed on your computer before you can upgrade a Word 2003 document-level customization project.
If you have the 2007 Microsoft Office system installed, the Visual Studio Conversion Wizard requires you to choose whether you want to convert the document to one of the Open XML Formats. You should convert the format of the document unless you have a specific reason to use the older format. For more information about these formats, see Introduction to new file name extensions and Open XML Formats.
If you have Microsoft Office 2003 installed when you upgrade the project, the project will continue to use Microsoft Office 2003 as the target version and the format of the document will remain the same.
If you upgrade a document-level project that you created by using Visual Studio Tools for Office, Version 2003, you must perform some upgrade steps manually. For more information, see Upgrading from Visual Studio Tools for Office, Version 2003.
Application-Level Add-in Projects
If you have the 2007 Microsoft Office system installed, and you do not want the Visual Studio Conversion Wizard to upgrade version 2003 add-in projects to version 2007 add-in projects, you can change the default so they remain Office 2003 projects. Since the 2007 release of Office can host Office 2003 add-ins, you can develop, compile, and test the project even though you do not have Microsoft Office 2003 installed. Clear the Always upgrade to installed version of Office option in the Project Upgrade options page. For more information, see Project Upgrade, Options Dialog Box.
The Visual Studio Conversion Wizard cannot make add-in projects compatible with a previous version of Office. Therefore, if you have Office 2003 installed and upgrade a version 2007 add-in project, then the project remains a version 2007 add-in project after the upgrade is complete. You can open the project, develop the add-in, and compile code successfully. However, you cannot test the add-in because Office 2003 does not host version 2007 add-ins.
You do not need to have Microsoft Office installed to upgrade an application-level add-in project.
If you upgrade an Outlook 2003 add-in project, you should update the name of your host item class and you must update references to the Application object.
You do not need to update projects that you created by using Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE) project templates.
Host Item Class Name
The Visual Studio Conversion Wizard does not update the name of your host item class. The name of the class continues to be ThisApplication. You do not need to change this name. However, code examples in the Visual Studio Tools for the Office system 3.0 Help documentation use the host item class name ThisAddIn. If you would like to make it easier to test code by copying it and pasting it in your own project, you can change the name of the class to ThisAddIn and then refactor this name change throughout the project. For information about how to refactor code in a C# project, see How to: Rename Identifiers. For information about how to refactor code in a Visual Basic project, see How to: Rename an Identifier.
References to the Application Object
The Visual Studio Conversion Wizard does not modify your code. Therefore, you must manually change all code that uses either of the following techniques to access the Application object:
The this (in C#) or Me (in Visual Basic) keyword inside the ThisApplication class.
The Globals.ThisApplication object in code outside the ThisApplication class.
For example, if your ThisApplication class contains the following code, you must update it.
The following code works as the replacement in upgraded projects.
The ThisApplication host item class in Microsoft Visual Studio 2005 Tools for the Microsoft Office System projects inherits directly from the Microsoft.Office.Tools.Outlook.Application class. However, the ThisAddIn host item class in Visual Studio Tools for the Office system 3.0 projects does not inherit from Microsoft.Office.Tools.Outlook.Application. Instead, you reference the active application object by using the Application property of the host item class.
If you upgrade to the 2007 version of Microsoft Office after you upgrade a Visual Studio Tools for Office project, the Visual Studio Conversion Wizard will appear the next time that you open the project.
Add-in projects for the 2007 version of Office that you chose not to upgrade when you had Office 2003 installed will now run, and you can test them by pressing F5 or CTRL+F5 in Visual Studio.