Share via

MVC 3 Project Upgrade Tool

  • 01/13/2011

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: https://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.

Comments

  • Anonymous
    January 13, 2011
    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.

  • Anonymous
    January 13, 2011
    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.

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

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

  • Anonymous
    January 14, 2011
    Marcin, I've sent the files in the morning. Thank you!

  • Anonymous
    January 14, 2011
    I have the same problem: The solution is being backed up to E:Applicationsonyxsrc__MVC_BACKUP The solution E:Applicationsonyxsrconyx.sln is being converted ERROR: There was an error converting the solution file Object reference not set to an instance of an object.

  • Anonymous
    January 14, 2011
    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.

  • Anonymous
    January 14, 2011
    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.

  • Anonymous
    January 14, 2011
    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.

  • Anonymous
    February 03, 2011
    Your new solution is working great. I have successfully upgraded N2 CMS MVC2 test project to MVC3

  • Anonymous
    February 10, 2011
    This worked great! Was fast and simple. Thank you very much

  • Anonymous
    February 24, 2011
    The comment has been removed

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

  • Anonymous
    March 21, 2011
    Any ideas on how to get around the really long path names issue?

  • Anonymous
    March 21, 2011
    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.

  • Anonymous
    June 24, 2011
    I get the error Deserialization failed. Verify that the data is being deserialized using the same SerializationMode with which it was serialized

  • Anonymous
    June 24, 2011
    use the helper Html.Serialize in one of my views, to serialize an object, and then I deserialize it again in my Controller using the MvcSerializer like this: (RegistrationViewModel) new MvcSerializer().Deserialize(serializedObject); This worked fine before, but after upgrading to MVC3 (And MVC3 Futures) The Deserialize method has changed so that it now has one more parameter: SerializationMode. This I can set to either Signed or EncryptedAndSigned. Regardless of which of these I use, I get an SerializationException asking me to verify that the data was serialized with the same mode I'm trying to deserialize with. In my view, for some reason IntelliSense is not working for the Serialize method, so I don't know if this has gotten any additional overloads as well. But the question is quite simply: How can I now, in MVC3, deserialize the data inside my controller that I have serialized inside the View with Html.Serialize?

  • Anonymous
    June 24, 2011
    Fernando, your problem does not appear to be related to the upgrade tool itself. forums.asp.net/.../1 is an excellent venue to ask such questions.

  • Anonymous
    January 13, 2012
    We have a solution which fails with the following error, I've replaced specific project and directory name with ProjectA and OurCompany, but otherwise this is exactly as is... ERROR: There was an error loading the solution file Could not find a part of the path 'C:DefaultCollectionProjectAOurCompanyOurCompany.Framework-ProjectAOurCompany.FrameworkOurCompany.Framework.csproj'. When I open the ProjectA solution in VS, the OurCompany.Framework project is located in a solution folder called Framework. (To note, OurCompany.Framework is a branch of the Framework, specific to ProjectA.). I imagine it was set up like that so that the dependent project (Framework) could sit outside the solution structure, though I think it's awful, and the developers that set this up are no longer with us to ask, so I may be wrong. The solution I'm trying to convert is C:DefaultCollectionProjectAProjectAProjectA.sln It would appear that the Upgrade Tool is misunderstanding the relative paths, and considering the Solution Folder (Framework) as a true sub-folder of ProjectA incorrectly. Is this a bug? Is there a workaround? I'm guessing I need to remove the Framework project from the solution and add it back without the Solution Folder, but am keen to hear your thoughts / suggestions? Many thanks in advance, Chris

  • Anonymous
    January 13, 2012
    Chris, at the end of this post I list some limitations of the tool. One of them is "Solutions with project files outside of the solution folder might cause problems". So yes, this is a known issue. One workaround that should work is to move the project so that's under the folder that contains the .sln file. Another would be to create a new temporary .sln file (in the directory above the project directory) and add a project to it.

  • Anonymous
    January 13, 2012
    Hi Marcin, Thanks for your reply - and my apologies for not having spotted the issue in your limitations section. I have since successfully upgrade, by removing the projects from Solution Folders and adding them directly to the solution. I didn't need to move them physically, just add the references again of course, and the upgrade has worked perfectly. Thank you!! Kind regards Chris

  • Anonymous
    January 13, 2012
    In case of any help to others... The TagBuilder class has moved, so to resolve missing assembly reference, add a reference to: System.Web.WebPages (Found in Assemblies -> Extensions)

  • Anonymous
    June 27, 2012
    I got an erro while converting from mvc2 to mvc3 and i can't do te conversion is there any alternate way to do that.? "Access to the path 'C:PortalPortalScriptsjquery-1.4.4.min.js' is denied."

  • Anonymous
    July 28, 2012
    @Nick. Try to download Process Monitor fra SysInternals. It can help you troubleshoot why you get an access denied.