Currently, Visual Studio won't give you any ASP.NET MVC-specific tooling support (e.g., the options to add areas, controllers, or views), nor will it offer any MVC-specific file types when you choose Add

To change this, you need to add a project type hint for Visual Studio.

You should now find that MVC-specific items appear in the Add

Next, add the ASP.NET MVC 2 assembly and its dependencies to your project:

Figure 18-2. Preparing System.Web.Mvc for bin deployment

All ASP.NET MVC applications rely on the routing system, so let's set that up now.

You should now have a working routing system. Don't worry, this won't interfere with requests that directly target existing *.aspx pages, since by default, routing gives priority to files that actually exist on disk.

To verify that your routing system is working, you'll need to add at least one MVC controller, as follows:

You can now visit /Home again, and you'll see your view rendered, as in Figure 18-4.

Figure 18-4. The Web Forms project is now also an MVC project.

That's it—you're done! Your Web Forms project should continue to work normally when you visit any of the existing .aspx pages (because files on disk take priority over routing), and you can also add controllers and views, and configure routing exactly as you would in an ASP.NET MVC application.

After upgrading a Web Forms project to support MVC, you're in the same position as if you had started with an MVC project and then added a whole set of Web Forms pages. This means, for example, that if you want to add routing support for your Web Forms pages (instead of continuing to use URLs matching their disk paths), you can follow the advice later in this chapter, in the section "Adding Routing Support for Web Forms Pages."

If you're targeting .NET 4, then your Web Forms pages have built-in support for routing, so you can generate URLs and perform redirections to MVC actions as follows:

protected void Page_Load(object sender, EventArgs e)
{
    // You can generate a URL based on routing parameters
    string url = Page.GetRouteUrl(new { controller = "Home", action = "Index" });

    // ... or you can redirect to a location based on routing parameters
    Response.RedirectToRoute(new { controller = "Home", action = "Index" });
}

But if you're targeting .NET 3.5, those methods don't exist. Web Forms isn't aware of routing. No problem—you can implement those methods yourself as extension methods. For example, add the following class anywhere in your project:

// This class is only relevant for .NET 3.5
public static class WebFormsRoutingExtensions
{
   public static string GetRouteUrl(this Control control, object routeValues)
   {
      return GetRouteUrl(routeValues).VirtualPath;

}

   public static void RedirectToRoute(this HttpResponse resp, object routeValues)
   {
      resp.Redirect(GetRouteUrl(routeValues).VirtualPath);
   }

   private static VirtualPathData GetRouteUrl(object values)
   {
      var httpContext = new HttpContextWrapper(HttpContext.Current);
      var rc = new RequestContext(httpContext, new RouteData());
      return RouteTable.Routes.GetVirtualPath(rc, new RouteValueDictionary(values));
   }
}

Now, as long as you've referenced the namespace containing this class, you'll be able to generate URLs and redirect to MVC actions as shown in the preceding Page_Load() code sample.

You won't be able to use MVC's Html.* helper methods from your Web Forms pages, because System.Web.UI.Page doesn't have a property of type HtmlHelper (whereas Html is a property of System.Web.Mvc.ViewPage). That's fine, because you wouldn't use, for example, Html.TextBox() from a Web Forms page anyway—MVC HTML helpers don't survive postbacks. But if you can't use Html.ActionLink(), how should your Web Forms pages render link tags referencing an MVC actions?

If you're targeting .NET 4, you can use an expression builder called RouteUrl that obtains URLs from the routing system—for example:

<asp:HyperLink NavigateUrl="<%$ RouteUrl: controller=Home, action=Index %>"
               runat="server">
    Visit the Index action on HomeController
</asp:HyperLink>

But if you're targeting .NET 3.5, that expression builder isn't available. You can instead use the GetRouteUrl() extension method we defined earlier, as long as you've referenced its namespace in Web.config's <pages>/<namespaces> node—for example:

<a href="<%= Page.GetRouteUrl(new { controller = "Home", action = "Index"}) %>">
    Visit the Index action on HomeController
</a>

