Upload and download files using ASP.NET MVC

Uploading and downloading files are common functions you’ll see in most websites and apps. Fortunately, it’s easy to write code to upload and download files using ASP.NET MVC. To start, we need a view and controller pair to upload a file. This is the same HTML and MVC code that you already know. However, there is no need for the model portion of the MVC pattern if you are only uploading files to disk and not working with a database. Otherwise, files can be a property of a model, for example, a profile picture.

The upload view

First, we must start in the view by creatingan HTML <form> element. You can create the form with the Html.BeginForm helper and pass in the following arguments, in the following order (for this particular overload signature):

  1. Action method name : Action method that processes uploaded file
  2. Controller name : Controller that belongs to above action method
  3. FormMethod : Any acceptable HTTP verb
  4. enctype : Appropriate encoding type

Using Helpers is a great way to take advantage of built in features of the ASP.NET MVC framework such as accessing routing information to create a link or using strongly typed objects to render HTML. In the case of the Html.BeginForm helper, we are rendering a <form> element. The Html.BeginForm helper expects an enctype attribute that designates that the form can send binary data as well as textual data in the HTTP POST request. Since the default encoding type is “text-plain” the HTTP Request will not send binary data (that means files!) to the server along with the usual textual form data, so you must set the enctype attribute to multipart/form data or it will not work!

Below is a complete sample of an MVC view containing a form with a file input and submit button:

@using (Html.BeginForm("Upload", "Home", FormMethod.Post,
    new { enctype = "multipart/form-data" } ))
 {
    @Html.AntiForgeryToken()

    <fieldset>
        <legend>Upload a file</legend>
        <div class="editor-field">
            @Html.TextBox("file", "", new { type = "file" })
        </div>
       <div class="editor-field">
            <input type="submit" value="Upload" />
        </div>
    </fieldset>
}

ASP.NET Web Forms has a FileUpload Control, but in ASP.NET MVC our options are either a plain HTML element such as <input type=”file” /> or the TextBox and TextBoxFor Html Helpers (or any helper that outputs a file field). Any Html Helper that outputs an <input type=”file”> tag works. In the example above, the type, id, and name attributes of this tag are all set to “file”. A quick look in the browser using the IE Developer Tools illustrates what the Html.BeginForm and TextBox helpers from the above code sample have rendered:

image_thumb2

When the user clicks the submit button, it causes an HTTP POST submission to /Home/Upload, which maps to the Home Controller’s Upload action method. The Upload action method receives the file and form data and from there you can perform the actual upload and save the file to disk or put in the cloud.

The upload action method

Action methods of MVC Controllers accept incoming HTTP requests for processing. Each HTTP request has a certain way, or method (POST GET PUT DELETE etc..) that it sends data to the server. The receiving action method must expect that type of request in order to process it. Since HTTP GET is the default, you must apply the HttpPost attribute to the Upload action method. This, of course, matches the method=”post” attribute of the HTML <form> element.

You can access uploaded files in the action method by querying the argument that is of type HttpPostedFileBase . The name of this argument, “file” in the below sample, must match the name of its corresponding file input in the HTML form (i.e., <input type=”file” name=”file”>). This allows ASP.NET MVC’s model binding to occur for file uploads. Ensuring the names match is using a concept called Convention over Configuration and leads to more readable code.

[HttpPost]
public ActionResult Upload(HttpPostedFileBase file)
{
    try
    {
        if (file.ContentLength > 0)
        {
            var fileName = Path.GetFileName(file.FileName);
            var path = Path.Combine(Server.MapPath("~/App_Data/Images"), fileName);
            file.SaveAs(path);
        }
        ViewBag.Message = "Upload successful";
        return RedirectToAction("Index");
    }
    catch
    {
        ViewBag.Message = "Upload failed";
        return RedirectToAction("Uploads");
    }
}

If you need to upload multiple files, use IEnumerable<HttpPostedFileBase> instead of a single HttpPostedFile and loop through the collection to access individual files. When completing an upload, be sure that you have the correct permissions to write to the directory you want, then use classes from System.IO to access the file system and save the file.

System.IO.Path.GetFileName retrieves a file name including its extension, and System.IO.Path.Combine combines two or more strings to create a complete path. Because we’re working with an uploaded file from HTTP, we need Server.MapPath to map a virtual path (HTTP) to a physical directory (C:\) . In this case the mapping is from the webroot, i.e., “~/” to the <project root>\App_Data\Images directory. I’m saving files to the App_Data directory to demonstrate concepts, but in real world sites it is unlikely that internet users would have privileges to save files there, so check with your sys admin or Web hoster as to where you should upload and download files

The sample code above also overwrites any existing files, so if that’s an issue you can generate a unique file name by spinning up a Guid and using that as the name, as shown here:

var guid = Guid.NewGuid();

If the file to upload is accompanying form data, the controller action method signature should contain the model type and an HttpPostedFileBase type for the file. For instance, if the file is a user’s profile picture and part of a Person model, the action method signature should look like the following:

public ActionResult Upload( Person Person, HttpPostedFileBase file ) {… }

If you are using Convention over Configuration then model binding will take care of everything and all you do is access the method’s arguments.

In order to download, we need the same MVC components – a view and a controller. We’ll start at the controller.

The Download Action Method

Usually the UI presents a list or grid of links or images in which the user can click to download an image or file. What we’ll use for this example is a simple list of links of images to download. We can do this by creating a List<string> to store the file names in hyperlinks for download. The code below shows obtaining the directory and file information and adding the file names to the list of strings. The method then returns the list of strings as a model to the view.

public FileActionResult Downloads()
{
    var dir = new System.IO.DirectoryInfo(Server.MapPath("~/App_Data/Images/"));
    System.IO.FileInfo[] fileNames = dir.GetFiles("*.*");
    List<string> items = new List<string>();

    foreach (var file in fileNames)
    {
        items.Add(file.Name);
    }

    return View(items);
}  

The view accepts the list of strings and displays them in the page.

The Download View

Notice that the model for this view is a List<string> type instead of a custom object as usual. Of course, this the view consists of a simple for loop that cycles through a list of strings containing the file names and displays them in <label> and <a> tags. The hyperlinks render so that they point to the Home controller’s Download action method, and pass in the name of the file as a URL parameter. Cycling through a list of strings means that you can use array syntax (i.e., @Model[i]) to access each member in the list.

@model List<string>

<h2>Downloads</h2>
<table>
    <tr>
        <th>File Name</th>
        <th>Link</th>
    </tr>
    @for (var i =0; i <= Model.Count -1; i++) {
        <tr>
            <td>
                @Model[i].ToString()
            </td>
            <td>
                @Html.ActionLink("Download", "Download", new  { ImageName=@Model[i].ToString() })
            </td>
        </tr>
    }
</table>

The image below is what the download view produces. The ActionLink Helper renders links that point to the Home controller’s Download action method, passing in the image name as a query string. I’m using the defaults but you might want to consider configuring Routing so that the URL looks friendlier.

image

As users click on the download link, the Download action method returns a FileResult:

 public FileResult Download(string ImageName)
{
   
return File(“<your path>” + ImageName, System.Net.Mime.MediaTypeNames.Application
.Octet);
}

However, you can also return a FileContentResult, FilePathResult, or  FileStreamResult (don’t forget to match the action method’s return type to the type you will use):

FileContentResult : Use this when want to use a byte array to access the file. In this scenario, you might have obtained the file as a byte array from a database call.

return new FileContentResult(byteArray, “image/jpeg”);

FilePathResult  : Returns a file on disk when you must access via a file path. In the FilePathResult you can return a File type or a FileStreamResult.

return new FilePathResult(“~/App_Data/Images/” + ImageName, System.Net.Mime.MediaTypeNames.Application.Octet);

FileStreamResult : Sends a stream out to the response.

return new FileStreamResult(new FileStream(“<your path>”, FileMode.Open), “image/jpeg”);

The various ways to return a file are very similar but allow sufficient customizations to meet the needs of most scenarios. Sometimes the file is from a stream or byte array, or sometimes you only have a simple file path. Media types as well as the System.Net.Mime.MediaTypeNames enum are available so you can designate the file type for download, as the above samples demonstrate.

Summary

Code for uploading and downloading files are mandatory tasks for Web developers at some point in time. We want to allow users to safely upload and download files to go along with other data, and using ASP.NET MVC means you can use Html Helpers as an easy way to provide this functionality.

More on the dev tools:

Profile & Tune Web Pages Using IE Developer Tools

Investigate Web Pages Using IE Developer Tools

More on the Razor view engine:

Introducing ASP.NET MVC development w/the Razor view engine

How data annotations for ASP.NET MVC validation work

Data validation is one of the most important aspects of developing applications for the web. However, validation is also something that can get messy pretty quickly, as developers often stick validation code anywhere and everywhere. However, if you keep a clear separation of concerns by using the MVC pattern and couple that with data annotations in the model, then your validation code becomes much simpler to write, maintain, and test. The added bonus: simple code that’s well written & tested is code that’s just going to work.

