Language

Getting Started with ASP.NET MVC 6

By Mike Wasson|

The next version of ASP.NET (“ASP.NET vNext”) has been re-designed from the ground up. The goal is to create a lean and composable .NET stack for building modern cloud-based apps.

This tutorial describes the new ASP.NET MVC 6 framework, which unifies MVC, Web API, and Web Pages.

As part of ASP.NET vNext, the MVC, Web API, and Web Pages frameworks will be merged into one framework, called MVC 6. The new framework removes a lot of overlap between the existing MVC and Web API frameworks. It uses a common set of abstractions for routing, action selection, filters, model binding, and so on. You can use the framework to create both UI (HTML) and web APIs.

This overview is designed to get you started with ASP.NET MVC 6. Because vNext is still an early preview, I won’t walk through creating an entire real-world application. Instead, I want to highlight some of the features and show enough code to get you started.

This overview assumes you are familiar with either MVC 5 or Web API 2. If not, here is some terminology that is used in ASP.NET MVC.

  • A controller handles HTTP requests and executes application logic.
  • Actions are methods on a controller that get invoked to handle HTTP requests. The return value from an action is used to construct the HTTP response.
  • Routing is the mechanism that selects which action to invoke for a particular HTTP request, usually based on the URL path and the HTTP verb.
  • A view is a component that renders HTML. Controllers can use views when the HTTP response contains HTML.
  • A model is an object that represents the domain data in your application. Typically an app either renders the model as HTML, or serializes the model into a data format such as JSON.
  • Razor syntax is a simple programming syntax for embedding server-based code in a web page.

I've defined some of these terms in a way that is specific to ASP.NET. For example, controllers have a particular purpose in ASP.NET MVC, but “model-view-controller” is a more general pattern, used by many frameworks.

You can use Visual Studio "14" to create and build MVC 6 projects. For more information, see Getting Started with ASP.NET vNext and Visual Studio "14". You can also build and run an MVC 6 application from the command line. To use the command-line tools, follow the instructions on the project wiki.

A minimal vNext project contains two files:

  • project.json. This file lists the dependencies for the application.
  • A startup class.

If you are using Visual Studio "14", create these files by using the vNext Web Application templates. Otherwise, you can copy them from the HelloMvc sample.

The startup class is where you configure the HTTP request pipeline for your application. Here is a simple example.

using Microsoft.AspNet.Builder;

public class Startup
{
    public void Configure(IBuilder app)
    {
        app.UseWelcomePage();
    }
}

By default , the hosting environment expects the startup class to be named Startup. The startup class must contain a method named Configure with the signature shown here. Inside this method, use the IBuilder interface to configure the application.

The UseWelcomePage methods adds a middleware component that just displays a welcome page. The welcome page is useful for diagnostic purposes, to make sure your project is configured and running correctly.

To run the application from the command line, type the following commands:

kpm restore
k web

The kpm restore command resolves the dependencies listed in the project.json file, and downloads the necessary NuGet packages. The k web command starts the HTTP listener. Notice there is no explicit build step. The k web command compiles the code on the fly. After you install the NuGet packages, you can make changes to the code and run k web again, without running kpm restore.

Next, launch a browser and navigate to http://localhost:5001. You should see the welcome page.

The web command is defined in the project.json file:

  "commands": {
    "web": "Microsoft.AspNet.Hosting server=Microsoft.AspNet.Server.WebListener server.urls=http://localhost:5001"
  },

This command starts the hosting environment and listens on the specified localhost address. You can edit the project.json file to use a different port number.

Serving Static Files

The welcome page is not too interesting, so lets’s enable the app to serve static files. Add the following entry to the “dependencies” section of the project.json file:

"Microsoft.AspNet.StaticFiles": "0.1-alpha-build-0402"

Modify the Startup class as follows.

using Microsoft.AspNet.Builder;
using Microsoft.AspNet.StaticFiles;

public class Startup
{
    public void Configure(IBuilder app)
    {
        app.UseStaticFiles();
    }
}

Getting Started with MVC 6

In the rest of this overview, we’ll explore some of the features of MVC 6. To enable MVC, modify the Startup class as follows.

using Microsoft.AspNet.Routing;
using Microsoft.AspNet.Builder;
using Microsoft.Framework.DependencyInjection;

