Upgrading VSTO Projects to use with Visual Studio 2010 (Navneet Gupta)

The first thing that you notice after opening your existing projects in Visual Studio 2010 is the very familiar Visual Studio Conversion wizard. Internally we call it Project Migration wizard. Personally I love this wizard because of its simplicity, my converted projects are only few clicks away. In this post I’ll walk through this wizard and tell you what’s happening behind the scenes.


There is very useful information shown on the first page of the wizard. This information is very similar to what was on Visual Studio 2008 version. I have the screen shot below and I can bet that most of you will not read the entire statement. I have been using Visual Studio since Visual Studio 6.0 and never read this myself until I joined this team and started owning Project Migration J. Personally I would have written this as bulleted list. Here is my version of the information.

1. You see this wizard if this project was created in previous versions of VS, or if you upgraded your copy of Microsoft Office.

* The second part of above statement is very interesting in VSTO scenarios, I will elaborate that later.

2. Once you convert this project to Visual Studio 2010, you may not be able to use it with earlier versions of Visual Studio, better take backups J

3. We will checkout the project files automatically if the project is under source control and provided this machine is configured properly to use source control.

4. If the project is not under source control remove the read only attribute from the files and folders.



The second step in the wizard gives us a chance to backup existing source files. We highly recommend taking a backup so that’s why we select the option by default. If you click Finish on the previous page, we would take the backup by default. By default we create a folder named “Backup” under the project directory and store the backup there.



The next step of upgrade process will tell you what we are going to do with your project. Again here is my bulleted list of what is written there.

1. We will checkout the files automatically, please make sure that the source control is configured properly on the machine.

2. We will upgrade the project to the currently installed version of Office. If you do not want to upgrade this uncheck “Always upgrade to installed version of Office” option on the “Office Tools” section of the Tools | Options dialog.

· Note that you can upgrade the Add-Ins even if you do not have any version of Microsoft Office installed on the machine.

· VSTO in Visual Studio 2010 does not support Office 2003 so we upgrade to Office 2007 format by default.

Update: Please note that it is still possible to create Office 2003 Shared AddIns in Visual Studio 2010, Misha has a nice blog about the COM Shim wizard being upgraded to use with VS 2010




Once you click Finish we start upgrading the project to Visual Studio 2010 format. Once this is converted, you will get the final page of this wizard. If there were any errors during upgrade the conversion log checkbox will be checked by default.

If you do not have .Net Framework 3.5 SP1 installed on the machine the project migration will go through an extra step which I will explain later in “Retargeting During Project Upgrade” section below.


If you check the checkbox then the Conversion Report will display as shown below. It is clear from the report below that we touch only the .sln and .csproj/.vbproj files during project upgrade.


Retargeting During Project Upgrade

If the machine does not have .Net Framework 3.5 SP1 installed, the Project Migration wizard will ask you to either download .Net Framework 3.5 SP1 or to retarget the project to .Net Framework 4.


If you choose to download .Net Framework 3.5 SP1 the solution and project file will be upgraded to Visual Studio 2010 compatible format and the project will be unloaded in the Solution Explorer. After downloading .Net Framework 3.5 SP1 you can right click on the project in Solution Explorer and select Reload Project.


Please keep few things in mind when you choose to retarget the project to .Net Framework 4, this is a big decision; it comes with lots of power and with power comes lots of responsibilities. The major benefit of switching to .Net Framework 4 for VSTO solutions is the use of Type Embedding in VSTO Runtime. Once you retarget the solution to .Net Framework 4 all the referenced Primary Interop Assemblies will be embedded into the customization assembly and the end users will no longer need to install Microsoft Office Primary Interop Assemblies on their machines to run this customization.

There is a nice MSDN article which explains this, so be sure to go through it before deciding to switch to .Net Framework 4. Be aware that you may need to change some code as we have changed the programming model a bit. Take a look at some of the How Do I videos we have on the VSTO Dev Center that explain how to migrate projects.

Note: If you are upgrading a document level customization that targets Office 2003 you may need to install Visual Studio for Office Runtime Second Edition on developer machine before upgrading the project due to a known compatibility break we found while designing Visual Studio for Office Runtime 3.0 during the Visual Studio 2008 timeframe. Check “Upgrading Microsoft Office 2003 Projects” section of this article for more details.

So I hope that this post helps explain what is happening behind the scenes when you migrate your Office solutions to Visual Studio 2010.

You may find following articles useful while migrating projects to Visual Studio 2010.

Upgrading and Migrating Office Solutions

Migrating Office Solutions to the .NET Framework 4

Project Upgrade, Options Dialog Box

Have fun.