Upgrading and Migrating Office Solutions

If you have a Microsoft Office project that was created in an earlier version of Visual Studio, you must upgrade the project to use it in Visual Studio 2010. To upgrade a Microsoft Office project, open it in a version of Visual Studio 2010 that includes the Microsoft Office developer tools. For more information about the upgrade process, see How to: Upgrade Office Solutions. For more information about the versions of Visual Studio 2010 that include the Microsoft Office developer tools, see Configuring a Computer to Develop Office Solutions.

When you upgrade a Microsoft Office project, Visual Studio makes several changes to the project. Some of the changes depend on the version of the .NET Framework and Microsoft Office that you have installed on the development computer, and whether the project is a document-level project or a application-level project.

You can also change the target framework of Office projects at any time from the .NET Framework 3.5 to the .NET Framework 4, or vice versa. For more information, see How to: Target a Specific .NET Framework Version or Profile. If you change the target framework, some additional steps might be required to run the retargeted solution on development and end user computers, and your project will no longer compile if it uses certain features. For more information, see Migrating Office Solutions to the .NET Framework 4.

Supported Project Upgrade Versions

You can upgrade Office projects created by using any of the following versions of Visual Studio Tools for Office:

• Microsoft Visual Studio 2005 Tools for the Microsoft Office System.

• Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE).

• Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0). This version of Visual Studio Tools for Office was included with Visual Studio 2008.

Visual Studio 2010 does not support upgrading Microsoft Office projects created by using Visual Studio Tools for Office, Version 2003. To continue to develop one of these projects in Visual Studio 2010, create a new Office project and manually port your code into the new project.

Changes to Upgraded Projects

When you upgrade a Microsoft Office project, Visual Studio makes the following changes to the project:

• Updates the version of the Visual Studio Tools for Office runtime that the project targets to the Visual Studio 2010 Tools for Office Runtime.

  For more information about the Visual Studio Tools for Office runtime, see Visual Studio Tools for Office Runtime Overview.

• Updates the version of the .NET Framework that the project targets, if necessary.

• Updates the assembly references in the project.

• Modifies the project to target the version of Microsoft Office that you have installed on the development computer (Microsoft Office 2010 or the 2007 Microsoft Office system) if the original project targeted an earlier version of Microsoft Office. If no version of Microsoft Office is installed, the upgraded project targets the 2007 Microsoft Office system.

Targeted .NET Framework

When you upgrade a Visual Studio Tools for Office project in Visual Studio 2010, Visual Studio modifies the target .NET Framework in the following cases:

• The original project targets the .NET Framework 2.0. In this case, Visual Studio modifies the project to target the .NET Framework 3.5 if both the .NET Framework 3.5 and the .NET Framework 4 are installed on the development computer. If only the .NET Framework 4 is installed, Visual Studio modifies the project to target the .NET Framework 4.

• The project targets the .NET Framework 3.5, but only the .NET Framework 4 is installed on the development computer. In this case, Visual Studio modifies the project to target the .NET Framework 4.

If the project already targets the .NET Framework 3.5, Visual Studio will not update the target framework in the upgraded project if the .NET Framework 3.5 is also installed on the development computer.

The following table summarizes the target framework changes for upgraded projects.

Target framework of original project	Framework versions on development computer	Target framework of upgraded project
.NET Framework 2.0 .NET Framework 3.5	.NET Framework 3.5 and .NET Framework 4	.NET Framework 3.5 Note If the original project targets the .NET Framework 3.5 Client Profile, the upgraded project targets the .NET Framework 3.5.
.NET Framework 2.0 .NET Framework 3.5	.NET Framework 4	.NET Framework 4 Note If the original project targets the .NET Framework 3.5 Client Profile, the upgraded project targets the .NET Framework 4 Client Profile.

When you target the .NET Framework 4 in an Office project, you can use certain features that are not available when you target the .NET Framework 3.5. For more information, see Designing and Creating Office Solutions.

Assembly References

Visual Studio upgrades the following assembly references in the project:

• Microsoft Office primary interop assemblies.

• Assemblies in the Visual Studio Tools for Office runtime. For more information about these assemblies, see Visual Studio Tools for Office Runtime Overview.

• New or updated versions of dependent assemblies.

Visual Studio does not add references to new or updated versions of assemblies that you added to the original project after it was created. For example, if you upgrade a Word 2003 add-in project that also references the PowerPoint 2003 primary interop assembly, Visual Studio modifies the upgraded project to reference the Word 2007 or Word 2010 primary interop assembly. However, you must manually update the reference to the PowerPoint primary interop assembly.

Upgrading Microsoft Office 2003 Projects

By default, if Microsoft Office 2010 or the 2007 Microsoft Office system is installed on your development computer when you upgrade a project that targets Microsoft Office 2003, Visual Studio modifies the project to target the version of Microsoft Office you have installed. The Always upgrade to installed version of Office check box in the Project Upgrade options page controls this behavior. If you clear this check box, Visual Studio does not modify the project to target Microsoft Office 2010 or the 2007 Microsoft Office system, and you might not be able to open, debug, or run the project. For more information about this option, see Project Upgrade, Options Dialog Box.

There are some additional considerations for upgrading document-level customizations and application-level add-ins that target Microsoft Office 2003.

Document-Level Projects

To upgrade a document-level project for Microsoft Office 2003, you must have the appropriate Microsoft Office 2010 or 2007 Microsoft Office system application installed on the development computer. For example, you must install Word 2007 or Word 2010 on the computer before you can upgrade a Word 2003 project.

When you upgrade a document-level project with a document that is saved in a binary format, you must decide whether to convert the document to an Open XML Format, or to keep the document in a binary format. You should select Open XML unless you have a specific reason to use the older format. For more information about Open XML, see Introduction to new file name extensions and Open XML Formats.

If the document in the project contains Windows Forms controls, you must also have the Visual Studio 2005 Tools for Office Second Edition Runtime installed before you upgrade the project. If this version of the runtime is not installed on the development computer before you upgrade the project, there might be compile or run time errors in the upgraded project. After you finish upgrading the project, you can uninstall the Visual Studio 2005 Tools for Office Second Edition Runtime from the development computer if it is not being used by any other Office solutions. This version of the runtime is available as a redistributable package from the Microsoft Download Center at Microsoft Visual Studio 2005 Tools for Office Second Edition Runtime (VSTO 2005 SE) (x86).

Application-Level Projects

If the solution file for your original project included a Setup project that was configured to install the application-level add-in, Visual Studio upgrades the Setup project to a Visual Studio 2010 project, but it does not make any further changes to the project. If you want to keep using a Windows Installer file to deploy your add-in, you must modify the Setup project to install new pre-requisites such as the .NET Framework 4 or .NET Framework 3.5, the Visual Studio 2010 Tools for Office Runtime, and optionally the primary interop assemblies referenced by your add-in. For more information, see Publishing an Office Solution by Using Windows Installer.

If you want to use ClickOnce to deploy your add-in, you can delete the Setup project entirely. For more information about deploying add-ins by using ClickOnce, see Deploying Office Solutions.

See Also

Tasks

How to: Upgrade Office Solutions

Reference

Project Upgrade, Options Dialog Box

Concepts

Migrating Office Solutions to the .NET Framework 4