public class Startup
{
    public void Configure(IBuilder app)
    {
        app.UseServices(services =>
        {
            services.AddMvc();
        });

        app.UseMvc(routes =>
        {
            routes.MapRoute(
                name: "Default",
                template: "{controller}/{action}/{id?}",
                defaults: new { controller = "Home", action = "Index" });
        });

    }
}

This code enables MVC and defines a route. If you’ve used earlier versions of MVC, the MapRoute method should look familiar. For comparison, here are the same routes defined in MVC 5 and MVC 6:

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

// MVC 6 route
routes.MapRoute(
    name: "Default",
    template: "{controller}/{action}/{id?}",
    defaults: new { controller = "Home", action = "Index" }
);

The ‘?’ character in the template means the {id} segment is optional.

Next, add a controller class. The following controller defines a single action named Index that returns a view.

using Microsoft.AspNet.Mvc;

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

Except for the namespace, this code would compile in MVC 5.

Now add a view. Create a file named ./Views/Home/index.cshtml and paste in the following code.

@{
  var message = "Hello World";
}

<!DOCTYPE html>

<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Index Page</title>
</head>
<body>
  <h1>@message</h1>
  <p>Index page</p>
</body>
</html>

I included a @message variable just to show that this is a Razor file and not just static HTML.

Here is the file structure for the project:

.\HomeController.cs
.\project.json
.\Startup.cs
.\Views\Home\Index.cshtml

Run the app by using the k web command, and then navigate to http://localhost:5001. You should see the HTML that is rendered by the Index view.

View Models

You can pass a model to the view. Let’s add a model class:

public class MessageModel
{
    public string Message { get; set; }
}

Modify the action by passing an instance of MessageModel to the View method:

public class HomeController : Controller
{
    public ActionResult Index()
    {
        var model = new MessageModel { Message = "Hello ASP.NET" };
        return View(model);
    }
}

Update index.cshtml to refer to the model.

<!DOCTYPE html>

<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Hello World Page</title>
</head>
<body>
  <h1>@Model.Message</h1>
</body>
</html>

Now when you run the app, "Hello ASP.NET" is rendered inside the H1 tag.

Creating Web APIs and REST-Style Actions

If the route template does not include {action}, the framework uses the HTTP verb to select the action name. This style of routing is similar to convention-based routing in the current version of ASP.NET Web API, and is useful for REST-style APIs.

Here is an example of a route template without an {action} variable.

app.UseMvc(routes =>
{
    routes.MapRoute("ApiRoute", "{controller}/{id?}");
});

Using this route template, the action name maps to the HTTP verb in the request. For example, a GET request will invoke a method named Get, a PUT request will invoke a method named Put, and so forth. The {controller} variable still maps to the controller name.

The following controller uses this style of routing.

using Microsoft.AspNet.Mvc;

public class ValuesController : Controller
{
    // GET /values
    public string Get()
    {
        return "Values";
    }

    // GET /values/1
    public string Get(int id)
    {
        return "Value " + id.ToString();
    }

    // POST /values
    public ActionResult Post()
    {
        return new HttpStatusCodeResult(201);
    }
}    

The following table shows the web API that is defined by ValuesController.

Request MethodURI PathController Action
GET/valuesGet
GET/values/1Get(id)
POST/valuesPost

The two Get actions both return strings. In that case, the framework writes the string into the body of the HTTP response, and sets the Content-Type header to “text/plain”. For example, if you send a GET request to /values/1, the response will look similar to the following.

HTTP/1.1 200 OK
Content-Type: text/plain
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 30 Apr 2014 00:16:38 GMT
Content-Length: 7

Value 1

The Post action returns an HttpStatusCodeResult. The framework translates this into an HTTP status code.

HTTP/1.1 201 Created
Content-Length: 0
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 30 Apr 2014 00:18:58 GMT

If you are familiar with ASP.NET Web API, you may have noticed that ValuesController derives from Controller, not ApiController. That’s because vNext does not have a separate controller class for web APIs.

In the current ASP.NET framework, MVC 5 and Web API 2 use completely different classes and namespaces. That means a controller is either an MVC controller or a Web API controller. Web API controllers use separate routes, and they can't use MVC filters or MVC model binders.

One goal of ASP.NET vNext is to merge MVC and Web API into a single framework, which shares a single pipeline and uses the same routing, action selection, filters, model binding, and so forth. The result will be a more consistent programming model, and code that is more re-usable.

Returning JSON

To serialize an object into JSON format, call Controller.Json. This method returns a JsonResult, which is an action result that serializes an object to JSON format. For example, let’s add a model class named Movie.