The two technologies are built on the same core ASP.NET platform, so when they're both in the same application, they share the same Session and Application collections (among others). It's also possible, though more tricky, to use TempData to share data between the two technologies. These options are explained in more detail in Table 18-1.

The notion of "temp data" is specific to ASP.NET MVC, so Web Forms doesn't come with an easy way to access it. It is possible, but you'll need to write your own code to retrieve the collection from its underlying storage. The following example shows how to create an alternative Page base class that exposes a collection called TempData, loading its contents at the beginning of a request, and saving them at the end of the request:

public class TempDataAwarePage : System.Web.UI.Page
{
    protected readonly TempDataDictionary TempData = new TempDataDictionary();

    protected override void OnInit(EventArgs e) {
        base.OnInit(e);
        TempData.Load(GetDummyContext(), new SessionStateTempDataProvider());
    }

    protected override void OnUnload(EventArgs e) {
        TempData.Save(GetDummyContext(), new SessionStateTempDataProvider());
        base.OnUnload(e);
    }

    // Provides enough context for TempData to be loaded and saved
    private static ControllerContext GetDummyContext()
    {
        return new ControllerContext(
            new HttpContextWrapper(HttpContext.Current),
            new RouteData(),
            _dummyControllerInstance

);
    }

    // Just fulfills tempData.Load()'s requirement for a controller object
    private static Controller _dummyControllerInstance = new DummyController();
    private class DummyController : Controller { }
}

Now, if you change your Web Forms pages to derive from TempDataAwarePage instead of from System.Web.UI.Page, you'll have access to a field called TempData that behaves exactly like an MVC controller's TempData collection, and in fact shares the same data. If you'd rather not change the base class of your Web Forms pages, you can use the preceding example code as a starting point for creating a utility class for manually loading and saving TempData when in a Web Forms page.

If you're targeting .NET 4, it's relatively easy to fit Web Forms pages into the routing system. Just use MapPageRoute() in the RegisterRoutes() method in your Global.asax.cs file:

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

    routes.MapPageRoute(
            "UserInfo",                 // Route name
            "users/{userName}",         // URL
            "~/WebForms/ShowUser.aspx"  // Physical ASPX file
    );

    // Also add your MVC routes here
}

Now the URL /users/anything will be handled by /WebForms/ShowUser.aspx. Internally, MapPageRoute() uses a route handler called System.Web.Routing.PageRouteHandler, which knows how to locate and compile ASPX pages. Just like MVC's MapRoute(), Web Forms' MapPageRoute() has overloads for specifying parameter defaults and constraints.

To generate outbound URLs to Web Forms pages, you'll usually need to specify the route name to be matched. In the preceding example, the route entry was called UserInfo, so you can create a Web Forms hyperlink with a clean URL as follows:

<asp:HyperLink runat="server"
               NavigateUrl="<%$ RouteUrl:RouteName=UserInfo, UserName:Bob %>">
    Go to the user list
</asp:HyperLink>

or you can perform a redirection to it from a Web Forms code-behind handler, as follows:

Response.RedirectToRoute("UserInfo", new { userName = "Bob" });

or you can generate a link to it from an MVC view, as follows:

<%: Html.RouteLink("Go to the user list", "UserList", new { userName = "Bob" }) %>

or you can perform a redirection to it from an MVC action method, as follows:

return RedirectToRoute("UserList", new { userName = "Bob" });

If your URL pattern includes a curly brace parameter, then the matching Web Forms page can read its value. In code-behind methods, use the RouteData property (e.g., RouteData.Values["userName"]), or to set properties on server controls, use the RouteValue expression builder—for example:

<asp:TextBox runat="server" Text="<%$ RouteValue: userName %>" />

If you're targeting .NET 3.5, you'll need to do a bit more work, because there's no built-in MapPageRoute() method, and Web Forms generally isn't aware of routing.

To fit Web Forms into routing, you first need to define a custom route entry type suitable for use with Web Forms pages. The following route entry type, WebFormsRoute, knows how to use BuildManager.CreateInstanceFromVirtualPath() to locate, compile, and instantiate a Web Forms page. Unlike .NET 4's native Web Forms routing code, this route entry type is careful not to interfere with outbound URL generation except when you specifically supply a virtualPath parameter that corresponds to its own.

