MVC 3 Project Upgrade Tool

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: (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.