Why does my MVC project throw exceptions on production servers after installing WebMatrix 2 Beta?

After installing WebMatrix 2 Beta on my development machine, an MVC project compiled on that machine and deployed to a production server will start throwing a FileNotFoundException looking for System.Web.WebPages.

"...System.IO.FileNotFoundException: Could not load file or assembly 'System.Web.WebPages,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3开发者_如何学Go856ad364e35' or one of its dependencies.
The system cannot find the file specified.  File name: 'System.Web.WebPages, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35'..."

I couldn't find anything on Google to help with this, so I am asking and answering this here for anyone else that runs into this situation. It is a fairly obscure set of circumstances that lead up to this problem.

If you have a fairly old MVC project that you have been upgrading over the various releases, you may have an unversioned project reference to System.Web.WebPages.

<Reference Include="System.Web.WebPages" />

This works fine as long as the version your project finds where compiled matches the version available where it is deployed.

Installing WebMatrix 2 Beta will add a new version of this DLL. Your MVC project will start pulling v2.0.0.0 for compilation. When you move to a system without WebMatrix 2 Beta installed, it will not be able to find v2 and will throw the above exception.

---

I spun up a new MVC 3 project and noticed that there are a couple references that are fully qualified in the new project and much more generic in the problem project.

<Reference Include="System.Web.WebPages, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL" />
<Reference Include="System.Web.Helpers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL" />

If you switch to these project references instead of the generic ones (<Reference Include="..." />), you will make sure the project is compiled with the expected version of the DLL rather than picking up the latest one available on the system.