In model-view-controller (MVC) architecture, incoming requests are handled by controllers. In ASP.NET MVC, controllers are just simple C# classes (usually inheriting from System.Web.Mvc.Controller, the framework's built-in controller base class).^[7] Each public method on a controller is known as an action method, which means you can invoke it from the Web via some URL.

The default project template includes a folder called Controllers. It isn't compulsory to put your controllers here, but it is a helpful convention. So, to add the first controller, right-click the Controllers folder in Visual Studio's Solution Explorer and choose Add

Figure 2-3. Adding a new controller, HomeController, to the project

Next, when HomeController.cs appears, remove any code that it already contains, and replace the whole HomeController class with this:

public class HomeController : Controller
{
    public string Index()
    {
        return "Hello, world!";
    }
}

It isn't very exciting—it's just a way of getting right down to basics. Try running the project now (press F5 again), and you should see your message displayed in a browser (Figure 2-4).

Figure 2-4. The initial application output

As well as models, views, and controllers, ASP.NET MVC applications also use the routing system. This piece of infrastructure decides how URLs map onto particular controllers and actions. Under the default routing configuration, you could request any of the following URLs and it would be handled by the Index action on HomeController:

So, when a browser requests http://yoursite/ or http://yoursite/Home, it gets back the output from HomeController's Index method. Right now, the output is the string Hello, world!.

You can see and edit your routing configuration by opening your project's Global.asax.cs file, but for this chapter's simple example, the default configuration will suffice. In Chapter 4 you'll set up custom routing entries, and in Chapter 8 you'll learn much more about what routing can do.

Your existing controller, HomeController, currently sends a plain-text string to the browser. That's fine for debugging, but in real applications you're more likely to generate an HTML document, and you do so by using a view.

To render a view from your Index() method, first rewrite the method as follows:

public class HomeController : Controller
{
    public ViewResult Index()
    {
        return View();
    }

}

By returning an object of type ViewResult, you're giving the MVC Framework an instruction to render a view. Because you're generating that ViewResult object by calling View() with no parameters, you're telling the framework to render the action's default view. However, if you try to run your application now, you'll get the error message displayed in Figure 2-5.

Figure 2-5. Error message shown when ASP.NET MVC can't find a view template

Again, I'm showing you this error message so you can see exactly what the framework is trying to do and so you don't think there's some hidden magic happening. This error message is more helpful than most—the framework tells you not just that it couldn't find any suitable view to render, but also where it tried looking for one. Here's your first bit of convention-over-configuration: view files are normally associated with action methods by means of a naming convention, rather than by means of explicit configuration. When the framework wants to find the default view for an action called Index on a controller called HomeController, it will check the four locations listed in Figure 2-5.

To add a view for the Index action—and to make that error go away—right-click the action method (either on the Index() method name or somewhere inside the method body) and then choose Add View. This will lead to the pop-up window shown in Figure 2-6.

Figure 2-6. Adding a view template for the Index action