What are data annotations?

Data annotations are attribute classes that live in the System.ComponentModel.DataAnnotations namespace that you can use to apply to (decorate) classes or properties to enforce pre-defined validation rules. These annotations are available across various Visual Studio 2010 project types including ASP.NET MVC, Web Forms, ASP.NET Apps & Web Sites, Dynamic Data & even non ASP.NET projects like Silverlight & WPF. The same holds true for the data models; you can use these annotations with POCOs (plain old CLR objects), EF models, Linq2SQL models, etc… The bottom line is that you can use data annotations anywhere.

There are several out of the box data annotations to choose from:

  • Required
  • Regular Expression
  • Range
  • ZipCode
  • DisplayName
  • DisplayFormat
  • Scaffold
  • DataType
  • StringLength
  • A few more…

Although having this set of built in validations is great, it is a limited set. Since every business has lots of rules that don’t neatly fit into this pre-defined set of attributes, what do you do when you need to use your own logic? It’s quite easy, really – just derive from any of the inheritable (non sealed) attribute classes in the System.ComponentModel.DataAnnotations namespace, then code your business rules in the derived class methods.

Between the built-in validators and your own custom validation code, you’re all set with maintainable and clean validation. However, server side data sanitization & validation is also equally important. An upcoming blog post will cover creating custom & server side validation. In the meantime, Brad Wilson from the ASP.NET team has some great blog posts on unobtrusive validation along with a a great series of posts on MVC.

And it all starts in the data model…

Applying data annotations to the model.

Suppose a data entry clerk needs to frequently update baked products with baked and expiration dates, amounts, prices, etc… To accomplish this in code, start with a basic POCO class to represent a product and will serve as the data model to meet the needs of this scenario. You’ll need to do more than just create the class and its members though, and that’s where annotations come into play.

Data annotations serve as a way to enforce these common validation scenarios without having to write much code, and more importantly, without writing repetitive code. Annotations live in one place – the model, rather than a code behind, web page, controller, or view. This helps prevent data validation code from turning into Spaghetti# code[1] scattered about your project.

Take a look at the following Product class, complete with a few basic data annotations:

public class Product 
{
public int Id { get; set; }

[DisplayName("Delicious Treat")]
[Required(ErrorMessage = "The product name field is required.")]
public string Name { get; set; }

[Required(ErrorMessage = "The product description field is required.")]
public string Description { get; set; }

[DisplayName("Sale Price")]
[Required(ErrorMessage = "The Sale Price field is required.")]
public decimal Price { get; set; }

[DisplayName("Freshly Baked on")]
[Required(ErrorMessage = "The Freshly Baked On field is required.")]
public DateTime CreationDate { get; set; }

[DisplayName("Don't Sell After")]
[Required(ErrorMessage = "The Expiration Date field is required.")]
public DateTime ExpirationDate { get; set; }

[DisplayName("Qty Available")]
[Required(ErrorMessage = "The Qty Available field is required.")]
[Range(0,120)]
public int QtyOnHand { get; set; }

[DisplayName("Product Image")]
public string ImageName { get; set; }
}

The above properties are labeled with attributes that clearly state their intentions. The bulk of the validation is simply the Required attribute for this sample, along with a Range attribute on the QtyOnHand property. Some attributes such as the DisplayName attribute don’t necessarily validate but do affect the rendered output. As the above sample demonstrates, any combination of necessary attributes can decorate properties. Notice that all the model and validation code so far live in the same place, and will continue to do so when you create custom attributes and validators; meaning that you’ll continue to have a nice, clean separation of concerns in your app.

Once you’re done applying attributes to the model, you can move on to the controllers and views.

Where do views & controllers fit in?

Views:

Once you’ve setup validation on the model using data annotations, they’re automatically consumed by Html Helpers in views so the helpers can render the proper HTML output. For client side validation to work, you will need to ensure that these two <SCRIPT> tag references are in your view:

<script src="@Url.Content("~/Scripts/jquery.validate.min.js")" type="text/javascript"></script>
<
script src="@Url.Content("~/Scripts/jquery.validate.unobtrusive.min.js")" type="text/javascript"></script
>

Note: If you’re using ASP.NET MVC 3 project templates, these script tags will be added in views automatically for you by selecting the “reference client script libraries” option in the Add View dialog.

The following code from an edit or insert view will make sure the DisplayName, Required, and Range attributes work at run time.

<div class="editor-field">
@Html.EditorFor(model => model.QtyOnHand)
@Html.ValidationMessageFor(model => model.QtyOnHand)
</div
>

Other helper methods such as @Html.TextBox, @Html.TextBoxFor, @Html.Editor, etc… render nearly identical yet very slim output, explained more later in this post. Views play an integral part in validation, yet as the developer you often won’t need to do much in the view other than use the built-in Html Helpers.

Controllers:

Controllers serve as a gateway to accept HTTP POST requests to process incoming data then to match that data with its model and view for rendering. Controllers shouldn’t be a dumping ground for validation code, server side validation code should be called from controller action methods. While you can put validation code directly into the action methods themselves; the practice tends to lead to code that’s less than optimal to maintain, since you’ve started scattering the code about the project. Rather than having code in multiple locations, think about moving server side validation code to a single location near or in the model, or as its own library project.

How validation works.

Both client and server side validation work because of a few conventions in your project that match up data annotations, Html Helpers, rendered output. Html Helpers in views render HTML elements containing attributes that start with the pattern data-val-*. The data-val-* attributes contain error messages, regular expressions, ranges, and other validation information that originates in data annotations.

That means that this decorated code in the model…

[DisplayName("Qty Available")]
[Required(ErrorMessage = "The Qty Available field is required.")]
[Range(0,120)]
public int QtyOnHand { get; set; }

…combined with this code in the view…

<div class="editor-field">
@Html.EditorFor(model => model.QtyOnHand)
@Html.ValidationMessageFor(model => model.QtyOnHand)
</div
>

…turns into this HTML at runtime…

<div class="editor-field">
<input class="text-box single-line"
data-val="true" data-val-number="The field Qty Available must be a number."
data-val-range="The field Qty Available must be between 0 and 120."
data-val-range-max="120" data-val-range-min="0"
data-val-required="The Qty Available field is required."
id="QtyOnHand" name="QtyOnHand" type="text" value="12" />
<span class="field-validation-valid" data-valmsg-for="QtyOnHand" data-valmsg-replace="true"></span
>
</
div
>

The tie-in between the data model annotations and the data-val-* attributes should be clear after reading the above code, but it’s where the client side validation ties in might not be so obvious. Open the \Scripts\jquery.validate.unobtrusive.js file and search for “data-val”. Right away you’ll see that the JavaScript uses the data-val-*, input-* and field-* CSS classes to display/hide validation messages on the client. Although you shouldn’t modify or need to maintain the built-in .js files; it’s worth investigating them to see how things work together in ASP.NET MVC.

function onError(error, inputElement) {  // 'this' is the form element
var container = $(this).find("[data-valmsg-for='" + inputElement[0].name + "']"),
replace = $.parseJSON(container.attr("data-valmsg-replace")) !== false;

container.removeClass("field-validation-valid").addClass("field-validation-error");
error.data("unobtrusiveContainer", container);

if (replace) {
container.empty();
error.removeClass("input-validation-error").appendTo(container);
}
else {
error.hide();
}
}

Having the onError function tied in by only HTML attributes keeps client side validation unobtrusive, or in other words, out of the way of your view code. Annotations combined with unobtrusive validation make both the view and the output are very clean and maintainable. The final result in the browser is fully capable client side validation that falls back to server side validation for browsers without JavaScript enabled. Either way, the same validation happens and the user sees the same error.

image_thumb2

Summary & Code

Data annotations give you a nice way to keep validation and business logic close to the model, and easier to maintain, test and debug. Additionally, cleaner, simpler output leads to faster download speeds and easier integration with client side script libraries like jQuery for UI manipulation.

Although this post focuses on data annotations and client side script, don’t forget that server side validation is very important.

Download the code.

Notes: [1] Spaghetti# is not a real language.

Integrating ASP.NET Web Forms and ASP.NET MVC

With ASP.NET MVC being a mature platform, many Web Forms developers are wondering whether or not they should move to MVC or are thinking about integrating MVC into their existing Web Forms projects. Web Forms has caught up to MVC in many respects. For example, Web Forms V4+ supports routing, and the controls render less HTML than ever before. ViewState went on a diet and is considerably smaller. In the past some have turned to MVC to address these concerns, but no longer is this the case.

If you’re interested in more content about migrating or integrating Web Forms and MVC, see my WintellectNOW video, “Migrating from Web Forms to MVC”. It covers the many concerns developers face when making the decision about whether or not to migrate to a new technology (and whether or not you should at all). In the meantime, below are some practical tips and techniques required when integrating the two technologies.

MVC Integration: Setup, References, and Configuration