using System.Web.Compilation;
public class WebFormsRoute : Route
{
    // Constructor is hard-coded to use the special WebFormsRouteHandler
    public WebFormsRoute(string url, string virtualPath)
        : base(url, new WebFormsRouteHandler { VirtualPath = virtualPath }) { }

    public override VirtualPathData GetVirtualPath(RequestContext requestContext,
                                                   RouteValueDictionary values)
    {
        // Only generate outbound URL when "virtualPath" matches this entry
        string path = ((WebFormsRouteHandler)this.RouteHandler).VirtualPath;
        if ((string)values["virtualPath"] != path)
            return null;
        else
        {
            // Exclude "virtualPath" from the generated URL, otherwise you'd
            // get URLs such as /some/url?virtualPath=~/Path/Page.aspx
            var valuesExceptVirtualPath = new RouteValueDictionary(values);
            valuesExceptVirtualPath.Remove("virtualPath");
            return base.GetVirtualPath(requestContext, valuesExceptVirtualPath);

}
    }

    private class WebFormsRouteHandler : IRouteHandler
    {
       public string VirtualPath { get; set; }
       public IHttpHandler GetHttpHandler(RequestContext requestContext)
       {
          // Store RouteData so it can be read back later
          requestContext.HttpContext.Items["routeData"] = requestContext.RouteData;

          // Compiles the ASPX file (if needed) and instantiates the web form
          return (IHttpHandler)BuildManager.CreateInstanceFromVirtualPath
                                              (VirtualPath, typeof(IHttpHandler));
       }
    }
}

Once you've defined this class (anywhere in your MVC web application project), you can use it to set up Route entries to Web Forms pages. For example, add the following route entry to RegisterRoutes() in Global.asax.cs:

routes.Add(new WebFormsRoute("users/{userName}", "~/WebForms/ShowUser.aspx"));

As you'd expect, this will expose ~/WebForms/ShowUser.aspx on the URL /users/anything. Now you can also generate links or redirections to that route entry—for example, from an MVC view:

<%= Html.RouteLink("Go to the user list",
            new { virtualPath="~/WebForms/ShowUser.aspx", userName = "bob" }) %>

or from an MVC action:

return RedirectToRoute(new {
    virtualPath = "~/WebForms/ShowUser.aspx",
    userName = "bob"
});

or from a Web Forms page code-behind event handler, if you reference the namespace of the WebFormsRoutingExtensions extension method class from earlier in this chapter:

void myButton_Click(object sender, EventArgs e)
{
    Response.RedirectToRoute(new {
        virtualPath = "~/WebForms/ShowUser.aspx",
        userName = "bob"

});
}

