Marcin On ASP.NET

Keeping my eye on the dot

MVC 3 Project Upgrade Tool

MVC 3 Project Upgrade Tool

Rate This
  • Comments 24

We have just released the final version of ASP.NET MVC 3. Read the official MVC 3 release information or download MVC 3.

To help you upgrade your MVC 2 projects to MVC 3 we have released an upgrade tool. You can download it here: http://aspnet.codeplex.com/releases/view/59008. (This is an update of the tool that Eilon Lipton previously previewed on his blog and now we are giving it a more permanent home on our CodePlex site).

April 11 Update: We made a small update to the tool that allows you to skip the backup step. You might want to consider skipping the backup step if you use source control or if your solution is very big.

January 14 Update: We have updated the file on codeplex to fix an issue with converting solutions that had Web Sites or other solution items. If you are having problems please make sure you download the tool again from the codeplex site.

The upgrade tool only supports Visual Studio 2010 projects targeting .NET 4. Upgrading both MVC 2 and MVC 3 Beta (or RC) projects is supported.

The tool does not support Visual Studio 2008 solutions, MVC 1 projects, or projects targeting .NET 3.5. Those projects will first have to be upgraded using Visual Studio 2010 and/or retargeted for .NET 4:

  • If you have a Visual Studio 2008 solution you can simply open it with Visual Studio 2010 to initiate the solution upgrade process.
  • If your projects are targetting .NET 3.5 read how to target .NET 4.
  • If you have a MVC 1.0 project you can use the old version of this tool to convert it to MVC 2.

MVC upgrade tool screenshot

The usage of the tool is quite simple:

  1. If you use a source control system make sure your files are checked out and writable
  2. Run the executable
  3. Select your Visual Studio 2010 solution file that contains your project
  4. Review the changes for each item in the Item details pane
  5. Click on the Convert button to initiate the conversion process
  6. Review the results in the Conversion log pane


During the conversion process the tool will:

  1. Create a backup of the entire solution.
  2. Update all class library projects (including Test projects) that reference System.Web.Mvc.dll to reference version 3.0.
  3. Update all Web Application projects that reference System.Web.Mvc to reference version 3.0 and add references to System.Web.Helpers.dll and System.Web.WebPages.dll.
  4. Change all MVC 2 Web Application projects to be MVC 3 projects (this affects which version of the 'Add View' dialog you get etc) 
  5. Update all MVC Web Application root Web.config files:
    1. Update references to System.Web.Mvc version 3.0.
    2. Add an assembly binding redirect entry for System.Web.Mvc.
    3. Add assembly and namespace references to System.Web.Helpers and System.Web.WebPages.
    4. Add the “ClientValidationEnabled” and “UnobtrusiveJavaScriptEnabled” settings to the <appSettings> element with value “false” if they were not already present (these settings can be used to control the unobtrusive client validation and unobtrusive Ajax features).
  6. Update all MVC Web Application views Web.config files (~\Views\Web.config as well as the views Web.config files for all Areas):
    1. Update references to System.Web.Mvc version 3.0
    2. Add a <configSections> entry required for Razor configuration in MVC
    3. Add the <system.web.webPages.razor> entry required for Razor support in MVC
    4. Add the “webPages:enabled” setting to the <appSettings> element with value “false” (required to prevent .cshtml or .vbhtml files in the Views folder from being directly accessible from a web browser)
  7. Add the following JavaScript libraries to the MVC Web Applications (only if they did not already exist):
    • jQuery 1.4.4 (jquery-1.4.4.js, jquery-1.4.4-vsdoc.js, jquery-1.4.4.min.js)
    • jQuery UI 1.8.7 (jquery-ui.js, jquery-ui.min.js)
    • jQuery Validation 1.7 (jquery-validate.js, jquery-validate-vsdoc.js, jquery-validate.min.js)
    • Microsoft Ajax (MicrosoftAjax.js, Microsoft.Ajax.debug.js)
  8. Overwrite MVC-specific JavaScript files in MVC Web Applications:
    • MicrosoftMvcAjax.js, MicrosoftMvcAjax.debug.js, MicrosoftMvcValidation.js, MicrosoftMvcValidation.debug.js, jquery.unobtrusive-ajax.js, jquery.unobtrusive-ajax.min.js, jquery.validate.unobtrusive.js, jquery.validate.unobtrusive.min.js
  9. Add jQuery UI theme files (stylesheet and images)


This is an unsupported utility and there is a possibility that it might not work correctly for your solution. Specifically, the tool has the following limitations:

  • Read-only project files are not supported (make sure you check out your solution if you use source control)
  • Very long file paths might cause problems
  • Solutions with project files outside of the solution folder might cause problems
  • The tool will not upgrade your application code to account for any potential runtime breaking changes
  • Non-standard project files (e.g. missing MVC project type GUID) will not be handled correctly
  • Once again, VS 2008 solutions, MVC 1 or .NET 3.5 projects are not supported
  • The tool will also not modify any Web Sites in your solution


However, if you run into problems let me know and I will see if we can get them addressed.

  • I have an NullReferenceExpection reported after the solution is backed-up:

    ERROR: There was an error converting the solution file

    Object reference not set to an instance of an object.

    No changes are made to the solution.

    It's VS2010, .NET 4, MVC2.

    After opening a solution in the tool I can see the tree of projects in the tree view with valid upgrade steps displayed for each project.

  • Jakub, could you send me the generated log as well as the solution, project, or web.config file for which the exception gets thrown? Email is marcind at microsoft.

  • It probably doesn't work with web site projects, which isn't surprising, but should be noted..

  • I got the same error as Jakub, the project was also unable to load in VS afterwards.

  • Marcin, I've sent the files in the morning. Thank you!

  • I have the same problem:

    The solution is being backed up to E:\Applications\onyx\src\__MVC_BACKUP

    The solution E:\Applications\onyx\src\onyx.sln is being converted

    ERROR: There was an error converting the solution file

    Object reference not set to an instance of an object.

  • I had the same issue. To fix it I created a blank solution, then added my web project and other libraries that reference system.web.mvc, and converted that. It worked just fine then.

  • Thank you everyone for the reports. I'll have an updated version of the tool posted to the codeplex site soon. In the meantime, Gabe's workaround (creating a new solution and adding your existing projects) should solve the problem.

  • We've posted an updated version of the tool on the codeplex site (same URL) that should fix the issues reported in the earlier comments.

  • Your new solution is working great.

    I have successfully upgraded N2 CMS MVC2 test project to MVC3

  • This worked great! Was fast and simple. Thank you very much

  • Hi, the tool ran fine but when I open the solution and try to add a new view, the Dialog Box does not show my classes from Models and VoewModels Folders. Any hint? I did rebuild the solution again, but the issue persist

  • I've used your tool and it works like charm! Thanks a lot, it saves time :)

  • Any ideas on how to get around the really long path names issue?

  • Shawn, for now you would have to move your project closer to the root directory to achieve shorter file names. We will look at addressing this in the future. Sorry for the inconvenience.

Page 1 of 2 (24 items) 12
Leave a Comment
  • Please add 5 and 1 and type the answer here:
  • Post