You can install the ASP.NET MVC 4 NuGet package that includes all the resources that you need to use MVC such as references, web.config changes, etc… Once you’ve installed the NuGet package there is little you need to do to use MVC except create folders named “Models”, “Views”, and “Controllers” (assuming you are keeping all these in the same project).

image_thumb3

The NuGet Package adds in several changes to the web.config file as well as references to the project that are worth examining. The web.config sample below shows these references:

Location: <configuration><appSettings>

Configure the ASP.NET Web Pages rendering engine settings in the <appSettings> element.

<appSettings>
  <add key=webpages:Version value=2.0.0.0 />
  <add key=webpages:Enabled value=false />
  <add key=PreserveLoginUrl value=true />
  <add key=ClientValidationEnabled value=true />
  <add key=UnobtrusiveJavaScriptEnabled value=true />
</appSettings>

Location: <configuration><system.web>

This code adds various names
paces to the project’s compilation as well as parser filter and base types, which are settings that determine how views render. The namespace references below are the automatic imports to namespaces for use in views only. You must continue use the using keyword in C# code. The general namespace inclusion is in the previous example.

<pages pageParserFilterType=System.Web.Mvc.ViewTypeParserFilter, System.Web.Mvc,
       Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35
       pageBaseType=System.Web.Mvc.ViewPage, System.Web.Mvc,
       Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35
       userControlBaseType=System.Web.Mvc.ViewUserControl, System.Web.Mvc,
       Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35>
  <namespaces>
    <add namespace=System.Web.Optimization />
    <add namespace=System.Web.Helpers />
    <add namespace=System.Web.Mvc />
    <add namespace=System.Web.Mvc.Ajax />
    <add namespace=System.Web.Mvc.Html />
    <add namespace=System.Web.Optimization />
    <add namespace=System.Web.Routing />
    <add namespace=System.Web.WebPages />
    <add namespace=System.Web.WebPages.Html />
  </namespaces>
  <controls>
    <add assembly=Microsoft.AspNet.Web.Optimization.WebForms
     namespace=Microsoft.AspNet.Web.Optimization.WebForms
     tagPrefix=webopt />
  </controls>
</pages>

Location: <configuration><system.webServer><handlers>

These are the ASP.NET runtime HTTP handlers. They are what determines which .dlls service which type of requests at a low level. As demonstrated, these handlers are looking to interact with HTTP via verbs.

<handlers>
  <remove name=ExtensionlessUrlHandler-ISAPI-4.0_32bit />
  <remove name=ExtensionlessUrlHandler-ISAPI-4.0_64bit />
  <remove name=ExtensionlessUrlHandler-Integrated-4.0 />
  <add name=ExtensionlessUrlHandler-ISAPI-4.0_32bit path=*.
       verb=GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS modules=IsapiModule
       scriptProcessor=%windir%\Microsoft.NET\Framework\v4.0.30319\aspnet_isapi.dll
       preCondition=classicMode,runtimeVersionv4.0,bitness32 responseBufferLimit=0 />
  <add name=ExtensionlessUrlHandler-ISAPI-4.0_64bit path=*.
       verb=GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS modules=IsapiModule
       scriptProcessor=%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll
       preCondition=classicMode,runtimeVersionv4.0,bitness64 responseBufferLimit=0 />
  <add name=ExtensionlessUrlHandler-Integrated-4.0 path=*.
       verb=GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS type=System.Web.Handlers.TransferRequestHandler
       preCondition=integratedMode,runtimeVersionv4.0 />
</handlers>

Location: <configuration><runtime><assemblyBinding>

Of course if you’re dealing with differing versions of .NET for any type project, you must change assembly bindings. Assembly bindings declare which versions of which libraries to reference in the project. VS will compile against the new redirected binding than the default when you use the settings below:

<dependentAssembly>
  <assemblyIdentity name=System.Web.Helpers publicKeyToken=31bf3856ad364e35 />
  <bindingRedirect oldVersion=1.0.0.0-2.0.0.0 newVersion=2.0.0.0 />
</dependentAssembly>
<dependentAssembly>
  <assemblyIdentity name=System.Web.Mvc publicKeyToken=31bf3856ad364e35 />
  <bindingRedirect oldVersion=1.0.0.0-4.0.0.0 newVersion=4.0.0.0 />
</dependentAssembly>
<dependentAssembly>
  <assemblyIdentity name=System.Web.WebPages publicKeyToken=31bf3856ad364e35 />
  <bindingRedirect oldVersion=1.0.0.0-2.0.0.0 newVersion=2.0.0.0 />
</dependentAssembly>

After configuring the project to incorporate MVC, you’ll need to setup routing.

Controllers and Routing

Routing is an essential component of MVC development, and MVC cannot work without it. In Web Forms V4 and later, routing is baked right in. What you’ll need to do to ensure the proper routes are set is to create a static RouteConfig class, preferably in a file (e.g., RouteConfig.cs) inside the App_Start special folder. After that, add in the code below to assign a generic route.

routes.MapRoute(
    name: “Default”,
    url: “{controller}/{action}/{id}”,
    defaults: new { controller = “Home”, action = “Index”, id = UrlParameter.Optional }
);

Of course, the RouteConfig class won’t instantiate itself. That means you must call its RegisterRoutes function (also static) from the Global.asax.cs file like so:

void Application_Start(object sender, EventArgs e)
{
    RouteConfig.RegisterRoutes(RouteTable.Routes);
}

The last thing to do is use MVC conventions to create the appropriate folders for Models, Views, and Controllers, if you haven’t already. Otherwise, structure your project as you would for use with the MVC pattern, perhaps moving models to their own class library or service layer.

Considerations when integrating Web Forms and MVC

DataSets/DataReaders & Models:

A lot of data is accessed by Web Forms via declarative tags like the <asp:SqlDataSource>, as well as volumes of DataSets and DataReaders in the code behind files. You’ll need to find a strategy for converting these to models, i.e., classes. Some Web Forms projects contain POCOs for models and those often port over quickly. By convention (assuming a single project), model files live in the <ProjectRoot>\Models folder and model classes in the <Project>.Models namespace.

ASPX & Views:

ASP.NET MVC ships with two view engines: Web Forms (ASPX) and Razor. The ASPX view engine continues on using the classic <%# %> syntax for code delimiters, while Razor uses only the @ symbol (or @{}) as a way to denote the start of of code. Razor uses a new parsing engine first introduced in ASP.NET Web Pages that produces clean and concise HTML output. However, if you have a team strong in Web Forms they may want to continue using Web Forms syntax. The difference worth mentioning is that the ASPX view engine uses the traditional Web Forms rendering under the hood so technically it builds a control tree and renders it. You just can’t access the elements in MVC views like you can in a Web Forms page by referring to a control as an object in the code behind. This makes Razor much faster as there is no tree to render. In  views, code renders inline, or in placeholders, rather than from scripted code in a code behind. This is a drastic enough difference that you’ll probably need to completely rewrite many Web Forms as MVC views, as opposed to simply reusing pages in MVC. Of course, redoing all pages as views all at once is often not an option because of time and budget, but you can move them one by one.

Any would be controls in MVC become Html helpers. Html Helpers are the cornerstone of ASP.NET MVC views. Like controls, the Html Helpers render chunks of browser friendly output, but helpers emit the least amount of code as possible and in the least obtrusive way. Helpers also accept and render data from the model. This means if you have 3rd party controls, you might want to migrate these pages last or weigh the option of leaving them as Web Forms. This, of course, depends upon the cost-benefit of the developer’s time to build a control vs. buying a new version of one, if one is available. Most popular 3rd party vendors are up to date.

Code Behind Files & Controllers:

It is not uncommon to see a Web Forms code behind file with 5,000+ lines of code. That’s a lot of code for one single Page object. It also makes the page object a Swiss army knife of sorts as Page objects deal with building the UI and doing all sorts of other things. Many developers add CRUD operations directly in the code behind. This page of all trades ends up doing all the chores and this means more complex code and code that is tightly coupled.

MVC leans toward a concept called Separation of Concerns in which each part of the MVC pattern maps to a concern. M for models or data and CRUD operations. V for views or UI. C for controllers or operational code. All the layers are nicely separated. If your Web Forms code is getting a bit unruly or spaghetti-like then MVC could address and fix some of your maintenance issues by breaking out components into manageable units, or concerns.

Controllers of course make the calls to Web services to retrieve JSON or XML data or directly to the database, a repository, or any number of options. Controllers also do the work of determining how HTTP requests are handled. This responsibility falls to the code behind in Web Forms.

ASP.NET Core:

Since it’s all ASP.NET, you get to share core features such as sessions, caching, globalization, Forms authentication between Web Forms and MVC.

Summary

Fortunately assets like images, CSS, and custom JavaScript are all reusable between Web Forms and MVC projects. Just keep the ID and NAME attributes the same (which you want anyway for consistency). As you can see, both technologies are ASP.NET so they can live harmoniously and even compliment each other.