All of these will return the clean URL to the browser (in this example, that's /users/bob). You can't easily use named routes with this code—instead, it uses the ASPX page's virtual path as both a unique route name and as a required routing parameter to avoid interfering with MVC routes' outbound URL generation.

To read routing parameters in Web Forms pages, add the following extension method:

public static class WebFormsRoutingExtensions
{
    public static RouteData GetRouteData(this Control control)
    {
        return (RouteData)HttpContext.Current.Items["routeData"];
    }

    // If you already have this class, leave the other methods in place
}

Now, assuming you've referenced this class's namespace, then you can access routing parameters in Web Forms code-behind classes—for example:

protected void Page_Load(object sender, EventArgs e)
{
    myLabel.Text = this.GetRouteData().Values["userName"];
}

Also, if you've added WebFormsRoutingExtensions' namespace to the <pages>/<namespaces> node in your Web.config file, you can also access routing parameter values in ASPX inline code—for example:

<%= Page.GetRouteData().Values["userName"] %>

If you're targeting .NET 4, then this way of registering route entries is also compatible with the built-in expression builders, so you can also read routing parameter values or generate outbound URLs as follows:

<asp:Literal runat="server" Text="<%$ RouteValue:userName %>" />
<asp:HyperLink NavigateUrl="<%$ RouteUrl: virtualPath=~/WebForms/ShowUser.aspx,
                                          userName=bob %>" runat="server">
    Click me
</asp:HyperLink>

I mentioned earlier that .NET 4's native routing helper knows about UrlAuthorizationModule, so if you're using URL-based authorization, it checks that the user is allowed to visit both the clean URL and the URL of the ASPX file to which it maps.

However, the .NET 3.5-compatible code I've just shown doesn't do that. So, if you're using URL-based authorization (which very few MVC developers do), then you need to add authorization rules for your clean routing URLs, not just for the paths to the ASPX files that handle those URLs.

In other words, if you want to protect a Web Forms page exposed by the following route entry:

routes.Add(new WebFormsRoute("some/url/{PersonName}", "~/Path/MyPage.aspx"));

then don't configure URL-based authorization as follows:

<configuration>
  <location path="Page/MyPage.aspx">
    <system.web>
      <authorization>
        <allow roles="administrator"/>
        <deny users="*"/>
      </authorization>
    </system.web>
  </location>
</configuration>

Instead, configure it as follows:

<configuration>
  <location path="some/url">
    <system.web>
      <authorization>
        <allow roles="administrator"/>
        <deny users="*"/>
      </authorization>
    </system.web>
  </location>
  <location path="Page/MyPage.aspx"> <!-- Prevent direct access -->
    <system.web>
      <authorization>
        <deny users="*"/>
      </authorization>
    </system.web>
  </location>
</configuration>

This is because UrlAuthorizationModule is only concerned about the URLs that visitors request, and doesn't know or care what ASPX file, if any, will ultimately handle the request.

During the upgrade process, Visual Studio 2010's Conversion Wizard will bring up the prompt shown in Figure 18-7, asking if you'd like to switch to targeting .NET 4.

Figure 18-7. Visual Studio 2010 will ask permission to target .NET 4

Of course, you should only say yes if you'll later be deploying to a server with .NET 4 installed. If you agree to target .NET 4, then the Conversion wizard will carry out the following additional upgrade steps:

After upgrading from ASP.NET MVC 1 to ASP.NET MVC 2, you might have a little surprise when you first deploy to your production servers.

The anti-forgery tokens that you can generate using Html.AntiForgeryToken() store an encrypted, serialized data structure. ASP.NET MVC 2 uses a newer data format and can't read the tokens generated by ASP.NET MVC 1. So, if you deploy your upgraded application while visitors are actively using your site, their __RequestValidationToken cookies will suddenly become invalid, leading to HttpAntiForgeryException errors. Visitors won't be able to continue using your site until they clear their session cookies by closing and reopening their browsers.

For a small intranet application, this might be OK—you can edit your global error handler page to display a prominent message saying, "If you're having problems, please try closing and reopening your browser." But for larger, public Internet applications, inconveniencing visitors in this way may not be acceptable.

public class MvcApplication : System.Web.HttpApplication
{
    protected void Application_Error(object sender, EventArgs e)
    {
        var application = (HttpApplication) sender;
        if (IsHttpAntiForgeryTokenException(application.Server.GetLastError()))
            HandleAntiForgeryCookieFormatError(application);
    }
}

private static bool IsHttpAntiForgeryTokenException(Exception exception)
{
    // Scan up the chain of InnerExceptions
    while (exception != null) {
        if (exception is HttpAntiForgeryException)
            return true;
        exception = exception.InnerException;
    }
    return false;
}

private static void HandleAntiForgeryCookieFormatError(HttpApplication application)
{
    var antiForgeryCookieNames = application.Request.Cookies.Cast<string>()
        .Where(x => x.StartsWith("__RequestVerificationToken"))
        .ToList();

    // To delete a cookie, send a new pre-expired cookie with the same name
    foreach (var cookieName in antiForgeryCookieNames)
        application.Response.Cookies.Add(new HttpCookie(cookieName) {
            Expires = new DateTime(2000, 1, 1)
        });

    application.Response.Redirect("~/Home/UpgradeNotice");
}