public class Movie
{
    public string Title { get; set; }
    public int Year { get; set; }
    public string Genre { get; set; }
}

Here is a controller that returns a list of movies in JSON format.

using Microsoft.AspNet.Mvc;

public class MoviesController : Controller
{
    public ActionResult Get()
    {
        var movie = new Movie
        {
            Title = "Maximum Payback", Year = 1990, Genre = "Action"
        };
        return Json(movie);
    }
}

The response from the Get action will look similar to the following.

HTTP/1.1 200 OK
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 02 May 2014 20:39:25 GMT
Content-Length: 120

[{"Title":"Maximum Payback","Year":1990,"Genre":"Action"},{"Title":"Fatal Vengeance 2","Year":2012,"Genre":"Action"}]

Note: The preview release does not support content negotiation yet.

Areas

Areas are a way to group controllers, models, and views. In previous versions of MVC, you register areas by calling AreaRegistration.RegisterAllAreas. Area controllers are placed in a special Areas folder.

In MVC 6, you create a route template with an {area} parameter, and then decorate area controllers with the [Area] attribute. The following code defines an area route.

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "AreasRoute",
        template: "{area}/{controller}/{action}");

    routes.MapRoute(
        name: "Default",
        template: "{controller}/{action}/{id?}",
        defaults: new { controller = "Home", action = "Index" });
});

Given these routes, you could define two Home controllers, as follows:

namespace MyApp.Controllers
{ 
    public class HomeController : Controller
    {
        // Home/Index
        public ActionResult Index()
        {
            return View();
        }
    }
}
namespace MyApp.Areas.Controllers
{
    [Area("Books")]
    public class HomeController : Controller
    {
        // Books/Home/Index
        public ActionResult Index()
        {
            return View();
        }
    }
}

The second controller is assigned to the Books area.

URIController
/Home/IndexMyApp.Controllers.HomeController
/Books/Home/IndexMyApp.Areas.Controllers.HomeController

Views for an area go into a folder named “Areas/{area name}/Views/{controller}”. So in this example, the view for the Books/Home/Index action would go in a file named “Areas\Books\Views\Home\index.cshtml”.

Previously, the Web API framework did not support areas. Because MVC 6 merges the two frameworks, you can now organize web API-style controllers into areas.

View Components and Child Views

View components are similar to child actions in previous versions of MVC. They allow a view to invoke an action and render the result within the view. The following code shows a simple view component that writes a text string.

[ViewComponent(Name = "MyViewComponent")]
public class SimpleViewComponent : ViewComponent
{
    public IViewComponentResult Invoke(int num)
    {
        var message = String.Format("The secret code is: {0}", num);
        return Result.Content(message);
    }
}

To include this view component in a view, call Html.Component.

<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Index Page</title>
</head>
<body>
  <p>@Component.Invoke("MyViewComponent", 42)</p>
</body>
</html>

When the view is rendered, the p tag will contain the string "The secret code is 42". Notice that you can pass parameters to the view component’s Invoke method.

POCO Controllers

In MVC 6, controllers do not need to derive from Microsoft.AspNet.Mvc.Controller. You can write a controller as a simple class or “POCO” (plain old CLR object). Here is an example.

public class HomeController
{
    // Helpers can be dependency injected into the controller
    public HomeController(IActionResultHelper resultHelper)
    {
        Result = resultHelper;
    }

    private IActionResultHelper Result { get; set; }

    public ActionResult Index()
    {
        return Result.Json(new { message = "Poco controllers!" });
    }
}

IActionResultHelper is a helper for creating action results. Notice that the IActionResultHelper instance is injected into the controller via the constructor. The framework provides a default IActionResultHelper implementation, and automatically injects it. You could also provide your own implementation of IActionResultHelper.

Previously, I showed a controller calls Controller.Json to return JSON data. That method is really just syntactic sugar for calling IActionResultHelper.Json.

The Controller class also gives you convenient access to the HTTP request context, the current principal (IPrincipal), a view bag, and other useful properties. So the Controller class is certainly useful, but it’s not required. For a light-weight controller, you might prefer a POCO controller.

Providing Feedback

Feedback is welcome. You can provide feedback in GitHub, in comments on this page, or in the ASP.NET VNext forum. If you ask a question in StackOverflow, use the asp.net-vnext tag. You can make suggestions for new features on the UserVoice site.

Author Information

Mike Wasson

Mike Wasson – Mike Wasson is a programmer-writer at Microsoft.