As you can see, with just a few modifications to a Web Forms project and you can start adding MVC components. You can run both Web Forms and MVC or work toward doing a complete migration.

Use ViewModels to manage data & organize code in ASP.NET MVC applications

The concept of the ViewModel isn’t just for ASP.NET MVC, as you’ll see references to ViewModels throughout the web in articles and blog posts about the MVC, MVP, and MVVM patterns. Those posts and articles can center around any number of technologies such as ASP.NET, Silverlight, WPF, or MVC… This post will investigate ViewModels as they apply to the world of ASP.NET MVC.

What is an ASP.NET MVC ViewModel?

In ASP.NET MVC, ViewModels allow you to shape multiple entities from one or more data models or sources into a single object, optimized for consumption and rendering by the view. The below image illustrates the concept of a ViewModel:

 

image_16

The purpose of a ViewModel is for the view to have a single object to render, alleviating the need for UI logic code in the view that would otherwise be necessary. This means the only responsibility, or concern, of the view is to render that single ViewModel object, aiding in a cleaner separation of concerns (SoC). Concerns are distinct aspects of the application that have a particular purpose (i.e., concern), and keeping these aspects apart means your application is more organized, and the code more focused. Putting data manipulation code in its own location away from the view and controller, enforces SoC.

Using ViewModels in MVC for finer granularity and better SoC leads to more easily maintainable and testable code. Remember, unit testing is about testing small units.

Along with better coding practices, there are many business reasons demonstrating why you might consider using ViewModels:

  • Incorporating dropdown lists of lookup data into a related entity
  • Master-detail records view
  • Pagination: combining actual data and paging information
  • Components like a shopping cart or user profile widget
  • Dashboards, with multiple sources of disparate data
  • Reports, often with aggregate data

The above scenarios are common to a wide variety of applications, and deal with more complex data than basic CRUD forms-over-data page (e.g., a simple 1:1 mapping to the db table). For example, providing a list of states, and ensuring that the state that matches the state of current customer, means that you need to either provide two sets of data or a single set of customer/state data combined, as shown in the image below.

 

image_6

Some scenarios such as a lookup table representing states in the USA, could easily work with either ViewModels or a ViewBag/ViewData object, so there is some potential overlap at times. It’s up to the application architects and developers to decide what works best with their exact use case.

Creating a ViewModel

Although a ViewModel consists of multiple entities, at its core a ViewModel is still just a class – and one that doesn’t even inherit from anything special, as many MVC classes do.

Physically, ViewModels can exist in different locations, listed below:

  • In a folder called ViewModels that resides in the root of the project. (small apps)
  • As a .dll referenced from the MVC project (any size app)
  • In a separate project(s) as a service layer, for large applications that generate view/content specific data. (enterprise apps)

Since a ViewModel is just a class, the easiest way to get started using one is to create a new folder named ViewModels and add a new code file to it.

To create the CustomerViewModel ViewModel, add the Customer and StatesDictionary types as properties to form one CustomerViewModel class. In the example below, the CustomerViewModel class contains the newly defined properties.

public class CustomerViewModel 

{

    public Customer Customer { get; set; }

    public StatesDictionary States { get; set; }

    public CustomerViewModel(Customer customer)

    {

        Customer = customer;

        States = new StatesDictionary();

    }

}

Generally, ViewModels contain the word “ViewModel” as part of its name; however, the conventions at work here are for consistency in code readability, since other classes in MVC state their intents in their names as well (e.g., names of controllers, action methods, etc…use conventions in their names).

The StatesDictionary class is a simple Dictionary object containing two type parameters of type string. The class also contains the definitions for all the members in the Dictionary (i.e., the state data). The only property in the StatesDictionary class is the StateSelectList, which is an object that Html Helpers use with to render an HTML <select> element that displays a listing of states. The type Dictionary<string, string> in the StateSelectList property maps to the state abbreviation then state name, respectively.

public class StatesDictionary

{

    public static SelectList StateSelectList

    {

        get { return new SelectList(StateDictionary, "Value", "Key"); }

    } 

    public static readonly IDictionary<string, string> 

        StateDictionary = new Dictionary<string, string> { 

      {"Choose...",""}

    , { "Alabama", "AL" }

    , { "Alaska", "AK" }

    , { "Arizona", "AZ" }

    , { "Arkansas", "AR" }

    , { "California", "CA" }

    // code continues to add states...

    }; 

}

Data that lives in small lists and infrequently changes, like the StatesDictionary class, exists in all types of applications. In real world applications, you’ll find a variety of methods for dealing with lookup data such as a list of states – often XML files and SQL tables. You can replace the code in the StateDictionary method to use entities from Entity Framework, read data from files, or any data access code that you require.

After creating the ViewModel, the next steps are to instantiate it in a controller and return it to the view.

Getting the ViewModel to the view

Starts with the controller…

Sending a ViewModel to the view for rendering will work the same as when dealing with a model. Since it’s just a class, the view doesn’t know, and doesn’t care, where the model or ViewModel came from. You can create the instance of the ViewModel class in the controller, or resolve it if using an IoC container. Remember that just as you would do with views, you should keep controllers clean of unnecessary code, meaning that only code that fetches the model or ViewModel belongs here, and little more.

public ActionResult Edit(int id)

{

    Customer customer = context.Customers.Single(x => x.Id == id);

    var customerViewModel = new CustomerViewModel(customer);

    return View(customerViewModel);

}

Then the view renders the ViewModel…

In order for the view to know what object to use, set the @model keyword to point to the ViewModel, just like you already would with a regular model.

@model FourthCoffee.Web.ViewModels.CustomerViewModel

Because the Customer object is a property of the ViewModel, you’ll see the model.Class.Property syntax to access the ViewModel data, similar to the following line of code.

<div class="editor-label">

    @Html.LabelFor(model => model.Customer.FirstName)

</div>

<div class="editor-field">

    @Html.EditorFor(model => model.Customer.FirstName)

    @Html.ValidationMessageFor(model => model.Customer.FirstName)

</div>

@* ...View code continues rendering properties... *@

Additionally, you can edit the Edit/Create views so that the DropDownList containing a list of the states will display, and display the correct state matching that of the customer.

<div class="editor-field">    

    @Html.DropDownList("state", new SelectList(StatesDictionary.StateSelectList, 

                       "Value", "Text", Model.Customer == null ? "" : Model.Customer.State))

    @Html.ValidationMessageFor(model => model.Customer.State)

</div>

As you might have noticed, using a ViewModel is just as easy as using the ViewBag or ViewData objects. ViewModels, however, provide those extra benefits like being easier to test and optimize.

Checking the results

After a user navigates to the /Customers/Edit/1 URL in the browser, the Razor view engine renders the CustomerViewModel similarly to the following screen shot.

image_4

The State DropDownList displays the states and the current state for that customer, as expected.

Digging Further into ViewModels

Because ViewModels render pre-manipulated data that no longer have those 1:1 mappings between model classes and database tables, you’ll need to do create mappings yourself. You can manually map small ViewModels, but this will quickly become burdensome when mapping larger classes, especially when working with parent-child-grandchild, multi-level, or complex data. This is where a tool such as AutoMapper comes into play. AutoMapper will let you fluently setup mappings between ViewModels and models more easily than doing so manually, or writing your own mapper.

Here are some tips for using ViewModels:

  • Put only data that you’ll render in the ViewModel.
  • The view should direct the properties of the ViewModel, this way it fits better for rendering and maintenance.
  • Use a mapper when ViewModels become complex.

Some tools that can help assist you in generating POCOs (Plain Old CLR Objects) for models and ViewModels are:

POCO Generator

EF POCO Templates

In addition to these tools, you can use MvcScaffolding to create actions and views based on ViewModels. MvcScaffolding, invention of ASP.NET team member Steve Sanderson, gives you more power in creating CRUD, repository, unit test and other templates quickly and painlessly. Check out Steve’s Multi-part series on MvcScaffolding here. MvcScaffolding works with ViewModels as well as models.

You should always prefer using a ViewModel rather than instantiating multiple models and putting that manipulation code in the controller.

Summary

ViewModels help you organize and manage data in MVC applications when you need to work with more complex data than the other objects allow. Using ViewModels gives you the flexibility to use data as you see fit. ViewModels area generally a more flexible way to access multiple data sources than models + ViewBag/ViewData objects.

Further reading: Comparing the MVC and MVVM patterns along with their respective ViewModels

Download the code!

Partial views in ASP.NET MVC

What is a partial view and when should I use it?

As developers become familiar with the ASP.NET MVC model, they’ll naturally want to create reusable components filled with content & code. In Web Forms, we could do this by creating a web user control or a web server control, but in MVC, we will use partial views. You’ll notice that conceptually, all of the scenarios below would work for either technology.

  • A stock ticker that’s displayed on each page in an application.
  • A calendar widget that’s displayed on multiple pages in application.
  • A login box.
  • A social networking component used on multiple pages, such as a Facebook Like button.