Uncheck "Select master page" (since we're not using master pages in this example) and then click Add. This will create a brand new view file for you at the correct default location for your action method: ~/Views/Home/Index.aspx.

As Visual Studio's HTML markup editor appears,^[8] you'll see something familiar: an HTML page prepopulated with the usual collection of elements—<html>, <body>, and so on. Let's move the Hello, world! greeting into the view. Replace the whole <body> section of the HTML markup with

<body>
   Hello, world (from the view)!
</body>

Press F5 to launch the application again, and you should see your view template at work (Figure 2-7).

Figure 2-7. Output from the view

Previously, your Index() action method simply returned a string, so the MVC Framework had nothing to do but send that string as the HTTP response. Now, though, you're returning an object of type ViewResult, which instructs the MVC Framework to render a view. You didn't specify a view name, so it picks the conventional one for this action method (i.e., ~/Views/Home/Index.aspx).

Besides ViewResult, there are other types of objects you can return from an action, which instruct the framework to do different things. For example, RedirectResult performs a redirection, and HttpUnauthorizedResult forces the visitor to log in. These things are called action results, and they all derive from the ActionResult base class. You'll learn about each of them in due course. This action results system lets you encapsulate and reuse common response types, and it simplifies unit testing tremendously.

Of course, the whole point of a web application platform is the ability to construct and display dynamic output. In ASP.NET MVC, it's the controller's job to construct some data, and the view's job to render it as HTML. This separation of concerns keeps your application tidy. The data is passed from controller to view using a data structure called ViewData.

As a simple example, alter your HomeController's Index() action method (again) to add a string into ViewData:

public ViewResult Index()
{
    int hour = DateTime.Now.Hour;
    ViewData["greeting"] = (hour < 12 ? "Good morning" : "Good afternoon");
    return View();
}

and update your Index.aspx view template to display it as follows. If you're using Visual Studio 2010 and chose to target .NET Framework 4 when you first created the project, write

<body>
   <%: ViewData["greeting"] %>, world (from the view)!
</body>

Otherwise, if you're using Visual Studio 2008 or targeting .NET Framework 3.5, write

<body>
   <%= Html.Encode(ViewData["greeting"]) %>, world (from the view)!
</body>

Not surprisingly, when you run the application again (press F5), your dynamically chosen greeting will appear in the browser (Figure 2-8).

Figure 2-8. Dynamically generated output

Your friend is having a New Year's party, and she's asked you to create a web site that allows invitees to send back an electronic RSVP. This application, PartyInvites, will

I can't promise that it will be enough for you to retire as a Web 3.0 billionaire, but it's a good start. You can implement the first bullet point feature immediately: just add some HTML to your existing Index.aspx view. If you're using Visual Studio 2010/.NET 4, update the view as follows:

<body>
    <h1>New Year's Party</h1>
    <p>
        <%: ViewData["greeting"] %>! </para>
        We're going to have an exciting party. </para>
        (To do: sell it better. Add pictures or something.)
    </p>
</body>

Or, if you're using Visual Studio 2008/.NET 3.5, update it as follows:

<body>
    <h1>New Year's Party</h1>
    <p>
        <%= Html.Encode(ViewData["greeting"]) %>!
        We're going to have an exciting party.
        (To do: sell it better. Add pictures or something.)
    </p>
</body>

You could go right ahead and create lots more actions and views, but before you do that, take a step back and think about the application you're building.

In MVC, M stands for model, and it's the most important character in the story. Your model is a software representation of the real-world objects, processes, and rules that make up the subject matter, or domain, of your application. It's the central keeper of data and domain logic (i.e., business processes and rules). Everything else (controllers and views) is merely plumbing needed to expose the model's operations and data to the Web. A well-crafted MVC application isn't just an ad hoc collection of controllers and views; there's always a model, a recognizable software component in its own right. The next chapter will cover this architecture, with comparisons to others, in more detail.

You don't need much of a domain model for the PartyInvites application, but there is one obvious type of model object that we'll use, which we'll call GuestResponse. This object will be responsible for storing, validating, and ultimately confirming an invitee's RSVP.

public class GuestResponse
{
    public string Name { get; set; }
    public string Email { get; set; }
    public string Phone { get; set; }
    public bool? WillAttend { get; set; }
}

There's going to be an RSVP form, so you'll need to place a link to it. Update Index.aspx as follows if you're using Visual Studio 2010/.NET 4:

<body>
    <h1>New Year's Party</h1>
    <p>
        <%:ViewData["greeting"] %>!
        We're going to have an exciting party.
        (To do: sell it better. Add pictures or something.)
    </p>
    <%: Html.ActionLink("RSVP Now", "RsvpForm") %>
</body>

Or, if you're using Visual Studio 2008/.NET 3.5, update it as follows (don't worry, I'll stop talking about these differences in a moment):

<body>
    <h1>New Year's Party</h1>
    <p>
        <%= Html.Encode(ViewData["greeting"]) %>!
        We're going to have an exciting party.
        (To do: sell it better. Add pictures or something.)
    </p>
    <%= Html.ActionLink("RSVP Now", "RsvpForm") %>
</body>

<%= Html.Encode(ViewData["greeting"]) %>

Run the project again, and you'll see the new link, as shown in Figure 2-9.

Figure 2-9. A view with a link

But if you click the RSVP Now link, you'll get a 404 Not Found error. Check out the browser's address bar: it will read http://yourserver/Home/RsvpForm.

That's because Html.ActionLink() inspected your routing configuration and figured out that, under the current (default) configuration, /Home/RsvpForm is the URL for an action called RsvpForm on a controller called HomeController. Unlike in traditional ASP.NET Web Forms, PHP, and many older web development platforms, URLs in ASP.NET MVC don't correspond to files on the server's hard disk—instead, they're mapped through a routing configuration onto a controller and action method. Each action method automatically has its own URL; you don't need to create a separate page or class for each URL.

Of course, the reason for the 404 Not Found error is that you haven't yet defined any action method called RsvpForm(). Add a new method to your HomeController class:

public ViewResult RsvpForm()
{
    return View();
}

Introducing Strongly Typed Views

Again, you'll need to add a view for that new action. But first, make sure you've compiled your code either by pressing F5 to run it again, by choosing Build

Next, to create the view for RsvpForm(), right-click inside the RsvpForm() method and then choose Add View. This time, the view will be slightly different: we'll specify that it's primarily intended to render a single specific type of model object, as opposed to the previous view, which just rendered an ad hoc collection of things found in the ViewData structure. This makes it a strongly typed view, and you'll see the benefit of it shortly.

Figure 2-10 shows the options you should use in the Add View pop-up. Make sure that "Select master page" is unchecked, and this time check the box labeled "Create a strongly typed view." In the "View data class" drop-down, select the GuestResponse type. Leave "View content" set to Empty. Finally, click Add.

Figure 2-10. To create a strongly typed view, specify a view data class.

When you click Add, you'll get a new view at this action's default view location, ~/Views/Home/RsvpForm.aspx. If you try running the application now, then when you click the RSVP Now link, your new view should render as a blank page in the browser.

Tip

Practice jumping quickly from an action method to its default view and back again. In Visual Studio, position the caret inside either of your action methods, right-click, and choose Go To View, or press Ctrl+M and then Ctrl+G. You'll jump directly to the action's default view. To jump from a view to its associated action, right-click anywhere in the view markup and choose Go To Controller, or press Ctrl+M and then Ctrl+G again. This saves you from hunting around when you have lots of tabs open.

It's now time to work on RsvpForm.aspx, turning it into a form for editing instances of GuestResponse. Go back to RsvpForm.aspx and use ASP.NET MVC's built-in helper methods to construct an HTML form:

<body>
    <h1>RSVP</h1>

    <% using(Html.BeginForm()) { %>
        <p>Your name: <%: Html.TextBoxFor(x => x.Name) %></p>
        <p>Your email: <%: Html.TextBoxFor(x => x.Email) %></p>
        <p>Your phone: <%: Html.TextBoxFor(x => x.Phone) %></p>
        <p>
            Will you attend?
            <%: Html.DropDownListFor(x => x.WillAttend, new[] {
                new SelectListItem { Text = "Yes, I'll be there",
                                     Value = bool.TrueString },
                new SelectListItem { Text = "No, I can't come",
                                     Value = bool.FalseString }
            }, "Choose an option") %>
        </p>
        <input type="submit" value="Submit RSVP" />
    <% } %>
</body>

For each model property, you're using an HTML helper to render a suitable input control. These HTML helpers let you pick out a model property using a lambda expression (i.e., the x => x.PropertyName syntax). This is only possible because your view is strongly typed, which means the framework already knows what model type you're using and therefore what properties it has. In case you're unfamiliar with lambda expressions, which were introduced in C# 3, there's an explanation at the end of Chapter 3.

As an alternative to using a lambda expression, you could use a different HTML helper that lets you specify the target model property as a string—for example, <%: Html.TextBox("Phone") %>. However, the great benefit of lambda expressions is that they're strongly typed, so you get full IntelliSense when editing the view (as shown in Figure 2-11), and if you use a refactoring tool to rename a model property, all your views will be updated automatically.

Figure 2-11. IntelliSense while editing a strongly typed view

I should also point out the <% using(Html.BeginForm(...)) { ... } %> helper syntax. This creative use of C#'s using syntax renders an opening HTML <form> tag where it first appears and a closing </form> tag at the end of the using block. You can pass parameters to Html.BeginForm(), telling it which action method the form should post to when submitted, but since you're not passing any parameters to Html.BeginForm(), it assumes you want the form to post to the same URL from which it was rendered. So, this helper will render the following HTML:

<form action="/Home/RsvpForm" method="post" >
    ... form contents go here ...
</form>

I'm sure you're itching to try your new form out, so relaunch your application and click the RSVP Now link. Figure 2-12 shows your glorious form in all its magnificent, raw beauty.^[9]

Figure 2-12. Output from the RsvpForm.aspx view

To receive and process submitted form data, we're going to do a clever thing. We'll slice the RsvpForm action down the middle, creating the following:

Writing these as two separate C# methods helps keep your code tidy, since the two methods have totally different responsibilities. However, from outside, the pair of C# methods will be seen as a single logical action, since they will have the same name and are invoked by requesting the same URL.

Replace your current single RsvpForm() method with the following:

[HttpGet]
public ViewResult RsvpForm()
{
    return View();
}

[HttpPost]
public ViewResult RsvpForm(GuestResponse guestResponse)
{
    // Todo: E-mail guestResponse to the party organizer
    return View("Thanks", guestResponse);
}

No doubt you can guess what the [HttpGet] and [HttpPost] attributes do. When present, they restrict which type of HTTP request an action will respond to. The first RsvpForm() overload will only respond to GET requests; the second RsvpForm() overload will only respond to POST requests.

Rendering Arbitrary Views and Passing a Model Object to Them

The second overload of RsvpForm() also demonstrates how to render a specific view template that doesn't necessarily match the name of the action, and how to pass a single, specific model object that you want to render. Here's the line I'm talking about:

return View("Thanks", guestResponse);

This line tells ASP.NET MVC to find and render a view called Thanks, and to supply the guestResponse object to that view. Since this all happens in a controller called HomeController, ASP.NET MVC will expect to find the Thanks view at ~/Views/Home/Thanks.aspx, but of course no such file yet exists. Let's create it.

Create the view by right-clicking inside any action method in HomeController and then choosing Add View. This will be another strongly typed view because it will receive and render a GuestResponse instance. Figure 2-13 shows the options you should use in the Add View pop-up. Enter the view name Thanks, make sure that "Select master page" is unchecked, and again check the box labeled "Create a strongly typed view." In the "View data class" drop-down, select the GuestResponse type. Leave "View content" set to Empty. Finally, click Add.

Figure 2-13. Adding a strongly typed view to work with a particular model class

Once again, Visual Studio will create a new view templatefor you at the location that follows ASP.NET MVC conventions (this time, it will go at ~/Views/Home/Thanks.aspx). This view is strongly typed to work with a GuestResponse instance, so you'll have access to a variable called Model, of type GuestResponse, which is the instance being rendered. Enter the following markup:^[10]

<body>
    <h1>Thank you, <%: Model.Name %>!</h1>
    <% if(Model.WillAttend == true) { %>
           It's great that you're coming. The drinks are already in the fridge!
    <% } else { %>
           Sorry to hear you can't make it, but thanks for letting us know.
    <% } %>
</body>

You can now fire up your application, fill in the form, submit it, and see a sensible result, as shown in Figure 2-14.

Figure 2-14. Output from the Thanks.aspx view

You may have noticed that so far, there's no validation whatsoever. You can type in any nonsense for an e-mail address, or even just submit a completely blank form.

It's time to rectify that, but before you go looking for the validation controls, remember that this is an MVC application, and following the don't-repeat-yourself principle, validation rules apply to a model, not a user interface. Validation often reflects business rules, which are most maintainable when expressed coherently in one and only one place, not scattered variously across multiple controller classes and ASPX and ASCX files.

The .NET class library has a namespace called System.ComponentModel.DataAnnotations that includes attributes you can use to define validation rules declaratively. To use them, go back to your GuestResponse model class and update it as follows:

public class GuestResponse
{
    [Required(ErrorMessage="Please enter your name")]
    public string Name { get; set; }

    [Required(ErrorMessage = "Please enter your email address")]
    [RegularExpression(".+\@.+\..+",
                       ErrorMessage = "Please enter a valid email address")]
    public string Email { get; set; }

    [Required(ErrorMessage = "Please enter your phone number")]
    public string Phone { get; set; }

    [Required(ErrorMessage = "Please specify whether you'll attend")]
    public bool? WillAttend { get; set; }
}

ASP.NET MVC automatically recognizes your model's Data Annotations attributes and uses them to validate incoming data when it performs model binding. Let's update the second RsvpForm() action method so that if there were any validation errors, it redisplays the default view instead of rendering the Thanks view:

[HttpPost]
public ViewResult RsvpForm(GuestResponse guestResponse)
{
    if (ModelState.IsValid) {
        // To do: E-mail guestResponse to the party organizer
        return View("Thanks", guestResponse);
    }
    else // Validation error, so redisplay data entry form
        return View();
}

Finally, choose where to display any validation error messages by adding an Html.ValidationSummary() to the form in the RsvpForm.aspx view:

<body>
    <h1>RSVP</h1>

    <% using(Html.BeginForm()) { %>
        <%: Html.ValidationSummary() %>
        ... leave rest as before ...

And now, if you try to submit a blank form or enter invalid data, you'll see the validation kick in (Figure 2-15).

Figure 2-15. The validation feature working

Highlighting Invalid Fields

The built-in HTML helpers for text boxes, drop-downs, and so on have a further neat trick. The same mechanism that lets helpers reuse previously attempted values (to retain state) also tells the helpers whether the previously attempted value was valid or not. If it was invalid, the helper automatically adds an extra CSS class so that you can highlight the invalid field for the user.

For example, after a blank form submission, <%: Html.TextBoxFor(x => x.Email) %> will produce the following HTML:

<input class="input-validation-error" id="Email" name="Email" type="text" value=""/>

The easiest way to highlight invalid fields is to reference a CSS style sheet, /Content/site.css, that's included by default in all new ASP.NET MVC 2 projects. Go to your RsvpForm.aspx view and add a new stylesheet reference to its <head> section:

<head runat="server">
    <title>RsvpForm</title>
    <link rel="Stylesheet" href="~/Content/Site.css" />
</head>

Now, all input controls with the CSS class input-validation-error will be highlighted, as shown in Figure 2-16.

Figure 2-16. Retaining state and highlighting invalid fields after validation error

The final requirement is to e-mail completed RSVPs to the party organizer. You could do this directly from an action method, but it's more logical to put this behavior into the model. After all, there could be other UIs that work with this same model and want to submit GuestResponse objects.

To construct the outgoing e-mail, start by adding the following method to GuestResponse:^[11]

private MailMessage BuildMailMessage()
{
    var message = new StringBuilder();
    message.AppendFormat("Date: {0:yyyy-MM-dd hh:mm}
", DateTime.Now);
    message.AppendFormat("RSVP from: {0}
", Name);
    message.AppendFormat("Email: {0}
", Email);
    message.AppendFormat("Phone: {0}
", Phone);
    message.AppendFormat("Can come: {0}
", WillAttend.Value ? "Yes" : "No");
    return new MailMessage(
        "[email protected]",                                            // From
        "[email protected]",                                 // To
        Name + (WillAttend.Value ? " will attend" : " won't attend"), // Subject
        message.ToString()                                            // Body
    );
}

Next, add a further method that uses BuildMailMessage() to actually deliver the e-mail to the site administrator. If you're running Visual Studio 2010 and .NET 4, add the following to the GuestResponse class:

public void Submit() // .NET 4 version
{
    using (var smtpClient = new SmtpClient())
    using (var mailMessage = BuildMailMessage()) {
        smtpClient.Send(mailMessage);
    }
}

However, if you're running Visual Studio 2008 or targeting .NET 3.5, you'll find that neither MailMessage nor SmtpClient is a disposable type (which means you can't put it in a using block to release its resources immediately), so you should instead express the method more simply, as follows:

public void Submit() // .NET 3.5 version
{
    new SmtpClient().Send(BuildMailMessage());
}

Finally, call guestResponse.Submit() from the second RsvpForm() overload, thereby sending the guest response by e-mail only if it's valid:

[HttpPost]

public ViewResult RsvpForm(GuestResponse guestResponse)
{
    if (ModelState.IsValid)
    {
        guestResponse.Submit();
        return View("Thanks", guestResponse);
    }
    else // Validation error, so redisplay data entry form
        return View();
}

Of course, it's more common to store model data in a database than to send it by e-mail. The major example in Chapter 4 will demonstrate one possible way to use ASP.NET MVC with SQL Server.

<configuration>
  <system.net>
    <mailSettings>
      <smtp deliveryMethod="Network">
        <network host="smtp.example.com"/>
      </smtp>
    </mailSettings>
  </system.net>
</configuration>

<configuration>
  <system.net>
    <mailSettings>
      <smtp deliveryMethod="SpecifiedPickupDirectory">
        <network host="ignored" />
        <specifiedPickupDirectory pickupDirectoryLocation="c:email" />

</smtp>
    </mailSettings>
  </system.net>
</configuration>