While ASP.NET MVC partial views may behave similarly in theory to web user controls, syntactically and functionally, the two behave differently. Web user controls found in web forms uses ViewState, PostBacks, and Events while MVC partial views do not use any of the preceding techniques for managing state. Just as ASP.NET web user controls do, partial views can tap into the models contained in your application as well as share data between other application components.

Rendering partial views

Partial views in ASP.NET MVC 3 allow the developer to create reusable content with the very precise and clean Razor syntax (or ASPX). The syntax that renders the partial view is implemented as an Html helper. The Html.Partial helper renders the partial view named “_FeaturedProduct” inline. The first argument of all overloaded methods in the call the @Html.Partial expect the view/partial’s file name, without the file extension. Adhering to convention, the @Html.Partial helper assumes the view resides in the \Views\Shared\ folder. Additional overloads in the @Html.Partial method allow you to pass ViewData/ViewBag objects between views/partials (see below under Sharing data…).

The code below demonstrates the call to render the featured product partial view.

<div>
  @Html.Partial("_FeaturedProduct")
</div
>

Partial views can be rendered inside a Layout Page (or if using MVC 2/3 w/ASPX, the Master Page) as well as regular views.

There are some cases where you might like to step aside and write directly to the HTTP Response stream rather than having a partial view render the results (partials/views use MvcHtmlString/StringWriter). To do so, use the Html.RenderPartial helper.

<div>
  @Html.RenderPartial(“_FeaturedProduct”)
</div
>

Use Html.RenderPartial for streaming images or other elements that are media-centric or where faster download times are highly important.

Creating a partial view

Both partial views and regular views are .cshtml files, with the difference being the folder where the partial views reside: \Views\Shared\. Use the Add New View dialog by accessing the context menu from the \Views\Shared node in Solution Explorer. The Add New View template dialog offers choices for creating your partial views, including the option for strongly typing views. Don’t forget to check off  “Create as a partial view” or you’ll end up with a lot of code to delete.

SNAGHTML44dfac8

Once you’ve created the view you can get started customizing it by simply editing the file. There’s no problem in deleting or modifying the view’s code, as there’s no designer tied to it. The code shown below (_FeaturedProduct.cshtml) is the same code the default view template creates, but modified to display the featured product differently:

<style type=“text/css”>
    .featuredProduct {border: solid 1px #000}
</style
>
<
div>
    <div>
        <h2>
            Our Featured product:<br />
            @ViewBag.FeaturedProduct.Name
        </h2>
    </div>    <div>
        <h3>
            Now discounted to $@String.Format(“{0:F}”, ((decimal)ViewBag.FeaturedProduct.Price)-100)
        </h3>
    </div>  
    <div>
        @Html.ActionLink(“Featured Product Details”, “Details”, new { id = ViewBag.FeaturedProduct.ProductId })
    </div> 
    <div>
        <img class=“featuredProduct” src=@Href(“~/Content/Images”)/@ViewBag.FeaturedProduct.ImageName” alt=Featured Product”/>
    </div
>
</
div
>

As with strongly typed views, strongly typed partial views also support dot notation syntax and access to the model, ViewBag, ViewData and other classes specifically designed for sharing data.

It should be clear when reading through the above code that the syntax of partial view looks the same as a regular view. The important take-away is not about the syntax but how the partial view is used. However, a syntactic benefit to developers is the consistency between both partial and full views, particularly when we need to share data between them.

Sharing Data between views and partial views

It’s a common occurrence to pass data between components of an application, and in this case those components are MVC partials, views & controllers. As previously noted, you should use the ViewBag or ViewData classes to share data across views and controllers. First, a few notes on ViewBag and ViewData:

  • ViewData was available in previous versions; ViewBag was released with MVC 3.
  • ViewData can contain any type of data in a name-value pair format. I.e., ViewData[“Message”] = “Welcome”;
  • ViewBag objects are just wrappers around ViewData objects, and allow developers to code to them using strongly typed syntax.
  • ViewBag objects can be extended by simply setting properties in a more fluent syntax. I.e.,  ViewBag.Customer = new Customer(1,”Smith”);

If code in a controller uses either the ViewBag or ViewData classes, those classes will be available throughout the view’s lifecycle, and that includes its partial views.

The preferable object is the ViewBag. Because of its more fluent and dynamic syntax, there’s more complex objects that can be shared quite easily between components. The sample below demonstrates setting up the ViewBag object in the controller so it will be available to all necessary components:

ProductModel productModel = new ProductModel();        
public ActionResult Index()
{
    ViewBag.FeaturedProduct = new FeaturedProduct(105, "The Most Awesome Bike Ever!", 1000.00M, "bike4.png");          
    return View(productModel.Products);           
}

The ViewBag is accessed inside the view or partial using the follows syntax:

@ViewBag.FeaturedProduct.Name

Summary

Partial views are a great way to reuse fragments of HTML and Razor syntax together, with the ability to easily share data.

Resources:

Introducing Razor

Introducing MVC Development w/the Razor View Engine

Razor View Syntax

When to use ViewBag, ViewData, or TempData in ASP.NET MVC 3 applications

“When should I use a ViewBag vs. ViewData vs. TempData objects?” — a frequent question in online forums, during presentations, and at events. There are enough similarities and differences between these objects that warrant a closer look to see exactly how you can use each of these objects while developing MVC applications.

All three objects are available as properties of both the view and controller. As a rule of thumb, you’ll use the ViewData, ViewBag, and TempData objects for the purposes of transporting small amounts of data from and to specific locations (e.g., controller to view or between views). Both the ViewData and ViewBag objects work well in the following scenarios:

  • Incorporating dropdown lists of lookup data into an entity
  • Components like a shopping cart
  • Widgets like a user profile widget
  • Small amounts of aggregate data

While the TempData object works well in one basic scenario:

  • Passing data between the current and next HTTP requests

If you need to work with larger amounts of data, reporting data, create dashboards, or work with multiple disparate sources of data, you can use the more heavy duty ViewModel object. See my detailed blog post on ViewModels for more details on working with ViewModels.

ViewData & ViewBag objects

  • ViewData
    • ViewData is a dictionary object that you put data into, which then becomes available to the view. ViewData is a derivative of the ViewDataDictionary class, so you can access by the familiar “key/value” syntax.
  • ViewBag
    • The ViewBag object is a wrapper around the ViewData object that allows you to create dynamic properties for the ViewBag.

Both the ViewData and ViewBag objects are great for accessing extra data (i.e., outside the data model), between the controller and view. Since views already expect a specific object as their model, this type of data access to extra data, MVC implements it as a property of both views and controllers, making usage and access to these objects easy. 

The syntax and usage of the ViewBag, ViewData, and TempData objects are outlined in the following code sample, which populates a featured product object that a view renders as in a bakery’s home page:

public class HomeController : Controller

{

    // ViewBag & ViewData sample

    public ActionResult Index()

    {

        var featuredProduct = new Product

        {

            Name = "Special Cupcake Assortment!",

            Description = "Delectable vanilla and chocolate cupcakes",

            CreationDate = DateTime.Today,

            ExpirationDate = DateTime.Today.AddDays(7),

            ImageName = "cupcakes.jpg",

            Price = 5.99M,

            QtyOnHand = 12

        };

    

        ViewData["FeaturedProduct"] = featuredProduct;

        ViewBag.Product = featuredProduct;

        TempData["FeaturedProduct"] = featuredProduct;  

    

        return View();

    }

}

The Index.cshtml view renders the Product object by accessing the code with the same syntax as in the controller. Notice that you’ll have to cast the ViewData and TempData objects, but not the ViewBag.

@using FourthCoffee.Models;

@{    

    ViewBag.Title = "Home Page";

    var viewDataProduct = ViewData["FeaturedProduct"] as Product;

    var tempDataProduct = TempData["FeaturedProduct"] as Product;                

}

<h2>Welcome to Fourth Coffee Bakery</h2>

<div>

    <a href="/Products">

    <img src='@Url.Content("\\Content\\Images\\cake.jpg")' alt="Fourth Coffee Bakery"/>    

    </a>

    <div>

        Today's Featured Product is!

        <br />

        <h
4>@ViewBag.FeaturedProduct.Name</h4>

        <h3>@viewDataProduct.Name</h3>

        <h2>@tempDataProduct.Name</h2>

    </div>

    @Html.ActionLink("Test Tempdata","Featured")

</div>

The ViewBag object lets you add dynamic properties to it which makes it a very versatile tool.

Although all three display something when this view renders, but the TempData can be troublesome when used in this manner, and here’s why…

TempData

TempData is meant to be a very short-lived instance, and you should only use it during the current and the subsequent requests only! Since TempData works this way, you need to know for sure what the next request will be, and redirecting to another view is the only time you can guarantee this. Therefore, the only scenario where using TempData will reliably work is when you are redirecting. This is because a redirect kills the current request (and sends HTTP status code 302 Object Moved to the client), then creates a new request on the server to serve the redirected view. Looking back at the previous HomeController code sample means that the TempData object could yield results differently than expected because the next request origin can’t be guaranteed. For example, the next request can originate from a completely different machine and browser instance.

As described below, the syntax for using TempData is the same as ViewData.

// TempData sample

public ActionResult Featured()

{

    var featuredProduct = new Product

    {

        Name = "Assorted Cupcakes",

        Description = "Delectable vanilla and chocolate cupcakes",

        CreationDate = DateTime.Today,

        ExpirationDate = DateTime.Today.AddDays(7),

        ImageName = "cupcakes.jpg",

        Price = 5.99M,

        QtyOnHand = 12

    };

 

    ViewData["FeaturedProduct"] = featuredProduct;

    ViewBag.Product = featuredProduct;

    TempData["FeaturedProduct"] = featuredProduct;

 

    //After the redirect, the ViewBag & ViewData objects are no longer available

    //Only TempData survives a redirect

 

    return new RedirectResult(@"~\Featured\");

}

However, once the controller redirects, the ViewBag and ViewData will contain null values. If you inspect the TempData object with debugging tools after the redirect you’ll see that it is fully populated with a featured product. This is because the redirect is that only, subsequent, request, so only it can access the TempData object without worry.

@using FourthCoffee.Models;

@model FourthCoffee.Models.Product

@{

    ViewBag.Title = "Details";

    var featuredProduct = TempData["FeaturedProduct"] as Product;

}

The customary Session object is the backing store for the TempData object, and it is destroyed more quickly than a regular session, i.e., immediately after the subsequent request. Because of its short lived scope, it’s great for passing error messages to an error page.

Greg shackles has a very comprehensive blog post that covers just about everything you need to know about TempData.

Now that you’ve seen how and when to use ViewData, ViewBag, and TempData objects, you might be wondering what to do when using larger sets of data or more complex scenarios. Fortunately, MVC has ways to deal with these commonly needed scenarios.

Thinking outside the ViewBag

Your requirements might need you to represent the following types of data, which do not fit in well when using ViewBag, ViewData, or TempData objects. The MVC 3 framework contains ViewModel objects for when you need more than ViewData. The type of data that suits ViewModels well is as follows:

  • Master-detail data
  • Larger sets of data
  • Complex relational data
  • Reporting and aggregate data
  • Dashboards
  • Data from disparate sources

You’ll likely run into these or similar scenarios during the app development process.

Summary

The ViewData and ViewBag objects give you ways to access those extra pieces of data that go alongside your model, however for more complex data, you can move up to the ViewModel. TempData, on the other hand, is geared specifically for working with data on HTTP redirects, so remember to be cautious when using TempData.

Introducing MVC Development w/the Razor View Engine for Visual Studio Developers

The Razor View Engine is a precise, useful, light language that enables you to create views for MVC projects in ASP.NET still while keeping a separation of concerns, ability to test, and pattern based development.  ASP.NET MVC developers looking for a more concise syntax now have another option that’s built-in (of course, there are many 3rd party view engines out there) with the language being a familiar light version of C#.

The Razor View engine is used to create WebMatrix sites or Visual Studio MVC applications.  When using ASP.NET MVC with either engine, you’ll stick to a style of development called “convention over configuration”, meaning that you’ll use certain naming conventions to name files, models, views, controllers, and other key application elements rather than storing lots of metadata about these same elements in a configuration file.  When using MVC in Visual Studio 2010, it’s is setup so that you’ll be guided to use convention over configuration, which becomes evident when exploring an ASP.NET MVC project.

Getting Started

Before you start, go and download these two things (as of this post; things are subject to change – these could end up in VS at some point):

You can also find the Razor Syntax Highlighter by choosing Extensions Manager from the Visual Studio Tools menu.  Once installed, MVC 3 project templates are available from Visual Studio.  The MVC 3 Web Application template allows you to use either the Web Forms View Engine or the Razor View Engine, while MVC 2 Applications contain only the WF View Engine.

image_2

When creating a new MVC 3 project a new dialog box appears asking which application type, view engine, and testing framework you’d like to use.  You can and should add a test project so you can test your code, then actually write some tests in it.   The image below demonstrates selecting the internet application project template using Razor as the view engine, as well as the test framework.  The internet application MVC template adds in ASP.NET membership & security features to the project by creating the necessary model, view and controller for logging on and registering as a site user.

image_6

Verify that the project is created with three folders, one each for Models, Views, and Controllers which is the same folder structure as a MVC 2 site.  The project also contains auxiliary folders and files needed for the application such as the Content & App_Data folders.   Since this is an MVC application using the Razor View Engine, you will see a different file extension – .cshtml.  The .cshtml files are Razor View Pages written using the Razor View Engine.  If you’re not familiar with Razor syntax, I’ve blogged about it here, and the online documentation has more information as well.

image_11

The application template sets up some models, views and controllers to start with, and is now ready for new models, views, and controllers.  I’ve found the easiest way to work with MVC in VS is to start with the model, move to the controller, then create the view, so we’ll look at models first.

Models

A model is a representation of an underlying data store.  Models can be almost anything from any data source; EF or Linq2Sql Models, or a simple class.  The code the builds the model below consists of two classes, a ProductModel class and a Product class.  The ProductModel class returns a List<t> of Product objects in a property aptly named Products that represents one or more products in the data store .  Product objects contain ProductNumber, Name and Price properties and represent an individual product in the data store.  The model code representing these product objects is below:

using System.Collections.Generic;
namespace AdventureWorks.Models
{
    public class ProductModel
    {
        public List<Product> Products { get; set; }
        public ProductModel()
        {
            Products = new List<Product>();
            this.Products.Add(new Product("AB-00-J1" ,"Super Fast Bike" ,1000M));
            this.Products.Add(new Product("EE-9-OL"  ,"Durable Helmet"  ,123.45M));
            this.Products.Add(new  Product("MMM99-54" ,"Soft Bike Seat"  ,34.99M));
        }
    }

    public class Product
    {
        public Product(string productNumber, string name, decimal price)
        {
            Name = name;
            Price = price;       
            ProductNumber=productNumber;
        }
        public string ProductNumber { get; set; }
        public string Name { get; set; }
        public decimal Price { get; set; }
       
    }
}

Models are handed over to views by controllers so the views can render the data from the model.  The model will extend business logic (of course, this is a simple example, business logic will likely be spread out into other applications & tiers). Models also provide validation information to the view via metadata & code.  You can add the model to the \Models folder or you can reference an external data model library.  In this case, the model’s been added to the \Models folder.

Controllers

Controllers are objects that inherit from the System.Web.Mvc.Controller class that match models with views.  During incoming requests, MVC’s routing system kicks in and determines which controller method to use based on routing code set in the global.asax.cs file.  A default route is set in the global.asax.cs file that works for most of the routes you’ll need, however, if need be then you can modify/add/delete your own routes.

Staying within convention, controller code files should go in the \Controllers folder. The controller class must follow the naming convention of YourNameController, i.e., ProductsController.  The controller’s Index method, again following convention, must be named the same name as its view but without the file extension.  By following this pattern, the controller can have multiple actions that deliver data to multiple views, making code easier to write, maintain, and test.

namespace AdventureWorks.Controllers
{
    public class ProductsController : Controller
    {
        public ActionResult Index()
        {
            ProductModel p = new ProductModel();           
            return View(p.Products);
        }
    }
}

By observing the previous code sample and the conventions that it follows, it’s clear that the Index method maps to the \Views\Products\Index.cshtml view.  The Index() method’s return type is an ActionResult from the System.Web.Mvc namespace.  There’s many different results that you can use for different scenarios such as ContentResult, FileResult, RedirectResult, ViewResult and others depending on your view’s needs

Views

Views are a mechanism to format and render data in a browser from the model, as specified by the @model attribute (or @inherits) at the top of the view.  Views in ASP.NET MVC with either the ASPX or Razor View engines use a code-based way to render the page rather than relying on declarative controls, which create tight coupling and are hard to test.  Using the MVC approach creates cleaner output in the browser as well as cleaner and more terse syntax in the views as well.  Views are meant to only render the markup, code and data; they’re not meant as a place to store business logic. The model and tiers accessed by the model, are the appropriate places to host business logic.  The view can have a small amount of UI validation logic,as a first line of defense for input sanitation, e.g., required, regex and range validators.

To add a view to your project, right click on the controller and select Add View.

image_4

Visual Studio will need some information about the view, which is supplied in the Add View dialog box:

  1. Specify whether you want a strongly-typed view or not.  Creating a strongly-typed view allows you to refer to the underlying data structures in the classic object.property syntax.
  2. Specify the view data class.  The dropdown list displays classes in your project that are part of the data model.
  3. Specify the view engine.  ASPX and Razor are the options.
  4. Specify the view content.  Choices are list, details, edit. etc…  Choosing this option creates .cshtml or .aspx view pages that do page rendering for you.

image_12

Here’s what choosing these options will produce in a Razor view page named \Views\Products\Index.cshtml:

@model List<AdventureWorks.Models.Product>
@{

View.Title = "Index";
Layout =
"~/Views/Shared/_Layout.cshtml"
;
}


<h2>Index</h2>
<
p>
@Html.ActionLink("Create New", "Create")
</p
>
<
table>
<tr>
<th>Edit/Details/Del</th>
<th>Product Number</th>
<th>Name</th>
<th>Price</th>
</tr>

@foreach (var item in
Model) {
<tr>
<td>
@Html.ActionLink("Edit", "Edit", new { /* id=item.PrimaryKey */ }) |
@Html.ActionLink("Details", "Details", new { /* id=item.PrimaryKey */ }) |
@Html.ActionLink("Delete", "Delete", new { /* id=item.PrimaryKey */ })
</td>
<td>
@item.ProductNumber
</td>
<td>
@item.Name
</td>
<td>
@String.Format("{0:F}", item.Price)
</td>
</tr>
}
</table>

Since the view is strongly typed, the data structure can be accessed as it is – an object with properties.  The code above loops through the model and renders a <TR> for each entity that the model holds along with <TD> tags and the actual data in them (ProductNumber, name and Price).  The result is a simple list of the three products in model with accompanying action links.

image_14

The HTML source shows a clean, precise table rendered to the browser.

image_8

Summary

Rendering a list of products is very easy using MVC and the Razor View Engine, as is updating/manipulating the data (logically what you’d do next if following this example).   If you’re digging deeper into learning MVC w/Razor the next topics you’ll want to get into are jQuery and HTML validation helpers for client side validation, and decorating the model with data annotations (also for validation).  The MVC web site has a ton of great examples and tutorials.

Although many ASP.NET MVC samples use the ASPX/Web Forms view engine they’re easily compared & converted to razor pages – so don’t avoid them, it’s still a great way to learn both MVC w/Razor and the ASPX engine.

Getting Familiar with Razor Language Syntax, Features and Rules

All languages have syntax rules, and ASP.NET Web Pages with Razor is no different.  The syntax is meant to be light and concise and simple, yet powerful enough to allow you to move to ASP.NET development using Visual Studio easily . Having said that, let’s take a look at a few key features of the language and some of the simple ways to write Razor code.

What exactly IS Razor and WebMatrix?

If you need the introduction on WebMatrix & Razor, no worries, I’ve already written a post on why, who and when WebMatrix & Razor are good choices and what they are intended for here.  Otherwise, continue on…

Basic Principles (Code/Script Blocks)

The @ character designates inline code, which is code that’s right inside of HTML  while the @{ with and ending } designates multiple lines of code.  Inline code can be anywhere – mixed inline with HTML, as HTML attribute values or page content. It can be multiple lines of code (a code block) as well when more functionality is needed.  Here’s a single inline statement sample with the actual code highlighted:

<li class=”price”>$@string.Format(“{0:f}”, p.Price)</li>

And here’s a what a block of code looks like:

@{

    LayoutPage = “~/_Layout.cshtml”;

    PageData[“Title”] = “Home”;

}

 

Each executable statement ends with a semicolon (;).Whitespace is ignored, but case is not.

Literal strings (or literal text) are put in double quotations (“), while numbers, if used mathematically, use none.

Comments

A Razor single line comment marker: @//

A Razor multi-line comment marker: @/* and */

Variables & Data Types

Use the var keyword to declare variables, or use the classic typed syntax.  The new operator is also supported.

var db = Database.Open(“bakery”);

string name = “Stephen”

int rating = 5;

var grid = new WebGrid(data, defaultSort: “Na
me”, rowsPerPage: 5);

Razor supports all the standard .NET framework simple data types and allows developers to take advantage of consuming objects and collections, using the classic dot notation, as shown below:

Mail.SmtpServer = “smtp.live.com”;

Mail.SmtpPort = 25;

Mail.EnableSsl = true;

Mail.Send(to: customerEmail, subject: “New Order”, body: body);

Paths

Use the ~ operator to get to the virtual root of the web site.  The virtual root is top level folder of your site, installed to here by default:

C:\Users\<YourUserName>\Documents\My Web Sites\Bakery

Where <YourUserName> is your Windows login name.  The Server.MapPath() method is also available, to help you when you need to convert physical paths to virtual paths for use on a web server.

Code constructs

Razor supports conditions and loops, so you can make decisions in your code.  You can use if blocks & switch blocks, for & foreach loops and while loops too.  Despite being a language that uses curly brace and is case sensitive, it’s very easy to read and write from a syntactic angle, as demonstrated here with a foreach loop, if statement and using the Mail object:

@foreach (var p in db.Query(“SELECT * FROM PRODUCTS”)) { … }

–and–

if (Mail.UserName.IsEmpty() || Mail.Password.IsEmpty() || Mail.From.IsEmpty()) {

        <h2>Please set up Mail!</h2><p>Please set your Hotmail Username, Password, and From Address in OrderSuccess.cshtml to send mail</p>

}

else {

    Mail.Send(to: customerEmail, subject: “New Order”, body: body);

    <h2>Thank you for ordering!</h2>

} 

Some other notable code constructs available in Razor are Try/Catch exception handling and arrays.  I just wanted to highlight a few of the popular ones here in this blog post. You can get a lot more information on the language features in the ASP.NET Web Pages with Razor Syntax eBook.

Helpers

Razor helpers allow you to encapsulate and condense complex tasks into a single line of code.  Some baked in helpers are used for …

  • Google Analytics
  • Facebook Integration
  • Twitter Integration
  • Sending Email
  • Validation
  • There’s lots more…

You can also create your own helpers, and there’ll be more helpers brought to you by Microsoft in the future.  Helpers are a big part of the Razor API.

The Razor API

This is where’s it at, in the API.  APIs (Application Programming Interfaces) contain functionality that you can tap into and use, rather than having to build it yourself.  The Razor API includes an extensive of helpers and activities like file uploading, data collection w/HTML Forms, charting, sending email, website analytics, etc…are all in the Razor API, and most only take a single or few lines of code to use.

You can browse the online API documentation here.

There’s More!

Of course, there’s a lot more you can do with Razor syntax; listed in this post are just some of the basics and features that you can take advantage of when building small, highly functional, easy to use web sites.

Add HTML5 Geolocation plus Bing Maps into ASP.NET MVC views

The Bing Maps API is a free, easy to use API, that allows you to incorporate mapping features into your ASP.NET MVC or application by using Web standards such as JavaScript, and the now supported HTML5 Geolocation.

Bing Maps and ASP.NET MVC

A Bing maps API key is required when using the API. The Bing Maps key allows you to access Geolocation data, and to manipulate an in-view Map object with JavaScript via the Bing Maps API. The Bing Maps Developer Portal is where you can get a key by registering with your Windows Live ID.

Once you’re set with a key, you’ll need these files in your MVC project to develop with Bing Maps:

\Scripts\YourBingMapsScript.js – This file contains your script that works with Bing Maps & Geolocation.

\Content\Site.css – A small bit of CSS is required to style the Map

\Views\BingMaps\Index.cshtml – The MVC view that contains the Bing Map HTML

Since the code is HTML &CSS that conform to Web standards, the bulk of the lives is in the .js file and/or the view. Although using MVC, the model and controller are not necessary for manipulating maps with client side script, but don’t throw out the model and controller yet, as you will need them to work with other data.

The Bing Maps Interactive SDK

If you’re writing code that uses Bing Maps, the Interactive Bing Maps SDK is a “must visit” Web site. By choosing the options on the left of the page, the Bing Maps Interactive SDK creates usable JavaScript, and a “View HTML ” button that exposes the page source.

 

image_2

The Bing Maps API & SDK contain more than an interactive website. Bing Maps development gives you access to many productive development tools such as:

  • The Bing Maps AJAX Control (multiple versions)
  • The Bing Maps iOS Control
  • A Bing Maps Silverlight Control
  • SOAP and REST services
  • More…

You can use the Bing Maps Interactive API to create the equivalent code as the samples shown in this post.

Render Bing Maps in MVC views with the Bing Maps AJAX control.

While it’s called the Bing Maps AJAX control, it’s not a control at all, but a JavaScript library instead. HTML and client side script (JavaScript, jQuery, etc…) are the enabling technologies for Bing Maps on the ASP.NET (or any Web) platform. To reference the Bing Maps AJAX Control, your view needs the <script> reference below.

<script src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0" type="text/javascript"></script>

If you plan to use the Bing Maps AJAX control in multiple views, the <script> reference can go in the _Layout.cshtml file, otherwise you can add it to the required views or a different layout page. Inside a view, a <div> element should contain and display the map, and is also the DOM object that you manipulate in code, so it needs an id attribute.

<div id="map"></div>
Since the browser renders a tiny <div> by default, some CSS is necessary, such as the position, width, and height, in which to create a suitable DOM shape for maps. You can save the CSS in the \Content\Site.css file, or its own file, for reusability across views.  
<style>
#map
{
    position:relative; 
    width: 500px; 
    height: 500px; 
    border:0px
}
</style>

After the HTML is in place, you can write code to capture the user's positional data to display a Bing map showing the location, nearby restaurants, or other information requested by the user. 

Display a Bing Map with a Pushpin.

You first need positional data from the user before displaying the map. Once you have the positional data points, i.e., latitude and longitude, you can add a Bing Map to any MVC view. To learn how to obtain positional data for your Web site or app, see this post on creating location aware Web sites with the HTML5 Geolocation.

The code below retrieves the latitude and longitude coordinates from the position argument of a showMap method, then creates an instance of a Map object the position, credentials, center, map type, and zoom level. The code continues on by centering the Pushpin to represent the user’s location in the map.

function showMap(position) {
 
    var latitude = position.coords.latitude;
    var longitude = position.coords.longitude;
 
    var map = new Microsoft.Maps.Map($("#map")[0],
    { 
        credentials: "Your Bing Maps API Key",
        center: new Microsoft.Maps.Location(latitude, longitude),
        mapTypeId:   Microsoft.Maps.MapTypeId.road,
        zoom:        10
    });   
 
    var center = map.getCenter();
    var pin = new Microsoft.Maps.Pushpin(center, { width: 50, height: 50, draggable: false });
    map.entities.push(pin);
}

The result should look something like this (but with your coordinates):

SNAGHTML1015b426

Should you want to customize the Pushpin icon, just change the Pushpin construction arguments, and pass in the path and name of the graphics file (.png, .jpg., and standard Web formats).

var pin = new Microsoft.Maps.Pushpin(center, {icon: 'CustomPushpin.png', width: 50, height: 50, draggable: true}); 

Customizing the map further by adding an Infobox, which is a small rectangle with information about a particular location, takes only a few lines of code. Make sure the clear method is run before pushing an Infobox onto a map or the latest Infobox, Pushpin, or other object will overlay the previous.

 map.entities.clear(); 
 var infoboxOptions = {title:'Bing Maps Rock!', description:'Add an Infobox to a map with very little JavaScript!'}; 
 var defaultInfobox = new Microsoft.Maps.Infobox(map.getCenter(), infoboxOptions );    
 map.entities.push(defaultInfobox);

The above code creates an Infobox on the map similar to the one shown here:

SNAGHTML101866d1 

These are just a few simple, but core examples, of what you can do with Bing Maps. For more information on developing for Bing Maps, see below in the Summary & Resources.

Summary & Resources

The Bing Maps AJAX control is a handy library you can use to add geo-interactivity to your Web sites with little code. Additionally, you can incorporate other APIs to make full featured location aware mapping apps.

Use the W3C Geolocation API to create location aware Web sites

The Bings Map control (Bing Maps API)

Bing Maps Articles

Customizing Bing Maps Pushpins

G. Andrew Duthie demonstrates bing maps in action with CommunityMegaphone.com

ASP.NET MVC ActionResults explained

Action results are an important part of the ASP.NET MVC controller system, and definitely worth taking a good look at. Understanding how they work gives you many more choices in MVC and that will certainly help make your code better.

What is an ActionResult?

An ActionResult is a return type of a controller method, also called an action method, and serves as the base class for *Result classes. Action methods return models to views, file streams, redirect to other controllers, or whatever is necessary for the task at hand. The controller takes on this responsibility to connect system components, acting as a traffic cop.

There are many derived ActionResult types you can use to return results that are more specific for a particular view. You can quickly access the derived types of the ActionResult during development by hovering over an ActionResult in an action result’s method signature then expanding the type tool window, to see what *Results the ASP.NET Framework provides.To get a deeper look at what exactly an ActionResult type is and how it works, running the code with a breakpoint set at the end of an action result method will get the information we want. Inspecting the image below of the Watch window shows some of the properties that you can tap into that ActionResults return.

Notice the Model, TempData, ViewBag, and ViewData properties. Drilling into the Watch window even further exposes the Model property’s strongly typed collection of objects.

SNAGHTML4d9b785_thumb3_2

These objects contain everything you need when working in the view. Of course, the Model is the most heavily used object, containing our application’s schema and data. The TempData object holds data between multiple controllers, while ViewBag and ViewData objects holds data between controllers and/or views.

Since the Model property is the actual model the view uses to render the data, its data type should align with the type specified in the @model directive in the target view. As pointed out in the image above, the Model property contains a strongly typed list of Product objects (or whatever you’re returning), matching the view’s model.

Looking in the Watch window shows that the runtime converts the ActionResult to a ViewResult, however you’ll want to be more specific during design time. Swapping ActionResults for more specific/derived classes, for example, a ViewResult, produce the exact same object structure as the ActionResult. With this in mind, using more specific types increases code accuracy, maintainability, and even performance as the compiler has a much better idea of what should happen at compile time, rather than at the last minute at runtime, since no runtime conversion happens.

Action methods, action results & routing

Action methods and the routing system work together in every MVC application. MVC does this by using a set of conventions, defined as routing patterns in the global.asax.cs file. These patterns connect HTTP requests with controllers and action methods. As an HTTP Request enters the routing system, it determines which controller should serve data to which view (if any).

The global.asax.cs defines the default routing pattern, {controller}/{action}/{id}, as described in more detail here:

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

    routes.MapRoute(
    "Default", // Route name
    "{controller}/{action}/{id}", // URL with parameters
    new { controller = "Home", action = "Index", id = UrlParameter.Optional } // Parameter defaults
    );
}

Picking apart each piece of the route pattern is a great way to digest what the routing system is doing…

  • {controller} Controller maps a part of the URL to the name of the controller class. For example, a class named ProductsController, will map to URLs that start with /Products (after the domain of course). ASP.NET automatically drops the word “Controller” from the URL so is it’s more user friendly, e.g., /Products vs. /ProductsController.
  • {action} Action maps a part of the URL to the individual methods inside controllers. Therefore the ProductsController.Edit(…) and ProductsController.Details(…) methods align with the /Products/Edit and Products/Details URLs, respectively. Action maps without any parameters, since the next route pattern, id, defines them.
  • {id} Id maps to an identifier, such as a product id or a product name. These are controller action method parameters, so the value at the end of the URL is generally the value of the method’s argument. For example, /Products/Edit/2 matches up with the id argument in ProductsController.Edit(int id). The controller methods normally use this id to query for a single record with a matching id to return to the view.

Below is a table detailing the mappings between routes, controllers, action methods and their parameters.

Action Method Route {controller}/{action}/{id} HTTP POST/GET
public ActionResult Index() { } /Products GET
public ActionResult Details(int id) { } /Products/Details/id GET, values in URL
public ActionResult Edit(int id) { } /Products/Edit/id GET, values in URL
[HttpPost]
public ActionResult Edit(int id, FormCollection collection) { }
/Products/Edit/id POST, values in FormCollection
public ActionResult Create() { } /Products/Create GET
[HttpPost]
public ActionResult Create(FormCollection collection) { }
/Products/Create POST, values in FormCollection
public ActionResult Delete(int id) { } /Products/Delete/id GET, values in URL
[HttpPost]
public ActionResult Delete(int d, FormCollection collection) { }
/Products/Delete/id POST, values in FormCollection

You may have noticed that the Edit, Create, and Delete action methods come overloaded as pairs, and an [HttpPost] attribute decorates one method in each pair. Since [HttpGet] is the default, the other method doesn’t need to be marked. Additionally, all methods decorated with the [HttpPost] attribute are meant to accept HTML input fields located between the <form> tags. The collection parameter of type FormCollection[1] contains all the input fields from the <form> of the HTTP Post.

Every method in a controller class returns an ActionResult by default; however, some actions will be more optimized, clear, or accurate in the code, if we are to specify a more specific action results, for instance, a ViewResult, rather than an ActionResult. Action result methods can also designate that its result will return something other than data for a view, e.g., a HttpNotFoundResult or an HttpStatusCodeResult, as shown in the code below:

Returns an HTTP 404 Not found error:

public HttpStatusCodeResult NotFound()
{
    var result = new HttpStatusCodeResult(404);
    return result;
}

Redirects to a separate view altogether:

[HttpPost]
public RedirectResult Create(FormCollection collection)
{
    // code to save form data ...     
    return new RedirectResult("Home/Index", false);
}

There’s many more ActionResult types to explore. Check them out and find something that meets the needs of your controller and/or view.

Summary

ActionResults are a key component to ASP.NET MVC, so understanding them is essential for MVC application development. Whether you need to make AJAX calls, redirect, return a file stream, or just return data to a view, ActionResults are right there in the center of all the……action.

[1] I recommend rather than using FormCollection, you should use a strongly typed parameter or multiple, differently typed parameters that match to data types in the HTML form. Look forward to a blog post soon to demonstrate this.