Cutting the Bloat and Cruft Out of the Standard ASP.NET WebApi Project in Visual Studio

---

The default WebApi project template that ships with Visual Studio 2012 has a lot to offer in some respects, but is less than ideal for either learning your way through the impressive WebApi framework, or building a lean, mean API project with a minimal footprint.

The default template in VS 2012 creates a project with no less than 40 references alone, which include a whole lot of stuff you may not want or need for your Simple API project. Also, the project created includes a morass of script files, images, Nuget Packages, and other supporting items for a fully-functional MVC site, but not needed for all API projects. In fact, there is a good chance your project needs only a fraction of the total.

• Getting and Installing the Empty WebApi Template
• Creating the Empty WebApi Project from the New Template
• Updating the Nuget Packages
• Adding WebApi Tracing (Optional)
• Add Routing and Filters
• Updating the Global.asax File
• Convention Over Configuration: Add Models and Controllers Folders
• Setting the Appropriate Start Action
• Clone the Source Code from this Post or Download a Zip File

The Default WebApi Project is Cool, for Certain Cases, But Overkill for Many

---

Lest you think I am dumping on the ASP.NET team, I am not. Far from it. The default WebApi project comes pre-fabbed with literally everything you need to jump-start a large and complex Web Service/API project, including self-updating, user-facing API Documentation (that's the purpose of the full-formed MVC site that loads with the project). Just checking out the solution explorer tells a story about the size of project you are getting, when you consider that each of those folders is basically bulging with files:

However, if you want to start simple, there's a lot to wade through here, and it can make figuring out what's going on rather challenging. Here is how to fix that.

I. Get the Empty ASP.NET WebApi Project Template from Visual Studio Gallery

---

Nikos Baxevanis has authored a terrific installable template for WebApi projects which is really, really empty. It installs into VS and is available as an ASP.NET MVC 4 Template through the File/New Project Menu. Once you install the template into VS, you can create a very empty WebApi project. After we add a few helpful items back in, we still end up with a project with less than half the dependencies, and a small fraction of the files found in the standard VS WebApi template project.

• Download the Installer HERE
• Make sure all instances of Visual Studio are CLOSED
• Run the installer

II. Create an Empty WebApi Project

---

Now, Open Visual Studio. Go to File/New Project, and select the ASP.NET MVC 4 Web Application Template:

Then, once you name your project appropriately, and hit Ok, you will see the available templates for this project type. Notice, there is now an Empty WebApi Project template (this was not there before):

Once you hit Ok, VS will create a project with far fewer references, and none of the extra stuff that came with the standard WebApi project:

At this point, we are almost, but not quite, done.

III. Making it Work: Update the Nuget Packages for the Empty WebApi Template

---

WebApi has been updated since the last time the Empty WebApi Template has been updated, so we need to update the packages used in our project. In the next steps, we will be adding some items to our project which depend on the most current packages for WebApi. in VS, go to the Tools Menu/Library Package Manager/Manage Packages for Solution:

Update all of the packages listed.

IV. Making it Work: Add the Microsoft.AspNet.WebApi.Tracing Package (Optional)

---

ASP.NET WebApi projects commonly include tracing to make debugging a little less unpleasant, via the Microsoft.AspNet.WebApi.Tracingpackage. While not a requirement, you may consider adding this package via Nuget. Once again, open Tools Menu/LibraryPackage Manager/Manage Packages for Solution, then type WebApi.Tracing in the Search box. Select the Microsoft.AspNet.WebApi.Tracing package, and click Install:

V. Making It Work: Adding WebApi Routing and Filters

---

Now that you have a more streamlined starting point, you will likely want to add a few things back in. In order to take advantage of the awesome that the MVC Team has created with WebApi (and to follow the MVC philosophy emphasizing convention over configuration), we will want some routing, and probably (but not necessarily) we will want to adhere to some MVC conventions in our project organization.

Add a new folder to the project, and name it App_Start (similar to that in the default MVC and/or WebApi Project template). Then right-click on the folder and select "Add Class" and name it  WebApiConfig.cs. Add the following code in place of the default code that VS creates in the class (note this is a static class). This class will set up the default routing convention similar to any other ASP.NET MVC Project. Note to replace the using statements at the top of the file as well as the code body:

Code for the WebApiConfig Class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
namespace EmptyWebApiProject.App_Start
{
publicstaticclass WebApiConfig
    {
publicconststring DEFAULT_ROUTE_NAME = "MyDefaultRoute";
publicstaticvoid Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: DEFAULT_ROUTE_NAME,
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
            config.EnableSystemDiagnosticsTracing();
        }
    }
}

Now, Add another class, and name it FilterConfig.cs. Copy the following code in place of the VS-generated code (as before, make sure to add the using statements as well as the code body):

Code for the FilterConfig Class:

using System.Web;
using System.Web.Mvc;
namespace EmptyWebApiProject.app_start
{
publicclass FilterConfig
    {
publicstaticvoid RegisterGlobalFilters(GlobalFilterCollection filters)
        {
            filters.Add(new HandleErrorAttribute());
        }
    }
}

VI. Making it Work: Update the Global.asax File to initialize Routes and Filters

---

Now that we have added the Routing and Filter files, we need to make sure we initialize them in our Global.asax file. Open that file and add the lines indicated to the existing code:

using System.Web;
using System.Web.Http;
using System.Web.Mvc;
//Add this Using Statement:
using EmptyWebApiTemplateProject.app_start;
namespace EmptyWebApiProject
{
// Note: For instructions on enabling IIS6 or IIS7 classic mode, 
// visit http://go.microsoft.com/?LinkId=9394801
publicclass WebApiApplication : HttpApplication
    {
protectedvoid Application_Start()
        {
            AreaRegistration.RegisterAllAreas();
// Add these two lines to initialize Routes and Filters:
            WebApiConfig.Register(GlobalConfiguration.Configuration);
            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
        }
    }
}

VII. Add a Models Folder and a Controllers Folder to Maintain Convention

---

While not required, it makes sense to adhere to conventions established for ASP.NET/MVC by organizing the code in your project. In the case of an API project such as we are creating here, the Models will, as usual, represent our data. However, unlike a standard MVC project, the Controllers, in this case, will all inherit from System.Web.Http.ApiController instead of System.Web.Mvc.Controller. For the moment, add the folders as seen below, and we now have a greatly simplified WebApi project structure:

Solutions Explorer with Added Models and Controllers Folders:

VIII. Set Appropriate Start Action and Note the Server Properties

Since we are building a minimal API service and not a web site, we may want to modify what happens when we run our project in Visual Studio. Unless (or until) you plan to have your API project display a home page, you might consider setting the runtime property setting such that VS does not try to open your site in a local browser when debugging. While the project will still run properly on whichever development server you have configured in Visual Studio, your default browser will try to open the page and show an error, which can be distracting.

In the Solution Explorer, double-click the project Properties folder. This will open the Project settings. Click on the "Web" tab. Your default web settings will probably look something like this:

Default VS Start Action Settings:

Not the highlighted item. We don't want a page to open (unless you are going to add one to the project), so we want to change that. Select the, "Don't open a page . . ." option instead:

Modified VS Start Action Settings:

While you are here, scroll the window down, and take note of the Server Settings. The default will usually be to use the Local IIS Web Server/IIS Express installed with Visual Studio. This is fine, but note the Project URL and specifically, the port setting. You will need to use this when consuming your API externally while debugging. Or, you may choose to switch to the Visual Studio Development Server and specify a port manually. In either case, when you call into your API Project from an external project while debugging you will need to use this as the root URL.

Default Server Settings for Local Debugging:

Clone this Project from Source or Download as a Zip File

You can clone this ready-to-build-out project as we've put it together here from my Github Repo, or download the Zip file. Beware, the repo is a little kludgy (especially if you navigate into the "packages" directory), as I included all of the Nuget Packages required so that the project will be fully functional out of the box.

Note that cloning this project will not give you the installed template we examine in the post above. But you can clone this project, renamed appropriately, and build it out to suit. Also, if you find ways to improve on it, shoot me a pull request. I am capable of missing important stuff, and doing dumb things!

Ready to Build it Out?

To this point we have examined how to install the empty WebApi template, and add the minimal additional items such as routing, filters, and a familiar folder structure needed to get an MVC-conformant API project ready to build. Next, we'll build out a basic example project using our streamlined WebApi Template. 

Next: Building a WebApi Example with the Minimal WebApi Project

Build Out a Clean, Minimal-Footprint REST-ful API

---

In a previous post, we saw how to create a minimal ASP.NET WebApi project template, so that we can avoid some of the bloat and complexity inherent in the standard VS WebApi project. Getting started building out an API project using the minimal project template is much easier, and we can always add back stuff as our project grows.

For starters, though, the minimal project makes it much easier to focus on our principle task – creating a simple, clean API. This minimal project is especially useful if, like myself, you are less-than-experienced, and learning your way through Web API development. Or, if you just want a simple project.

The source code for the projects used in this article can be found at my Github Repo:

• Empty WebApiProject (Ready-to-Use)
• MinimalApiDemo
• MinimalWebApiClientDemo
• Modeling Data
• WebApi Controllers
• Api Controllers - a Closer Look
• Creating a Simple Console API Client
• WebApi Built-in Serialization
• JSON-Based Example Code
• Class-Based Example Code

I. Create an Empty (or nearly so) WebApi Project

As we have seen, the default WebApi project in Visual Studio can be a bit much. To start with a stripped-down, minimal project template, either review the previous post referred to in the link above, which will install the Empty WebApi Project template into Visual Studio directly, clone the EmptyWebApi Project from my Github Repository, or download the zipped project. 

II. Modeling Our Data

In building our example, we will adhere to what are recommended conventions for an MVC project. While we are not creating a website proper, it will serve us well to follow the conventions designed into the MVC framework (of which WebApi is a part). Note how I have set up the basic project, with a Models folder and a Controllers folder (at this point, we don't need Views). If you have worked with a standard ASP.NET MVC project before, this part should look pretty familiar.

Right-click on the Models folder in Solution Explorer, and select the "Add Class" Menu Item. Name the class Person and hit Ok. Now add the following code to the Person class:

Code for the Person Class:

publicclass Person
{
publicint Id { get; set; }
publicstring FirstName { get; set; }
publicstring LastName { get; set; }
}

The Person class will be used to represent data from our data store once loaded into our application. Again following something of a convention, we will use a simple repository pattern to represent our database. It is good practice to use an interface to abstract away the specific implementation of your data store, and we will do so here. First of all, because we are going to avoid cluttering up this tutorial (at this point) with details of wiring up a database, and second of all because even in a finished project, your data storage requirements may change. With a properly implemented interface representing your datastore in code, changing up the database-specific code does not require changes to the rest of our project, only the concrete database implementation classes.

NOTE: I am aware that the Repository Pattern has fallen slightly out-of-favor in some quarters. Also, If you are planning to use Entity Framework, NHibernate, or another ORM, your approach in a real project might be different with respect to actual data access implementation. However, for this simple example, the repository pattern works.

Right-click on the Models folder again, and this time select "Add New Item." From from the "Code" sub-menu, select "Interface." Name the interface IPersonRepository and hit Ok. Then, add the following code to the newly created interface:

Code for the IPersonRepository Interface:

interface IPersonRepository
{
    IEnumerable<Person> GetAll();
    Person Get(int id);
    Person Add(Person person);
void Remove(int id);
bool Update(Person person);
}

Now that we have defined the interface for our repository, let's create a concrete implementation. Right-click once more on the Models folder in Solution Explorer, and select "Add Class" again. Name the new class PersonRepository and hit Ok. Now add the following code, which we'll walk through in a moment:

Code for the PersonRepository Class:

publicclass PersonRepository : IPersonRepository
{
// We are using the list and _fakeDatabaseID to represent what would
// most likely be a database of some sort, with an auto-incrementing ID field:
private List<Person> _people = new List<Person>();
privateint _fakeDatabaseID = 1;
public PersonRepository()
    {
// For the moment, we will load some sample data during initialization. 
this.Add(new Person { LastName = "Lennon", FirstName = "John" });
this.Add(new Person { LastName = "McCartney", FirstName = "Paul" });
this.Add(new Person { LastName = "Harrison", FirstName = "George" });
this.Add(new Person { LastName = "Starr", FirstName = "Ringo" });
    }
public IEnumerable<Person> GetAll()
    {
return _people;
    }
public Person Get(int id)
    {
return _people.Find(p => p.Id == id);
    }
public Person Add(Person person)
    {
if (person == null)
        {
thrownew ArgumentNullException("person");
        }
        person.Id = _fakeDatabaseID++;
        _people.Add(person);
return person;
    }
publicvoid Remove(int id)
    {
        _people.RemoveAll(p => p.Id == id);
    }
publicbool Update(Person person)
    {
if (person == null)
        {
thrownew ArgumentNullException("person");
        }
int index = _people.FindIndex(p => p.Id == person.Id);
if (index == -1)
        {
returnfalse;
        }
        _people.RemoveAt(index);
        _people.Add(person);
returntrue;
    }
}

Note in the code above, we are using a List<Person> to represent a datastore. In a real API application, you would most likely be using this class to access a database, XML file, or other persistence mechanism. We will look at connecting it all to a database in another post. For now I am keeping it simple, and loading some mock data into the list during initialization.

Using Api Controllers to Access Our API Service

Unlike an ASP.NET/MVC Project, which generally uses Controllers derived from System.Web.MVC.Controller, a WebApi project will generally utilize controllers derived from System.Web.Http.WebApiController. Like the standard MVC Controller, The WebApi Controller accepts incoming HTTP requests and processes accordingly. However, the standard MVC Controller returns a View, while the WebApi controller returns data.

Of particular note is that the WebApiController examines the Accept Header in the HTTP Request, and (where applicable) converts our .Net objects into the appropriate return data type (usually either XML or JSON). In this way, consumers of your API can specify the format required, and expect the proper return in the HTTP Response from the server. Content negotiation details are beyond the scope of this article, but suffice it to say that the WebApiController is what delivers the goods in a WebApiProject.

Right-click on the Controllers folder and select "Add Controller." In the dialog window, name the new controller PersonController and then select Empty WebApi Controller from the drop-down list of controller templates:

Notice that the generated class inherits from ApiController.

Now add the following code for some basic CRUD operations to the new controller (Note you need to add the using statement to reference the classes you defined in the Models Folder – see comment at the top of the class):

Code for the PersonController Class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
// Add a using statement to refer to Models:
using MinimalApiDemo.Models;
namespace MinimalApiDemo.Controllers
{
publicclass PersonController : ApiController
    {
staticreadonly IPersonRepository databasePlaceholder = new PersonRepository();
public IEnumerable<Person> GetAllPeople()
        {
return databasePlaceholder.GetAll();
        }
public Person GetPersonByID(int id)
        {
            Person person = databasePlaceholder.Get(id);
if (person == null)
            {
thrownew HttpResponseException(HttpStatusCode.NotFound);
            }
return person;
        }
public HttpResponseMessage PostPerson(Person person)
        {
            person = databasePlaceholder.Add(person);
string apiName = App_Start.WebApiConfig.DEFAULT_ROUTE_NAME;
            var response = this.Request.CreateResponse<Person>(HttpStatusCode.Created, person);
string uri = Url.Link(apiName, new { id = person.Id });
            response.Headers.Location = new Uri(uri);
return response;
        }
publicbool PutPerson(Person person)
        {
if (!databasePlaceholder.Update(person))
            {
thrownew HttpResponseException(HttpStatusCode.NotFound);
            }
returntrue;
        }
publicvoid DeletePerson(int id)
        {
            Person person = databasePlaceholder.Get(id);
if (person == null)
            {
thrownew HttpResponseException(HttpStatusCode.NotFound);
            }
            databasePlaceholder.Remove(id);
        }
    }
}

A Closer Look at the WebApi Controller

As we have alluded to previously, a core tenet of MVC is to favor Convention over Configuration. In terms of our controller class, what this means is that the ASP.NET/MVC runtime establishes certain default behaviors which require no additional configuration, unless you want to change them. Initially, for me anyway, this was also a source of confusion, as the runtime appeared to perform sufficient "magic" that I didn't know what was happening.

One of the MVC conventions is the mapping of controller methods to HTTP verbs. In our case, we are specifically mapping methods to the HTTP verbs GET, POST, PUT, and DELETE. Notice how our method names begin with one of these four verbs? Our two methods which retrieve person data, GetAllPeople and GetPersonByID begin with the word "Get." The MVC runtime will map HTTP GET requests to this controller and to one of these methods by following the convention set up in the Route mapping we registered in our WebApiConfig file:

If we go into the App_Start folder, and open the WebApiConfig file, we should see something similar to this:

publicstaticclass WebApiConfig
{
publicconststring DEFAULT_ROUTE_NAME = "MyDefaultRoute";
publicstaticvoid Register(HttpConfiguration config)
    {
        config.Routes.MapHttpRoute(
            name: DEFAULT_ROUTE_NAME,
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
        config.EnableSystemDiagnosticsTracing();
    }
}

In the above, the route template is used by the MVC framework to map incoming HTTP requests to the appropriately named controller (named such that the first part of the controller name matches the {controller} mapping, and to the most appropriate method with a name that begins with the HTTP verb specified in the request.

In order for all this to work, it becomes our responsibility to simply name our controllers and methods in accordance with this convention. For example, a GET request coming in with a URL mapping:

http://localhost:<port number>/person/

will be mapped to the PersonController.GetAllPeople() method, since the URL contains the Person mapping, the request contains the GET verb, and the optional /id parameter is not present.

Similarly, an HTTP GET request with the following URL mapping:

http://localhost:<port number>/person/2

will be mapped again to the PersonController, but this time to the GetPersonByID method, since the optional id parameter is provided.

Consuming The Example API with a Simple Console Client

The value of an exposed API service is that independent client applications can consume and interact with our API data in a manner we control through the API. We can make available as much, or as little, access as we wish. To demonstrate, we will create a very simple console application which will exercise our API project in a couple different ways.

To get started, open a second instance of Visual Studio, and use File –> New Project to create a Console Application. Then, go straight to the Tools –> Library Package Manager –> Manage Nuget Packages for Solution. Select "Online" in the left-hand tree menu, then, in the Search box, type "WebApi." Select the ASP.NET Web API Core Libraries package, and click Install.

Install WebApi Core Libraries in the Console Application

Once the installation is complete, select the Updates item from the left-hand tree menu. Install any relevant WebApi library updates.

WebApi and JSON give us Options for Client Code

WebApi provides flexible options for how we might retrieve data from our API application. Right out of the box, the WebApi library provides built-in serialization and de-serialization for POCO ("Plain Old CLR Objects") objects we might use, as well as send and receive straight JSON ("JavaScript Object Notation") or XML.

We will take a (very!) rudimentary look at client code that uses primarily JSON. One might at some point call into an API infrequently, and deem it not worth building a class hierarchy for these infrequent calls. We will also look at a more standard .NET approach, in which class models are built which represent data from the API we are consuming.

The example client project we are about to build by no means represents a design we might build in the real world. The purpose is to take a quick look at calling into a simple API and doing something semi-meaningful with the data.

IMPORTANT NOTE: for this sample code, I am using calls to GetAsync and ReadAsAsync and accessing the Result property of the return value. This creates blocking call, which is less than optimal for most real-world projects. I used this call to keep things simple in this demo. However, we will look at making non-blocking asynchronous calls in upcoming post.

Building the JSON-Based Example Code

The following example does not rely on a Person class being present. We will use the Newtonsoft JSON library installed with WebApi to parse and use JSON, and to basically shuttle our data around. Where needed, we will utilize C# Anonymous classes where the API we are calling into demands it.

In the example project, I basically added a separate class for the separate calls into our API project. Then, I added an ugly, monolithic method which walks through each, and writes the data retrieved out to the console window. The important part in the code below is getting a feel for making the API calls.

I added a class called JsonExamples for this. At the top of the class, make sure to add the following using statements:

Add Using Statements to the JsonExamples Class:

using System;
using System.Net.Http;
using Newtonsoft.Json.Linq;

Then, separate methods to call into our API project:

The Calls to the API GET, POST, PUT, and DELETE Controllers Using JSON:

// Sends HTTP GET to Person Controller on API:
static JArray getAllPeople()
{
    HttpClient client = new HttpClient();
    HttpResponseMessage response = 
        client.GetAsync("http://localhost:57772/api/person/").Result;
return response.Content.ReadAsAsync<JArray>().Result;
}
// Sends HTTP GET to Person Controller on API with ID:
static JObject getPerson(int id)
{
    HttpClient client = new HttpClient();
    HttpResponseMessage response = 
        client.GetAsync("http://localhost:57772/api/person/" + id).Result;
return response.Content.ReadAsAsync<JObject>().Result;
}
// Sends HTTP POST to Person Controller on API with Anonymous Object:
static JObject AddPerson(string newLastName, string newFirstName)
{
// Initialize an anonymous object representing a new Person record:
    var newPerson = new { LastName = newLastName, FirstName = newFirstName };
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:57772/");
    var response = client.PostAsJsonAsync("api/person", newPerson).Result;
return response.Content.ReadAsAsync<JObject>().Result;
}
// Sends HTTP PUT to Person Controller on API with Anonymous Object:
staticbool UpdatePerson(int personId, string newLastName, string newFirstName)
{
// Initialize an anonymous object representing a the modified Person record:
    var newPerson = new { id = personId, LastName = newLastName, FirstName = newFirstName };
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:57772/");
    var response = client.PutAsJsonAsync("api/person/", newPerson).Result;
return response.Content.ReadAsAsync<bool>().Result;
}
// Sends HTTP DELETE to Person Controller on API with Id Parameter:
staticvoid DeletePerson(int id)
{
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:57772/");
    var relativeUri = "api/person/" + id.ToString();
    var response = client.DeleteAsync(relativeUri).Result;
    client.Dispose();
}

Last, an ugly, procedural chunk of code that walks through each of the methods above and writes the results to the console window:

Ugly, Monolothic Console Output Code:

publicstatic void PrintJsonExamples()
{
    // WRITE ALL PEOPLE TO CONSOLE (JSON):
    Console.WriteLine("Retreive All The People:");
    JArray people = getAllPeople();
    foreach (var person in people)
    {
        Console.WriteLine(person);
    }
    // WRITE A SPECIFIC PERSON TO CONSOLE (JSON):
    Console.WriteLine(Environment.NewLine + "Retreive a Person by ID:");
    JObject singlePerson = getPerson(2);
    Console.WriteLine(singlePerson);
    // ADD NEW PERSON, THEN WRITE TO CONSOLE (JSON):
    Console.WriteLine(Environment.NewLine + "Add a new Person and return the new object:");
    JObject newPerson = AddPerson("Atten", "John");
    Console.WriteLine(newPerson);
    // UPDATE AN EXISTING PERSON, THEN WRITE TO CONSOLE (JSON):
    Console.WriteLine(Environment.NewLine + "Update an existing Person and return a boolean:");
    // Pretend we already had a person's data:
    JObject personToUpdate = getPerson(2);
string newLastName = "Richards";
    Console.WriteLine("Update Last Name of " + personToUpdate + "to " + newLastName);
    // Pretend we don't already know the Id:
    int id = personToUpdate.Value<int>("Id");
string FirstName = personToUpdate.Value<string>("FirstName");
string LastName = personToUpdate.Value<string>("LastName");
if (UpdatePerson(id, newLastName, FirstName))
    {
        Console.WriteLine(Environment.NewLine + "Updated person:");
        Console.WriteLine(getPerson(id));
    }
    // DELETE AN EXISTING PERSON BY ID:
    Console.WriteLine(Environment.NewLine + "Delete person object:");
    JsonExamples.DeletePerson(5);
    // WRITE THE UPDATED LIST TO THE CONSOLE:
    {
        // WRITE ALL PEOPLE TO CONSOLE
        Console.WriteLine("Retreive All The People using classes:");
        people = JsonExamples.getAllPeople();
        foreach (var person in people)
        {
            Console.WriteLine(person);
        }
    }
    Console.Read();
}

If we run the application by calling the PrintJsonExamples method, we see the JSON results in our console:

Console Output – Json Data:

Building the Class-Based Example Code

Depending on the needs of your project, you may decide adding a Person class to your API client makes sense. WebApi understands how to serialize and de-serialize .NET classes to and from JSON or XML, which are the two most common data exchange formats in use.

We can re-write our client examples to utilize a Person class if it suits our needs, and pass instances of Person to and from our API project indirectly through serialization. Our core client methods, re-written, look like this:

IMPORTANT: See the note above about the blocking calls used in this example!

The Calls to the API GET, POST, PUT, and DELETE Controllers Using an added Person Class:

// DEFINE A PERSON CLASS IDENTICAL TO THE ONE IN THE API:
publicclass Person
{
public int Id { get; set; }
publicstring LastName { get; set; }
publicstring FirstName { get; set; }
}
static IEnumerable<Person> getAllPeople()
{
    HttpClient client = new HttpClient();
    HttpResponseMessage response = 
        client.GetAsync("http://localhost:57772/api/person/").Result;
    client.Dispose();
return response.Content.ReadAsAsync<IEnumerable<Person>>().Result;
}
static Person getPerson(int id)
{
    HttpClient client = new HttpClient();
    HttpResponseMessage response = 
        client.GetAsync("http://localhost:57772/api/person/" + id).Result;
    client.Dispose();
return response.Content.ReadAsAsync<Person>().Result;
}
static Person AddPerson(Person newPerson)
{
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:57772/");
    var response = client.PostAsJsonAsync("api/person", newPerson).Result;
    client.Dispose();
return response.Content.ReadAsAsync<Person>().Result;
}
static bool UpdatePerson(Person newPerson)
{
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:57772/");
    var response = client.PutAsJsonAsync("api/person/", newPerson).Result;
    client.Dispose();
return response.Content.ReadAsAsync<bool>().Result;
}
static void DeletePerson(int id)
{
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:57772/");
    var relativeUri = "api/person/" + id.ToString();
    var response = client.DeleteAsync(relativeUri).Result;
    client.Dispose();
}

Next, some minor variations on the ugly console-output code:

Ugly, Monolithic Code, Modified:

publicstatic void PrintClassExamples()
{
string personOutputString = "id: {0};  LastName: {1}, FirstName: {2}";
    // WRITE ALL PEOPLE TO CONSOLE
    Console.WriteLine("Retreive All The People using classes:");
    IEnumerable<Person> people = ClassBasedExamples.getAllPeople();
    foreach (var person in people)
    {
        Console.WriteLine(personOutputString, person.Id, person.LastName, person.FirstName);
    }
    // WRITE A SPECIFIC PERSON TO CONSOLE:
    Console.WriteLine(Environment.NewLine 
        + "Retreive a Person object by ID:");
    Person singlePerson = ClassBasedExamples.getPerson(2);
    Console.WriteLine(personOutputString, singlePerson.Id, 
        singlePerson.LastName, singlePerson.FirstName);
    // ADD NEW PERSON, THEN WRITE TO CONSOLE:
    Console.WriteLine(Environment.NewLine 
        + "Add a new Person object and return the new object:");
    Person newPerson = new Person { LastName = "Atten", FirstName = "John" };
    newPerson = AddPerson(newPerson);
    Console.WriteLine(personOutputString, newPerson.Id, 
        newPerson.LastName, newPerson.FirstName);
    // UPDATE AN EXISTING PERSON, THEN WRITE TO CONSOLE:
    Console.WriteLine(Environment.NewLine 
        + "Update an existing Person object:");
    // Pretend we already had a person's data:
    Person personToUpdate = getPerson(2);
string newLastName = "Richards";
    Console.WriteLine("Updating Last Name of " 
        + personToUpdate.LastName + " to " + newLastName);
    personToUpdate.LastName = newLastName;
if (ClassBasedExamples.UpdatePerson(personToUpdate))
    {
        Console.WriteLine(Environment.NewLine + "Updated person object:");
        Person updatedPerson = getPerson(2);
        Console.WriteLine(personOutputString, updatedPerson.Id, 
            updatedPerson.LastName, updatedPerson.FirstName);
    }
    // DELETE AN EXISTING PERSON BY ID:
    Console.WriteLine(Environment.NewLine + "Delete person object:");
    ClassBasedExamples.DeletePerson(5);
    // WRITE THE UPDATED LIST TO THE CONSOLE:
    {
        Console.WriteLine("Retreive All The People using classes:");
        people = ClassBasedExamples.getAllPeople();
        foreach (var person in people)
        {
            Console.WriteLine(personOutputString, person.Id, 
                person.LastName, person.FirstName);
        }
    }
    Console.Read();
}

NOTE: The data in the API project is not persisted. However, until the IIS Server re-starts, the data is maintained between project debugging sessions. Re-start IIS Express by right-clicking the IIS Express icon in the system tray. Then stop and restart the API project.

Again, if we run our code, we will see the console output, this time reflecting the manner in which we decided to format our class data:

Console Output – Class-Based Data:

Wrapping Up

We've taken a look at building out a very basic API using the minimal components. We've also looked quickly at creating a basic client to consume such an API, independently of the API project itself. Next we will examine implementing proper asynchronous methods in an API client, and examine more advanced controllers and querying.

When getting started with ASP.NET MVC and/or the ASP.NET Web API, it can be overwhelming trying to figure out how it all works. These frameworks offer powerful features, and abstract away a good deal of pain associated with handling, routing, and responding to HTTP requests within an application. This is a great thing for seasoned developers who understand what it is the framework is doing "for" you (and how to modify that behavior, if desired). It also makes it easier for new or less-experienced folk to set up a basic site or API and watch it "just work."

On the other hand, the abstraction can make it challenging for those new to the MVC world to understand just what is going on, and where the critical functionality they want to modify "lives."

One of the fundamental concepts to understand when using ASP.NET MVC and/or the ASP.NET Web API is routing, which essentially defines how your application will process and respond to incoming HTTP requests.

Image by Andrew Morton

IMPORANT NOTE: This post covers the most basic and fundamental concepts of routing as applied to the ASP.NET MVC framework. The target audience are those with little or no familiarity with routing in general, or who may be looking to review the fundamentals. If you are an experience MVC developer, there is probably not much here for you, although your feedback in the comments is greatly appreciated.

In my next post, having covered the fundamentals, I will examine route customization. I will add a link here when that post is complete.

• What Makes a Good URL?
• How Routing Works in ASP.NET MVC
• Controller Matching
• Action Matching
• Action Parameter Matching
• Walk-Thru: the Default MVC Routing Template
• Route Parameter Defaults
• Other posts you may find useful

Routing Makes it All Work

---

Traditional web communication architecture maps a URL (Uniform Resource Locator) to a file within the file system. For example, the following:

http://mydomain.com/mybooks/favorites.html

would tend to map to a file named favorites.html, in the directory ~/mybooks/favorites, located in the root directory for the site mydomain.com. In response to an incoming HTTP request for this resource, the contents of the file are either returned (as in the example above, as HTML) or perhaps code associated with a file is executed (if, for example, the file were a .aspx file).

Within the MVC framework, as well as the Web API*, URLs are instead mapped to specific methods which execute in response to the incoming request, generally returning either a View (MVC) or some sort of structured data (Web API) corresponding to the the requested resource. In other words, instead of pointing to actual physical resources within a file system, MVC and Web API routes instead point to an abstraction which represents the resource requested, in both cases a method which will return the requested item.

NOTE: There are some subtle differences between MVC and Web API with respect to routing, but most of the concepts we cover here are mutually applicable. I attempt to clarify Web Api Routing Specifics in a separate post.

This de-coupling of the URL from the physical file system allows us to construct cleaner, more friendly URLs which are more beneficial to the user, search-engine-friendly, and (in theory) more persistent, meaning URLs associated with specific content are less likely to change, and break incoming links. In the authoritative book Professional ASP.NET MVC 4 , the authors refer to some common guidelines for high-quality URLs:

Usability expert Jacob Nielsen (www.useit.com) urges developers to pay attention to URLs and provides the following guidelines for high-quality URLs. You should provide:

• A domain name that is easy to remember and easy to spell
• Short URLs
• Easy-to-type URLs
• URLs that reflect the site structure
• URLs that are hackable to allow users to move to higher levels of the information architecture by hacking off the end of the URL
• Persistent URLs which don't change

* Technically, routing is incorporated into ASP.NET generally, and is available to all types of ASP.NET applications. However, the concept has been largely associated with MVC. Further, Web API actually contains its own implementation of routing, such the a Web API application can be hosted independently of ASP.NET and IIS.

How Routing Works in ASP.NET MVC

---

In MVC, the convention is to map URLs to a particular action (a method) on a particular controller. The action then executes, and (usually, but not always) returns an instance of ActionResult. The ActionResult class handles Framework logic such as rendering to HTML or JSON, and writing to the HTTP response that will be returned to the user's browser.

Once again, I defer to the authors of ASP.NET MVC 4 (who happen to also be members of the ASP.NET team):

"Routing within the ASP.NET MVC framework serves two main purposes:

• It matches incoming requests that would not otherwise match a file on the file system and maps the requests to a controller action.
• It constructs outgoing URLs that correspond to controller actions

The most basic version of this convention would be a URL as follows:

http://mydomain/controllername/methodname

In an MVC project, this is achieved by registering route templates which establish how incoming URLs will be mapped to specific controllers and actions. A typical MVC project defines a Global.asx file, which contains a single method – Application_Start. Within this method, calls are made to various configuration methods to set up the application's working state. One of these calls is to the RegisterRoutes method of the RouteConfig class found in the App_Start folder of the project.

Global.asx File and the RouteConfig File in a Typical MVC Project:

If we examine the Global.asx file, we find the following code:

The Default ASP.NET MVC Global.asx File:

publicclass MvcApplication : System.Web.HttpApplication
{
protectedvoid Application_Start()
    {
        AreaRegistration.RegisterAllAreas();
        WebApiConfig.Register(GlobalConfiguration.Configuration);
        FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
        RouteConfig.RegisterRoutes(RouteTable.Routes);
        BundleConfig.RegisterBundles(BundleTable.Bundles);
    }
}

For our purposes, we are interested only in the call to RouteConfig.RegisterRoutes. As we can see, the call passes the the Routes collection of the Global RouteTable as a parameter to the RegisterRoutes method, which then populates the routes collection with pre-defined route templates for the application. The default MVC project template comes with a single pre-configured route:

The Default MVC RouteConfig Class:

publicclass RouteConfig
{
publicstaticvoid RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
        routes.MapRoute(
            name: "Default",
            url: "{controller}/{action}/{id}",
            defaults: new
            { 
                controller = "Home", 
                action = "Index", 
                id = UrlParameter.Optional
            }
        );
    }
}

Note that any MVC application must have at least one route definition in order to function. In the above, a route template named "Default" is added to the routes collection. The items in curly braces enclose Route Parameters, and are represented by the parameter name as a placeholder between the curly braces. Route Segments are separated by forward slashes (much like a standard URL). Notice how the implied relative URL our route specifies matches the MVC convention:

~/{controller}/{action}

Route parameters can be named just about anything, however ASP.NET recognizes a few special route parameter names, in particular {controller} and {action} , and treats them differently than other route parameters.

Controller Matching

---

When the routing framework encounters a route parameter named {controller}, it appends the suffix "Controller" to the value of the parameter, and then scans the project for a class by that name which also implements the System.Web.Mvc.IController interface. Note that the search for a controller with a matching name is case-insensitive.

Action Matching

---

Once the framework has selected the proper controller, it attempts to locate an action on the controller with a name matching the {action} parameter value. The search for a matching action name is case-insensitive. If more than one action matches by name (as with multiple overloaded methods on the same controller), the framework will select the method for which the most URL parameters match method arguments by name.

Action Parameter Matching

---

Additional URL Parameters other than {controller} and {action} are available to be passed as arguments to the selected Action method. The framework will evaluate the input arguments of the available actions, and match them by name (case-insensitively) to the URL parameters other than {action} and {controller} . With certain restrictions, the framework will select that action with the greatest number of matching parameters.

Some things to consider:

• The MVC framework will first match method arguments by name to URL parameters. Then, it will attempt to match any query string parameters included in the URL by name. If the request is a POST, then the framework will attempt to match the contents of the POST body.
• Method arguments are evaluated for a match by name only. The framework does not consider the type required by the method argument. For example, a URL parameter named {id} with a value of "John" will be considered a match for a method which accepts an int argument named id.
• Action methods can be decorated with attributes which restrict the type of HTTP request they will respond to. Such attributes indicate the applicable HTTP verb to which the action will respond.

As an example of limiting the HTTP actions which a method may respond, consider the following:

Overloaded Action Method with HttpPost Attribute:

public ActionResult Edit(int id)
{
return View();
}
[HttpPost]
public ActionResult Edit(int id, FormCollection collection)
{
try
    {
// TODO: Add update logic here
return RedirectToAction("Index");
    }
catch
    {
return View();
    }
}

In the above, we find two methods named Edit. The first accepts an int named id as an argument, and the second accepts an int named id and a FormCollection (a complex type). The purpose of this overloaded method is so that a browser can:

• Request a view with which to edit a record of some sort and then,
• Submit the modified record values back to the site for storage.

The first Edit method, which requires only an intid argument will be called using HTTP GET, and return a view with the current representation of the data to be edited. Once the user has updated values in the view and submits the form data, an HTTP POST request is issued. The overloaded Edit method, decorated with the [HttpPost] attribute, is executed, and the modified data is persisted or otherwise processed. 

The MVC Default Route Template – Routing Walk-Thru

---

The route mapping assumes that the URL template specified is relative to the domain root for your site. In other words, since the entire application is hosted at http://yourdomain.com it is not necessary to include this domain root as part of the route template.

In the case of the default MVC mapping from our RouteConfig class above, the route contains the two special parameters, {controller} and {action}. In processing incoming requests, the framework appends "Controller" to the value provided for the {controller} parameter, and then searches the project for a controller class of that name. Once the proper controller has been identified, MVC next looks for a method name corresponding to the value of the {action} parameter, and then attempts to match any additional parameters with input arguments accepted by that method.

For example, if our application receives a request with the following URL:

http://mybookstore.com/books/details/25

the routing will match the default template. The string "Controller" will be appended to the "books" segment, and the runtime will set about searching the project for a class named BooksController. If the controller is located, MVC will then examine the controller for a public method named Details. If a Details method is found, MVC will attempt to find an overload which accepts a single argument named id, and then calls that method, passing in the final URL segment ("25" in this case) as an argument.

The following controller example would provide a suitable match for our incoming request:

A Simple Books Controller:

publicclass BooksController : Controller
{
public ActionResult Index()
    {
return View();
    }
public ActionResult Details(int id)
    {
return View();
    }
}

The incoming request would result in a call to the Details method, passing in the integer 25as the proper id argument. The method would return the appropriate view (how MVC does this is another convention for another post – let's stay focused on request routing for now).

Route Parameter Defaults

---

Notice in the RegisterRoutes method, the registration of the "Default" route also appears to assign some default values to the controller and action, parameters. These values will be used for any of these parameters if they are missing from the incoming request URL. Additionally, the id parameter is designated as optional. For example, consider the following URL:

http://mybookstore.com/books/

In this case, we have specified the Bookscontroller, but have not specified a value for the action or id. However, this route still matches our route definition, since MVC will provide the default value specified for the action parameter (in this case, index). Since the id parameter has been made optional in our route template, MVC will again search for a controller named BooksController, but in this case, examine the controller for a method named Index which does not require an argument. Again, a match is found, and the Index method is called, returning an appropriate view (most likely a list of all the books in the database).

The MVC default route mapping also specifies a default controller to use when no controller parameter is specified; namely, the "Home" controller. In other words, incoming requests to our domain root:

http://mybookstore.com/

will also match the default project controller. In this case, the runtime will attempt to locate a controller named HomeController, then locate the Index method of that controller. Since no id parameter was provided, the Index method will be called, returning the appropriate view ( most likely, the Homepage of our site).

What Next?

As we have seen above, MVC examines an incoming URL and attempts to map each URL segment to a controller and action according to the route templates set up in the RouteConfig.MapRoutes method. Once a proper controller and action have been identified, any additional URL segments (for example, the optional {id} segment in our example above) are evaluated against the action method signature to determine the best parameter match for the action.

But what happens when we need to do more than just send an ID in as an argument for the desired action method? Or, what if we have one or more overloaded methods by which we wish to perform more complex queries against our data?

While we can always include query parameters as part of our URL (and in fact we will no doubt have to resort to this at various points in our application design), we can customize and extend the default routing, and exert a little more control over how how and what our application will accept in an HTTP request by customizing our routes.

While the default /controller/action/id route baked into the MVC project template is a useful start and will handle many common controller cases, it is safe to say the MVC team did not expect developers to limit their applications to this minimally-flexible, single standard. Indeed, the ASP.NET routing framework (and the corresponding routing framework used by Web API) are very flexible, and within certain limits, highly customizable.

We'll look at route customization in the next post.

Additional Resources

---

• Routing Basics in ASP.NET Web API
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Getting Started with ASP.NET MVC

As noted in Routing Basics in ASP.NET MVC, routing in ASP.NET Web API is functionally very similar to the standard MVC routing. Understanding the MVC routing model will provide most of what you need to know to leverage that knowledge against the Web API framework, so long as you keep in mind the key differences between the two.

The differences between the two are largely dictated by the different consumption models driving each type of application.

Image by Ron Reiring

IMPORANT NOTE: This post covers the most basic and fundamental concepts of routing as applied to the ASP.NET Web API framework. The target audience are those with little or no familiarity with routing in general, or who may be looking to understand the most basic differences between routing in ASP.NET MVC and Web API.

If you have little to no knowledge of MVC routing, you may want to review my post on MVC routing basics first.

In my next post, having covered the fundamentals, I will examine route customization. I will add a link here when that post is complete.

• Web API Configuration Files
• How Routing Works for Web API
• The Default Web API Route Template
• Action Method Selection
• Web API and Action Naming
• What Have We Learned?
• Other Posts You May Find Useful

Web API and MVC – Two Separate Frameworks

---

Because the Web API grew (in part) out of the efforts of the ASP.NET MVC team, and because the default Web API project template in Visual Studio is bundled up inside an MVC application, it is easy to think that the Web API framework is some kind of subset of the MVC framework. In fact, the two inter-operate together very well, but that is by design. They are, in fact, separate frameworks which adhere to some common architectural patterns.

Instead of paraphrasing the overview of Web API and the architectural goals of the project, I will let the MVC team do so, because honestly, they know better than I do! from the most helpful book Professional ASP.NET MVC 4 authored by (mostly) the MVC team:

"ASP.NET MVC excels at accepting form data and generating HTML; ASP.NET Web API excels at accepting and generating structured data like JSON and XML." MVC has flirted with providing structured data support (with JsonResult and the JSON value provider), but it still fell short in several ways that are important to API programmers, including:

• Dispatching to actions based on HTTP verbs rather than action names
• Accepting and generating content which may not necessarily be object oriented (not only XML, but also content like images, PDF files, or VCARDs
• Content type negotiation, which allows the developer to both accept and genereate structured content independent of its wire representation
• Hosting outside of the ASP.NET runtime stack and IIS web server, something which WCF has been unable to do for years

The Web API team went to great lengths to try to allow you to leverage your existing ASP.NET experience with controllers, actions, filters, model binders, dependency injection, and the like. Many of these same concepts appear in Web API in very similar forms, which make applications that combine MVC and Web API seem very well integrated."

As noted above, one of the key differences between MVC and Web API is that Web API returns an appropriate representation of the model object as a result. A related difference is that Web API performs content type negotiation in response to incoming requests, and attempts to return the proper content type (JSON in response to an incoming request specifying JSON as the preferred content resource representation, for example).

Suffice it to say that Web API is an effort to create a mechanism for the efficient exchange of data and other content using HTTP. This effort is reflected in the architecture of the framework, and results in some of the differences in routing between the two frameworks.

Web API Route Configuration Files

---

The default Visual Studio Web API project template is rather large, as it incorporates a complete MVC project as well. The resulting project has some pretty cool features, including automatic documentation for the API you build (that is the purpose of the MVC site contained in the project), but also presents a rather bloated project file, with a large number of folders and dependencies.

NOTE: To see how to create a stripped-down Web API project template in Visual Studio, see Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4

As with a standard MVC project, the route configuration is called from the Global.asx file. However, in this standard Web API project, there exists both a RouteConfig class, and a WebApiConfig class, both in the Application_Start folder:

Global.asx File and the WebApiConfig File in a Typical MVC Project:

The RouteConfig.cs file here is the same as in any MVC project, and sets up routes for the MVC framework. The WebApiConfig.cs file is where our Web API routing configuration happens. However, if we open the file, it looks pretty familiar:

The WebApiConfig Class and MapHttpRoute Method:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
namespace StandardWebApiTemplateProject
{
publicstaticclass WebApiConfig
    {
publicstaticvoid Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

And, as we can see, the default route template for Web API looks a little different.

How Routing Works for Web API

---

Unlike ASP.NET MVC, the Web API routing convention routes incoming requests to a specific controller, but by default simply matches the HTTP verb of the request to an action method whose name begins with that verb. Recall the default MVC route configuration:

The Default MVC Route Template:

{controller}/{action}/{id}

In contrast, the default Web API route template looks like this:

The Default Web API Route Template:

api/{controller}/{id}

The literal api at the beginning of the Web API route template above makes it distinct from the standard MVC route. Also, it is a good convention to include as part of an API route a segment that lets the consumer know they are accessing an API instead of a standard site.

Also notice that unlike the familiar MVC route template, the Web API template does not specify an {action} route parameter. This is because, as we mentioned earlier, the Web API framework will by default map incoming requests to the appropriate action based upon the HTTP verb of the request.

Consider the following typical Web API Controller:

WebApi Controller from Default Visual Studio WebApi Template

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
namespace StandardWebApiTemplateProject.Controllers
{
publicclass ValuesController : ApiController
    {
// GET api/values
public IEnumerable<string> Get()
        {
returnnewstring[] { "value1", "value2" };
        }
// GET api/values/5
publicstring Get(int id)
        {
return"value";
        }
// POST api/values
publicvoid Post([FromBody]stringvalue)
        {
        }
// PUT api/values/5
publicvoid Put(int id, [FromBody]stringvalue)
        {
        }
// DELETE api/values/5
publicvoid Delete(int id)
        {
        }
    }
}

First, take note that Web API controllers do not inherit from System.Web.Mvc.Controller, but instead from System.Web.Http.Controller. Again, we are working with a familiar, but distinct library.

Of particular note, however, are the default method names (the example above is what is created as part of the default VS 2012 project template). Again, without specifying a specific method using an {action} route parameter, the Web API framework determines the appropriate route based on the HTTP verb of the incoming request, and calls the proper method accordingly.

The following incoming URL, included as part of an HTTP GET message, would map to the first Get() method as defined in the controller above:

Example URL With No ID Parameter

http://mydomain/values/

Similarly, this URL, also as part of an HTTP GET request, would map to the second Get(id) method:

Example URL Including ID Parameter

http://mydomain/values/5

We could, however, modify our controller thusly, and the routing would still work without modification:

Modifications to the ValuesController Class:

// GET api/values
public IEnumerable<string> GetValues()
{
returnnewstring[] { "value1", "value2" };
}
// GET api/values/5
publicstring GetValue(int id)
{
return"value";
}
// POST api/values
publicvoid PostValue([FromBody]Book value)
{
}
// PUT api/values/5
publicvoid PutValue(int id, [FromBody]stringvalue)
{
}
// DELETE api/values/5
publicvoid DeleteValue(int id)
{
}

Note that we retained the HTTP action verb as a prefix to all of our method names. Under these circumstances, the unmodified route parameter will still work just fine. When per convention, no {action} route parameter is specified, the Web API framework again appends the "Controller" suffix to the value provided for the {controller} parameter, and then scans the project for a suitably named class (in this case, one which derives from ApiController).

Action Method Selection

---

Once the proper controller class is selected, the framework examines the HTTP action verb of the request, and searches the class for method names with a matching prefix.

In order to determine the proper method, the framework then examines the additional URL parameters and attempts to match them with method arguments by name (case insensitive). The method with the most matching arguments will be selected.

An item to note here. Unlike in MVC, in Web API complex types are not allowed as part of the URL. Complex types must be placed in the body of the HTTP message. Also, there can be one, and only one such complex type in the message body.

In evaluating parameter matches against method arguments, any complex types and URL query strings are disregarded when searching for a match.

Web API and Action Naming

---

We can modify our default Web API route to include an {action} route parameter, in which case selection will occur similar to that in MVC. However, action methods defined on our controller still need to include the proper HTTP action verb prefix, and incoming URLs must use the full method name.

If we modify our default route thusly, adding an {action} parameter:

The Modified WebApiConfig Class and MapHttpRoute Method:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
namespace StandardWebApiTemplateProject
{
publicstaticclass WebApiConfig
    {
publicstaticvoid Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{action}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

To see how this works, consider the incoming URL:

http://mydomain/values/5

This will no longer work. If we wish to make a request of our modified ValuesController now, we would need to submit:

http://mydomain/values/GetValue/5

Review of the Basics for Web API Routing

---

• The routing convention for Web API is to route URLs to a controller, and then to the action which matches the HTTP verb of the request message. Action methods on the controller must either match the HTTP action verb, or at least include the action verb as a prefix for the method name.
• The default route template for a Web API Project is {controller}/{id} where the {id} parameter is optional.
• Web API route templates may optionally include an {action} parameter. However, the action methods defined on the controller must be named with the proper HTTP action verb as a prefix in order for the routing to work.
• In matching incoming HTTP messages to controllers, the Web API framework identifies the proper controller by appending the literal "Controller" to the value of the {controller} route parameter, then scans the project for a class matching that name.
• Actions are selected from the controller by considering the non-complex route parameters, and matching them by name to the arguments of each method which matches the HTTP verb of the request. The method which matches the most parameters is selected.
• Unlike MVC, URLs in Web API cannot contain complex types. Complex types must be placed in the HTTP message body. There may be one, and only one complex type in the body of an HTTP message.

That was Pretty Darn Basic. What Next?

---

The above represents a very simple overview of the Web API routing basics, focusing on the default configurations and conventions. In the next post we will examine more advanced routing considerations, and route customization.

Additional Resources

---

• Routing Basics in ASP.NET MVC
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Routing in ASP.NET Web API

Routing is one of the primary aspects of the MVC framework which makes MVC what it is. While that is possibly over-simplifying, the routing framework is where the MVC philosophy of "convention over configuration" is readily apparent.

Routing also represents one of the more potentially confounding aspects of MVC. Once we move beyond the basics, as our applications become more complex, it generally becomes necessary to customize our routes beyond the simple flexible default MVC route.

Image by ~uminotorino  Some rights reserved

Route customization is a complex topic. In this article we will look at some of the basic ways we can modify the conventional MVC routing mechanism to suit the needs of an application which requires more flexibility.

NOTE: most of the examples in this post are somewhat contrived, and arbitrary. My goal is to demonstrate some basic route customization options without getting distracted by the business case-specifics under which they might be required. I recognize that in the real world, the examples may or may not represent reasonable cases for customized routes.

• A Word about Route Matching Order
• Modifying the URL Pattern
• Modifying Route Default Options
• A Contrived Example
• Adding Route Constraints
• Regular Expressions in Route Constraints
• Notes and Resources on Regular Expressions
• Custom Route Constraints Using IRouteConstraint

In any sufficiently complex ASP.NET MVC project, it is likely you will need to add one or more custom routes which either supplement or replace the conventional MVC route. As we learned in Routing Basics in ASP.NET MVC, the default MVC route mapping is:

{controller}/{action}/{id}

This basic convention will handle a surprising number of potential routes. However, often there will be cases where more control is required, either to:

• Route incoming requests to the proper application logic in complex scenarios.
• Allow for well-structured URLs which reflect the structure of our site.
• Create URL structures that are easy to type, and  "hackable" in the sense that a user, on examining the structure of a current URL, might reasonably make some navigation guesses based on that structure.

Route customization is achieved in a number of ways, usually by by combining modifications to the basic pattern of the route mapping, employing route default options to specify controllers and actions explicitly, and less frequently, using route constraints to limit the ways in which a route will "match" a particular URL segment or parameter.

URLs are Matched Against Routes in Order – The First Match Wins

Incoming URLs are compared to route patters in the order the patters appear in the route dictionary (that is what we added the route maps to in our RouteConfig.cs file). The first route which successfully matches a controller, action, and action parameters to either the parameters in the URL or the defaults defined as part of the route map will call into the specified controller and action. This is important, and requires us to think our routes through carefully so that the wrong handler is not called inadvertently.

The basic process of route matching was covered in Routing Basics in ASP.NET MVC.

Modifying the URL Pattern

As we learned previously, in an MVC application, routes define patterns by which incoming URLs are matched to specific controllers, and actions (methods) on those controllers. Route mappings recognize URLs as a pattern of segments separated (or delimited) by a slash (/) character. Each segment may contain various combinations of  literals (text values) and parameter placeholders. Parameter placeholders are identified in a route definition by braces.

MVC recognizes the special parameter placeholders {controller} and {action} and uses these to locate the appropriate controller and method to call in response to an incoming URL. In addition to these two special placeholders, we can add just about anything to a route as a parameter placeholder to suit our purpose, so long as we adhere to good URL design principles, and of course, reasonably expect the parameter to be useful.

We are familiar with the default MVC pattern shown above. We can see that the route is composed of three segments, with no literals, and parameter placeholders for the special parameters {controller} and {action}, as well as an additional parameter called {id}.

When creating route URL patterns, we can combine literals with parameter placeholders in any number of ways, so long as parameter placeholders are always separated by either a delimiter, or at least one literal character. The following are examples of valid route patterns (whether they are sensible or not is another issue):

Examples of Valid Route Patterns in ASP.NET MVC:

The following pattern is not valid, because the {controller} parameter placeholder and the {action} parameter placeholder are not separated by either a slash (/) or another literal character. In this case, the MVC framework has no way to know where one parameter ends, and the next begins (assume the controller is named "People" and the action is "Show'):

Not all of the valid route examples above include either the {controller} parameter placeholder or the {action} parameter placeholder. The last example does not include either. Also, most include user-defined parameters, such as {username} or {country}. We'll take a look at both in the next two sections.

Modifying Route Default Options

In conjunction with modifying the route URL pattern, we can also take advantage of the route defaults to create routes which are more specific, and in some cases which map only to a specific controller and/or action.

The standard MVC project file contains the route mapping configuration in a file named RouteConfig.cs:

The standard MVC RouteConfig.cs File:

publicclass RouteConfig
{
publicstaticvoid RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
        routes.MapRoute(
            name: "Default",
            url: "{controller}/{action}/{id}",
            defaults: new { 
                controller = "Home", 
                action = "Index", 
                id = UrlParameter.Optional }
        );
    }
}

The route above establishes a default value for both the controller and the action, in case one more both are not provided as part of an incoming URL.

We can take this a step further, and add a new, more specific route which, when it matches a specific URL pattern, calls into one specific controller. In the following, we have added a new route mapping in our RouteConfig.cs file:

Adding a More Restrictive Route:

publicstaticvoid RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
// ALL THE PROPERTIES:
// rentalProperties/
    routes.MapRoute(
        name: "Properties",
        url: "RentalProperties/{action}/{id}",
        defaults: new
        {
            controller = "RentalProperty",
            action = "All",
            id = UrlParameter.Optional
        }
    );
    routes.MapRoute(
        name: "Default",
        url: "{controller}/{action}/{id}",
        defaults: new { 
            controller = "Home", 
            action = "Index", 
            id = UrlParameter.Optional }
    );
}

First off, take note that we have added the new, more specific route before the default in the file (which determines the order it is added to the route dictionary). This is because routes are evaluated for a match to an incoming URL in order. The default MVC route a pretty general, and if route order is not carefully considered when adding additional routes to your project, the default route may inadvertently match a URL intended for a different handler.

Beyond this, what we see in the new route added above is that there is no {controller} parameter placeholder in the URL pattern of the "Properties" route. Since no controller can be passed to this route as a parameter, it will always map to the RentalPropertiesController , and to whichever Action is provided as a parameter. Since there is a default action defined, if the incoming URL matches the route but does not contain an Action parameter, the default All() method will be called.

A Contrived Example

So far, in this rather contrived example, we haven't accomplished anything we couldn't have done using the default MVC route pattern. However, suppose in our application we wanted to define the following URL patterns and associated URL examples for accessing views in a property management application:

Desired URL patterns for Simple Property Management Application:

We could define a RentalPropertyController class as follows:

Rental Property Controller Example:

publicclass RentalPropertiesController : Controller
{
private RentalPropertyTestData _data = new RentalPropertyTestData();
// List all the properties
public ActionResult All()
    {
        var allRentalProperties = _data.RentalProperties;
return View(allRentalProperties);
    }
// get a specific property, display details and list all units:
public ActionResult RentalProperty(string rentalPropertyName)
    {
        var rentalProperty = _data.RentalProperties.Find(a => a.Name == rentalPropertyName);
return View(rentalProperty);
    }
// get a specific unit at a specific property:
public ActionResult Unit(string rentalPropertyName, string unitNo)
    {
        var unit = _data.Units.Find(u => u.RentalProperty.Name == rentalPropertyName);
return View(unit);
    }
}

Given the above controller, and the desired URL patterns in the previous table, we can see that the default MVC route mapping would work for some, but not all of our URLs. We might be better served by adding the following controller-and-action-specific routes to our application, so that our RouteConfig.cs file looks like this:

Modified Route Config File for Property Management Example Application:

publicstaticvoid RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
// RentalProperties/Boardwalk/Units/4A
    routes.MapRoute(
        name: "RentalPropertyUnit",
        url: "RentalProperties/{rentalPropertyName}/Units/{unitNo}",
        defaults: new
        {
            controller = "RentalProperties",
            action = "Unit",
        }
    );
// RentalProperties/Boardwalk
    routes.MapRoute(
        name: "RentalProperty",
        url: "RentalProperties/{rentalPropertyName}",
        defaults: new
        {
            controller = "RentalProperties",
            action = "RentalProperty",
        }
    );
// RentalProperties/
    routes.MapRoute(
        name: "RentalProperties",
        url: "RentalProperties",
        defaults: new
        {
            controller = "RentalProperties",
            action = "All",
            id = UrlParameter.Optional
        }
    );
    routes.MapRoute(
        name: "Default",
        url: "{controller}/{action}/{id}",
        defaults: new
        {
            controller = "Home",
            action = "Index",
            id = UrlParameter.Optional
        }
    );
}

As we see now, all of the newly added routes explicitly specify both the controller and action, and allow for our progressively enhanced URL structure which includes the property name as part of the URL.

Of course, in the real world, this URL scheme would likely not work the way we desire, because (depending upon how our database is going to be used) the names of rental properties may not be unique, even within a given management company. If the company operated rental properties in several states or even counties within a state, it is entirely possible that there would be more than one property named (for example) "Maple Glen." It is a sad fact that despite all the wonderfully simple examples we can find while learning, the real world often fails to model in the way we want.

Adding Route Constraints

Route constraints can be used to further restrict the URLs that can be considered a match for a specific route. While we have so far examined whether routes match based upon URL structure and parameter names, Route Constraints allow us to add some additional specificity.

The MVC framework recognizes two types of constraints, either a string, or a class which implements the interface IRouteConstraint.

Regular Expressions in Route Constraints

When a string is provided as a constraint, the MVC framework interprets the string as a Regular Expression, which can be employed to limit the ways a URL might match a particular route. A common scenario in this regard would be to restrict the value of a  route parameter to numeric values.

Consider the following route mapping:

Example Route Mapping for Blog Application with no Constraint:

routes.MapRoute(
    name: "BlogPost",
    url: "blog/posts/{postId}",
    defaults: new
    {
        controller = "Posts",
        action = "GetPost",
    }, 
);

This route will call into the PostsController of a hypothetical blog application and retrieve a specific post, based on the unique postId. This route will properly match the following URL:

http://domain/blog/posts/123

Unfortunately, if will also match this:

http://domain/blog/posts/gimme

The basic Route Constraint allows us to test the value of the {postId} parameter to determine if it is a numeric value. We can re-write our route mapping thusly:

Example Route Mapping for Blog Application with Added Constraint:

routes.MapRoute(
    name: "BlogPost",
    url: "blog/posts/{postId}",
    defaults: new
    {
        controller = "Posts",
        action = "GetPost",
    }, 
new {postId = @"\d+" }
);

The tiny Regular Expression @"\d+ in the code above basically limits the matches for this route to URLs in which the postId parameter contains one or more digits. In other words, nothing but integers, please.

I'm not going to dig too deep into Regular Expressions here. Suffice it to say that Regular Expressions can be used to great effect in developing a complex routing scheme for your application.

A Note and More Resources for Regular Expressions

Regular Expressions are a powerful tool, and also a giant pain the the ass. As Jamie Zawinskie said, "Some people, when confronted with a problem, think 'I know, I'll use regular expressions.' Now they have two problems." However, Regular Expressions are sometimes the very best tool for the job – restricting route matches in an MVC application is one of those cases. I find three tools most helpful when writing more complex regular expressions. In order of importance:

• Google (doh!)
• Expresso Regular Expression Development Tool (older, but invaluable)
• The site Regular-Expressions.info (More than you ever wanted to know)

Custom Route Constraints using IRouteConstraint

The other option for using route constraints is to create a class which implements the IRouteConstraint interface.

We'll take a quick look at a custom route constraint which can be used to make sure a particular controller is excluded as a match for our default MVC route.

Note: The following code was adapted from a code project article by Vijaya Anand (Code Project member After2050), originally posted at his personal blog Proud Parrot.

In creating a custom constraint, we first create a new class which implements IRouteConstraint. IRouteConstraint defines a single method, Match for which we need to provide the implementation. In order for the constraint to work, we will also need to create a constructor with which we set the argument(s) required for the method:

The Custom Constraint Class ExcludeController:

publicclass ExcludeController : IRouteConstraint
{
privatereadonlystring _controller;
public ExcludeController(string controller)
    {
        _controller = controller;
    }
publicbool Match(HttpContextBase httpContext,
        Route route, string parameterName,
        RouteValueDictionary values,
        RouteDirection routeDirection)
    {
// Does the _controller argument match the controller value in the route
// dictionary for the current request?
returnstring.Equals(values["controller"].ToString(),
            _controller, StringComparison.OrdinalIgnoreCase);
    }
}

Now, suppose we have a hypothetical controller ConfigurationController for which we have defined a special route which requires authentication. We don't want the MVC default route map to inadvertently allow access to the Configuration controller for unauthenticated users. We can make sure of this by modifying our default MVC route like so:

Adding a Custom Constraint to the Default MVC Route:

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

Now, if a URL which has not been matched by any previous route mapping is evaluated for a match with our default route, the MVC framework will call the Match method of our custom constraint ExcludeController. In the case above, if the URL contains the {controller} parameter with a value of "Configuration" the Match method will return a value of false, causing the route to reject the URL as a match.

Stephen Walther presents an excellent tutorial on Custom Route Constraints, and specifically, creating a authentication constraint at his blog in ASP.NET MVC Tip #30 – Create Custom Route Constraints.

8/23/2013 – UPDATE: I forgot to mention that Attribute Routing is an alternative routing model which allows you to specify routes directly on the controller action handler for a specific URL pattern. You can use Attribute Routing now as a Nuget package, but it is actually going to be an integrated option shipped with the upcoming release of ASP.NET 5 and Web Api 2. There is some debate as to whether Attribute Routing is a good thing, as evidenced by K. Scott Allen's recent post on OdeToCode. In this article I keep the focus on customization of the standard routing mechanism in ASP.NET.

Additional Resources

• Routing Basics in ASP.NET MVC
• Routing Basics in ASP.NET Web API
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Deploying an Azure Website from Source Control
• Webmatrix 3: Integrated Git and Deployment to Azure

Recently I needed to set up an ASP.NET MVC project to work with a SQL CE database. I also needed to use SQL CE as the backing store for the ASP.NET Membership feature. This was a simple, quick-and-dirty project for work, and the database requirements were very, very simple. I wanted to use SQL CE for all the data, and also use SQL CE for the membership function so that everything was nicely buttoned up within my site.

Turns out it was not 100% intuitive to make this work, but here is how I did it.

Image by Infocux Technologies | Some Rights Reserved

• Get the ASP.NET Provider via Nuget
• Configure the Profile, Membership, and Role Providers in Web.config
• Run the Project, and a SQL CE Membership Database will be Created
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project

Why Use SQL CE?

---

SQL CE is a great choice for applications which are not data-intensive, and/or for which deployment with minimal or no external dependencies is important. SQL CE is an embedded database, and includes all required runtime dependencies within the application. In other words, no need to install and configure SQL Server or SQL Express.

SQL CE was an ideal choice for my little work project, for which storage requirements were minimal, but for which I needed some level of membership/authorization. Once I had the configuration described below in place, development and (especially) deployment were a breeze, with no SQL Server configuration hassle.

The default configuration is for SQL Server Express

---

Out of the box, an ASP.NET MVC Project is configured to use SQL Server Express as the membership provider. If you do File –> New Project and choose an MVC 4 project type, your  Web.config file will contain a <connectionStrings> element that looks something like this:

<connectionStrings>
<addname="DefaultConnection"
connectionString="Data Source=(LocalDb)\v11.0;Initial 
     Catalog=aspnet-ConfigureAspNetforSQLCeMembershipDb-20131006163451;Integrated 
     Security=SSPI;AttachDBFilename=|DataDirectory|\aspnet-YourProject-20131006163451.mdf"
providerName="System.Data.SqlClient"/>
</connectionStrings>

If you run the out-of-the-box site and "register", a YourProject.mdf file and an accompanying .log file will be created in the App_Data folder in the VS solution.

If we want to use SQL CE instead of SQL Server Express, we need to change some things up.

Get the Microsoft.AspNet.Providers.SqlCe Package using Nuget

---

First off, we need to install the Microsoft Universal Provider for SQL CE. There is a handy Nuget package for doing just this. We can either open the Nuget Package Manager Console and do:

Install Microsoft.AspNet.Providers.SqlCE from the Package Manager Console:

PM> Install-Package Microsoft.AspNet.Providers.SqlCE

Or, we can go to the Solution Explorer, right-click on the solution, and select "Manage Nuget Packages for Solution. Then, select "Online" from the left-hand menu, and type Microsoft.AspNet.Providers.SqlCe in the search box:

Install Microsoft.AspNet.Providers.SqlCE from the Package Manager Console:

One you have done this, there will now be an extra entry in the <connectionStrings> element of your Web.config file:

Extra DefaultConnection in Web.config File:

<connectionStrings>
<addname="DefaultConnection"
connectionString="Data Source=(LocalDb)\v11.0;Initial 
     Catalog=aspnet-YourProject-20131006170652;Integrated 
     Security=SSPI;AttachDBFilename=|DataDirectory|\aspnet-YourProject-20131006170652.mdf"
providerName="System.Data.SqlClient"/>
<addname="DefaultConnection"
connectionString="Data Source=|DataDirectory|\aspnet.sdf"
providerName="System.Data.SqlServerCe.4.0"/>
</connectionStrings>

The new <add name= "DefaultConnection" . . . > node was added for us when we installed the SqlCe provider package. This will now conflict with the previous entry, so delete the original (where providerName = "System.Data.SqlClient" ).

That was easy. But we're not done yet.

Configure the Profile, Membership, and Role Providers in Web.config

---

In order for SQL CE to work as the back-end store for the membership features of our MVC site, we need to do some tuning on the Profile providers section of our Web.config file as well. If you scroll down from the connectionStrings section, you will find the Profile, Membership, and Role nodes, which looks something like this:

Default Profile, Membership, and Role Provider Configuration in Web.config:

<profiledefaultProvider="DefaultProfileProvider">
<providers>
<addname="DefaultProfileProvider"type="System.Web.Providers.DefaultProfileProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"connectionStringName="DefaultConnection"applicationName="/"/>
</providers>
</profile>
<membershipdefaultProvider="DefaultMembershipProvider">
<providers>
<addname="DefaultMembershipProvider"type="System.Web.Providers.DefaultMembershipProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"connectionStringName="DefaultConnection"enablePasswordRetrieval="false"enablePasswordReset="true"requiresQuestionAndAnswer="false"requiresUniqueEmail="false"maxInvalidPasswordAttempts="5"minRequiredPasswordLength="6"minRequiredNonalphanumericCharacters="0"passwordAttemptWindow="10"applicationName="/"/>
</providers>
</membership>
<roleManagerdefaultProvider="DefaultRoleProvider">
<providers>
<addname="DefaultRoleProvider"type="System.Web.Providers.DefaultRoleProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"connectionStringName="DefaultConnection"applicationName="/"/>
</providers>
</roleManager>

In order to use SQL CE for our Membership provider, we need to replace the above with the following:

Modified Profile, Membership, and Role Provider Configuration in Web.config:

<profiledefaultProvider="DefaultProfileProvider">
<providers>
<clear/>
<addname="SimpleRoleProvider"type="WebMatrix.WebData.SimpleRoleProvider, WebMatrix.WebData"/>
</providers>
</profile>
<membershipdefaultProvider="SimpleMembershipProvider">
<providers>
<clear/>
<addname="SimpleMembershipProvider"type="WebMatrix.WebData.SimpleMembershipProvider, WebMatrix.WebData"/>
</providers>
</membership>
<roleManagerenabled="true"defaultProvider="SimpleRoleProvider">
<providers>
<clear/>
<addname="SimpleRoleProvider"type="WebMatrix.WebData.SimpleRoleProvider, WebMatrix.WebData"/>
</providers>
</roleManager>

Once this is done, go to the App_Data folder, and if you originally ran the project and created a SQL Express Database (.mdf and .ldf files), delete those.

Run the Project, and a SQL CE Membership Database will be Created

---

In theory, that should be it. Once you run the project again, an .sdf file will be created in your App_Data folder and you should be off an running.

In reality, I had to do some fussing around. If you are using IIS Express for running your application in VS (this is the default), you may need to go to the system tray and Exit IIS Express, or at least stop the site, before you run again.

If you have any other issues, please feel free to let me know in the comments section. I really want to provide complete information here, even for simple things like this.

Other Resources

---

If you are newer to ASP.NET MVC, you might find some of the following helpful:

• Customizing Routes in ASP.NET MVC
• Routing Basics in ASP.NET MVC
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4

Entity Framework's "Code-First" development model has become a highly popular approach to data modeling in ASP.NET MVC development in the last few years. The Code First approach saves the average developer the perceived pain of working with SQL, and also minimizes the amount of repetitive, "boiler plate" code we need to write as part of a more traditional data access layer.

However, quite frequently we will need to develop against an existing database, the schema of which may or may not be open for modification.

Image by Ian Britton | Some Rights Reserved

• Create an ADO.NET Entity Data Model
• Add Functionality to Generated Classes with Partial Classes
• Adding Metadata Annotations to Generated Classes using Partial Classes
• Updating the Model to Reflect Changes in the Underlying Database
• Why Model or Database First?
• Additional Resources and Items of Interest

While it is possible to reverse-engineer an existing database and then switch to a code-first approach once the models have been created, for various reasons this approach may be impossible or impractical. In certain cases we must start with a pre-defined database schema and/or allow database changes to drive our model instead of the other way around. In this post we will take a quick look at how to reverse engineer an existing database to create your conceptual data model.

Within the context of an ASP.NET MVC application, we may find ourselves looking at the Database or Model First approach in a number of different situations, including:

• Creating a new front end against an existing database
• An organizational or DBA philosophy driven by the modeling the database first
• Personal developer preference – some of us simply prefer to model the data first.

For Our Examples: The Database . . . First . . .

---

Under the premise that we must (for whatever reason) build out our application around an existing database, we will create an extremely complex SQL Server database and pretend it is what we have been given by the powers that be:

Example Database:

As you can see, we have a complicated database with two related tables. Now, let's look at an example ASP.NET MVC project, into which we will reverse engineer this database to create our model classes and database context.

Create an ADO.NET Entity Data Model

---

In a standard ASP.NET project, we should find a pre-defined Models folder, in which there will (usually) already be an Account Model related to ASP.NET Forms Membership. Right-click on the Models folder in the VS Solution Explorer and select Add => ADO.NET Entity Data Model:

Adding an ADO.NET Entity Data Model:

After you do this, you will be prompted to provide a name for the data model you are about to create. The convention is something along the lines of "<ProjectName>Entities." In this case, I chose "ExampleEntities" and then proceed to the next step, where we are asked to choose what the model should contain. Obviously, we want to select "Generate from database" here, and then select Next in the Wizard.

In the next window, we are asked to choose a connection:

Choose Your Data Connection (or create a New One):

Obviously, our database is not called "ChinookDb.sdf" as seen in the picture above, and  in fact we probably don't already have our database available as an existing connection, so we need to click the "New Connection" button and create one. Once that's done, you will notice the wizard automatically determined an appropriate name (in my case, "ExampleDbEntities" for our connection string in Web.config. You can change this if you like, but I recommend using the default for consistency. Hit "Next."

In the next window, we are asked to select the database objects we wish to include in our model. For our simple database (and in most cases) we just want the tables. In my case, there is an extra table "sysDiagrams" that is NOT part of our domain model. In your own project, select the tables which make sense as part of your model domain. The other default settings in this window are usually appropriate as well:

Select the Database Objects:

Now, hit "Finish."

VS will take a few seconds to reverse engineer your database, and when finished, will present you with a diagram of the conceptual model of your database. As you can see, VS made fast work of our extremely complex data model:

The EDMX Diagram for ExampleEntities:

We can find our generated model classes in Solution Explorer under Models => ExampleEntities => ExampleEntities.tt:

The New Model Classes in VS Solution Explorer:

Add Functionality to Generated Classes with Partial Classes

---

Now that we have our model classes, it may often be the case we need to add functionality to them to suit the requirements of our program. Under the model-first or Database First approach, there are some things to be aware of here. These classes are generated, and can be automagically updated to reflect changes in the underlying database. If and when you do this, they will be re-written, and any code you may have added will be gone. Therefore, when you need to add additional properties or methods to one of these classes, use partial classes and add them in the Models folder.

For a contrived example, let's say we absolutely needed a CountOfAlbums property defined on our Artist class. We COULD open up our Artist class and simply add a new method like so:

Modifying the Artist Class in the Generated File:

//------------------------------------------------------------------------------
// <auto-generated>
//    This code was generated from a template.
//
//    Manual changes to this file may cause unexpected behavior in your application.
//    Manual changes to this file will be overwritten if the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------
namespace AzureModelFirstExample.Models
{
using System;
using System.Collections.Generic;
public partial class Artist
    {
public Artist()
        {
this.Albums = new HashSet<Album>();
        }
publicint Id { get; set; }
publicstring Artist1 { get; set; }
publicvirtual ICollection<Album> Albums { get; set; }
// THIS IS OUR NEW METHOD:
publicint CountAlbums
        {
get
            {
returnthis.Albums.Count;
            }
        }
    }
}

However, if later we were to have EF update our model to reflect changes in the underlying database schema (We'll look at this in a moment), this addition would be over-written. A better approach would be to add a new class file named ArtistPartial to our Models folder. Once we have done this by right-clicking in Solution Explorer => Add => Class . . . , we get a code file which looks like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
namespace AzureModelFirstExample.Models
{
publicclass ArtistPartial
    {
    }
}

Now, we will leave the actual code file name as ArtistPartial.cs, but we can replace the class declaration using the partial keyword and the class name Artist to match our generated model class. Then we can put our custom property in this file:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
namespace AzureModelFirstExample.Models
{
public partial class Artist
    {
// THIS IS OUR NEW METHOD:
publicint CountAlbums
        {
get
            {
returnthis.Albums.Count;
            }
        }
    }
}

Now, we can simply add the partial keyword to the class declaration for our EF-generated Artist model class (which we may need to do again if we regenerate the code as well, but it is easier to deal with than re-writing one or more potentially complex properties or methods . . .):

//------------------------------------------------------------------------------
// <auto-generated>
//    This code was generated from a template.
//
//    Manual changes to this file may cause unexpected behavior in your application.
//    Manual changes to this file will be overwritten if the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------
namespace AzureModelFirstExample.Models
{
using System;
using System.Collections.Generic;
public partial class Artist
    {
public Artist()
        {
this.Albums = new HashSet<Album>();
        }
publicint Id { get; set; }
publicstring Artist1 { get; set; }
publicvirtual ICollection<Album> Albums { get; set; }
    }
}

Adding MetaData Annotations to Generated Classes using Partial Classes

---

ASP.NET MVC provides some powerful and time-saving validation and other features which rely on Data Annotations facilitated in System.ComponentModel.DataAnnotations. Important attribute decorations for our model classes such as [Required] and [DisplayName] allow us to let the MVC framework and JQuery provide basic data entry validations for our site right out of the box.

As generated, our simple model classes don't know anything about whether (for example) NULL values are allowed in the database. If we want to take advantage of MVC's out-of-the-box validation and other helpers with our generated classes, we need to find a way to implement the data annotations and other metadata attributes. As before, if we implement these annotations directly in the generated Artist (or any other EF-generated) code file, they would again be over-written any time the model is updated. However, we can do this in our partial class, and thus preserve our validations through successive model updates throughout the development process. As an example, we know that:

• The Artist1 property of our Artist class is required, as in our database null values are not allowed (and we ALL KNOW that an empty string is NOT THE SAME AS NULL . . . RIGHT??).
• Artist1 is a terrible name for what should be the "Name" property of the artist. However, in our database. we would like to be able to give this a [Display] name attribute so that in our views, MVC will use a more appropriate label (such as "Name" or simply "Artist").

We can achieve both objectives by adding the following to our ArtistPartial code file:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
// This must be added to our using statements:
using System.ComponentModel.DataAnnotations;
namespace AzureModelFirstExample.Models
{
// We have added a class-level MetaData attribute here:
    [MetadataType(typeof(ArtistMetadata))]
public partial class Artist
    {
// THIS IS OUR NEW METHOD:
publicint CountAlbums
        {
get
            {
returnthis.Albums.Count;
            }
        }
    }
// We have defined and ArtistMetaData class which defines the 
// meta-data attributes for various properties on the artist class:
publicclass ArtistMetadata
    {
        [Required]
        [Display(Name = "Artist Id")]
publicstring Id { get; set; }
        [Required]
        [Display(Name = "Name")]
publicstring Artist1 { get; set; }
    }
}

Make sure to add the using System.ComponentModel.DataAnnotations to your using statements for the above to work properly.

As you can see, we added a new ArtistMetaData class to our ArtistPartial.cs code file, and defined the data annotations we wanted for each of the properties. To me, the one of greatest import is the [Required] attribute, which allows the MVC framework to perform JQuery validations right from the start.

When we work under a code-first development model, we would define these and other attributes on our classes, and EF would use this metadata while creating our database. In Model/Database first development, we need to decorate our classes manually. Doing this using partial classes allows us to preserve the annotations through successive automated updates to the model.

Updating the Model to Reflect Changes in the Underlying Database

---

Imagine the harsh, cruel DBA (aren't they all? – kidding, of course) at our company informs us that he has added a new table, RecordLabels to the database, and created a foreign key on the Albums table to reflect the label for each particular album.

No big deal, Entity Framework has us covered, right?

We can simply open our EDMX diagram, right-click anywhere in the viewing area, and select "Update model from database . . ." :

Updating the Model to Reflect Changes in the Database Schema:

Once we select this option, we see a familiar window. However, there are some differences. Once again, we will select the new tables to add. Again in my case sysDiagrams appears as an option, as well as the new RecordLabels table our cruel DBA added. We only want to select the RecordLabels table to add:

Select the RecordLabels Table to Add to the EF Model:

This time, however, we also see a tab named "Refresh." Here we find any database objects which have been changed since the last model update. In our case, we  have added a foreign key to the Albums table. In my specific case, the Artist table also appears, because I modified a few things in the course of preparing these examples.

Database Objects Modified Since the Last Model Update:

Once we click the "Finish" button, VS will again take a moment to regenerate our model classes. Once we Rebuild the project, we find that we now have the new model class RecordLabel in our ExampleEntities.tt file. Further, if we open our Album class we see that EF has now added a LabelId field, and a RecordLabel class as a property.

Last, since we carefully defined any additional methods required for our classes, along with relevant meta-data annotations, in respective partial class files for each of our model classes, our custom code for each class is untouched. We may need to modify it to reflect some of the changes (for example, we have added a LabelId field to the Album class, which likely should be non-nullable in the database and hence [Required] in our model.

We may need to go back through and add the partial keyword to some of our classes, although in some cases EF can figure out that it needs this as well.

Also, we should probably create a similar partial class file for our new RecordLabel class, and add what annotations and additional code make sense. 

Why Model or Database First?

---

The Entity Framework Code-First approach seems to be the new shiny thing for use in developing database applications. From a strictly developer standpoint, the Code First approach may be attractive in that:

• We can (to an extent) allow our database to be modeled upon our object domain, and we get to work and think in the familiar Object-Oriented realm we understand the best;
• Changes to the underlying data base structure can be propagated automatically as our code evolves
• We don't have to deal directly with SQL (for some, this is a strangely big deal).

However, there are plenty of times when the Code First approach is either not an option (remember the cruel DBA with the existing database we are required to use?), or when as a matter of preference we choose to work with the data model first, and build our code on top of that. In these situations, it is important to recognize the small but significant differences between the two approaches, and build out our application accordingly.

Additional Resources and Items of Interest

---

• ASP.NET MVC– Azure Websites and EF Model-First Connection Strings when Deploying from Github
• Customizing Routes in ASP.NET MVC
• Routing Basics in ASP.NET MVC
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Deploying an Azure Website from Source Control
• Deploying an Azure Website from Source ControlJohn on GoogleCodeProject

One of the coolest things about Windows Azure Websites is the integration with source control, and the automated deployment hooks Azure offers. However, there are a number of small gotcha's related to deployment, chief among these is the protection of confidential configuration items such as database connection string.

In this post, we are going to look specifically at the vexing situation I ran into deploying from source control with an application using Entity Framework's "Model-First" strategy (everything here is pretty much applicable to "Database-First" as well, since in terms of the conceptual modeling of the database within the application, they are the same).

Image by Hammad Ali | Some Rights Reserved

NOTE: If you are an MSDN Subscriber, you can access free Azure benefits. If you are not an MSDN subscriber, you can still have up to 10 Windows Azure Websites for free. Additionally, anyone can take advantage of an introductory free 30 day trial to check out the rest of the Azure platform.

If you wish to take advantage of Windows Azure Websites Deployment from Source Control feature, and your application uses Entity Framework's Model-or-Database-First approach, there are some non-intuitive set-up concerns that need to be addressed before your deployment will work properly.

• Windows Azure Databases, Website Deployment, and Connection Strings
• The Model-First Connection String Pattern for Windows Azure
• Filling in the Example Azure Connection String Settings
• Troubleshooting
• Azure EF Model-First Connection String Pattern on Github
• Deploying an Azure Website from Source Control

EF Model-First Connection String Meta-Data

---

When you use Entity Framework to either build a database based upon the model you create in the VS Entity Designer, or use EF to reverse-engineer a conceptual model from an existing database, EF creates a bunch of meta-data mappings used to manage the interaction of your application with the database.

Unlike the "Code-First" approach, in which much of the meta-data exists as annotations on your model classes which EF then uses to create and map the relations of your classes to the database, the Model-First paradigm leaves you with straight POCO ("Plain Old CLR Objects" or, alternately, "Plain Old Class Objects") classes.

In order for EF (and thus, your application) to work properly in a Model-First approach, it needs to know where all this meta-data lives, and this is evident in the connection string created by EF in your Web.config file:

EF Model First Connection Strings in Web.config:

<connectionStrings>
<addname="DefaultConnection"
connectionString="Data Source=(LocalDb)\v11.0;
    Initial Catalog=aspnet-AzureModelFirstExample-20131020060646;
    Integrated Security=SSPI;
    AttachDBFilename=|DataDirectory|\aspnet-AzureModelFirstExample-20131020060646.mdf"
providerName="System.Data.SqlClient"/>
<addname="ExampleDbEntities"
connectionString="metadata=res://*/Models.ExampleEntities.csdl
     |res://*/Models.ExampleEntities.ssdl|res://*/Models.ExampleEntities.msl;
     provider=System.Data.SqlClient;
     provider connection string=&quot;data source=XIVMAIN\XIVSQL;
     initial catalog=ExampleDb;integrated security=True;
     MultipleActiveResultSets=True;App=EntityFramework&quot;"
providerName="System.Data.EntityClient"/>
</connectionStrings>

In the above, the first XML node in <connectionStrings> , named "DefaultConnection" is the connection string for the standard Forms Membership feature included out of the box with the default MVC project template.

The second node, for the connection string named "ExampleDbEntities" is what you get when you create an Entity Framework Model First implementation of the actual domain database your application will consume. All that metadata=res: stuff essentially tells EF where to find the meta data it needs to properly relate your generated model classes to database tables, and to keep track of the relationships between them.

In the example above, the membership database exists in the App_Data folder of the project. The ExampleEntities database is hosted on my local development server. As a result, both connections are able to use Windows Integrated Security, and no confidential connection information is persisted in the Web.config file. 

When deploying a website to Windows Azure Websites, there are any number of variations with respect to how the two-database application above might be implemented. You might create a separate membership database on your Azure account, as well as an application database, similar to the above.

More likely, you might decide to combine the two such that all of your application data is served by the same Azure SQL Database instance. For this article, we are going to look at the free Websites tier, which allows one free Azure SQL Database (<= 20 Mb) for use by all of your free websites. We will also assume that you must (for whatever reason) develop your application against an existing database schema, such that the Model/Database First approach is indicated.

Windows Azure Databases, Website Deployment, and Connection Strings

---

In the configuration section of the Azure Website Management Portal, there is a section specifically for setting up connection strings. Azure connection strings are key/value pairs where the NAME field (the Key) is the name of the connection string as defined in our Web.config file, and the VALUE represents the actual connection string to be used to connect to our Azure SQL Database instance.

Connection String Management in the Windows Azure Websites Portal

The above is from the Configuration portal for an example I set up. I have an existing Azure SQL Database set up, and when I created the example site, the DefaultConnection string called out in red was associated with that database.

When we deploy our site from source control, Azure maps the connection string names defined in our Web.config file to the correspondingly-named connection strings defined here. This preserves the privacy of our confidential Azure database connection information, since it does not need to be committed to our source control repo.

Recall from the previous section that our Membership database on our local machine also uses a connection string named "DefaultConnection." Since for our example we are presuming that in deployment the Membership tables actually reside in the same database as the rest of our application data, the connection string above is appropriate. Of course, we need to make sure to migrate our Membership tables into this database (or assume they are already there).

In any case, this connection string should point to wherever our membership tables live. As it sits currently, the DefaultConnection is a standard Azure SQL Database connection. If we click on the "Show Connection Strings" link, we see that with a few small exceptions, the Azure connection string closely resembles a standard SQL Server connection string:

Default Azure Connection String for a Linked Azure SQL Database

Data Source=tcp:yourAzureServerName.database.windows.net,1433;
    Initial Catalog=ModelFirstExampleDb;
    User ID=yourDbUserName@yourAzureServerName;
    Password=YourPassword

This should work properly with the membership functions of our application out of the box, so long as the Membership data resides in the target database to which this connection string points.

Now we come to the issue of our application database. Since our Entity Framework models expect a Model-First implementation, they will be looking for that funky, meta-data-laden second connection string we saw in our Web.config file.

The Model-First Connection String Pattern for Windows Azure

---

In order for Windows Azure to work with our EF Model-First Deployment, we need to set up the second connection string very specifically. First off, we need to name it to match the name defined for our application data connection string in Web.config. Second, we need to use the following pattern, and carefully substitute all of the <angleBracketed> values with our proper values (the angle brackets are not part of the connection string – remove those when putting your own values in):

The Model-First Connection String for Windows Azure SQL Database:

metadata=res://*/Models.<EFModel>.csdl|res://*/Models.<EFModel>.ssdl|res://*/Models.<EFModel>.msl;
provider=System.Data.SqlClient;
provider connection string=
"data source=tcp:<AzureServer>.database.windows.net;
initial catalog=<AzureDatabaseName>;
Persist Security Info=True;
User ID=<UserLogIn>@<AzureServer>;
Password=<UserPassword>"

Obviously, this should actually be a single line, but I have condensed it here as much as was reasonable for readability. You can find the unmodified template at my Github repo.

• The value for <EFModel> is the name of the Entity Framework Model in your project
• The value for <AzureDatabaseName> is obviously, the name of your deployed Azure SQL database.
• When you initially set up your SQL Database, you will have created the values for <UserLogIn> and <UserPassword> . Replace those bracketed items with the values you created with the database.
• To find the value to use for <AzureServer> , navigate to your Azure SQL Database management area in the Azure Portal SQL Databases => Database Name => Dashboard. Replace <AzureServer> with the value from your own configuration called out (but redacted) in red below:

Find the Value for <AzureServer> in SQL Database Dashboard:

Filling in the Example Azure Connection String Settings

---

So, that all seems like a lot to have read just to get to this, but here goes . . . Your DefaultConnection is already defined, and points directly at your Azure SQL Database. Assuming your ASP.NET Membership tables are all defined in your one application database, all we need to do is paste in our EF Model-First connection string, once we have replaced the placeholders with the values for our own SQL Database, and configure the rest of the connection string (again, it is important that the NAME value here match the name defined for this connection in Web.config).

In the case of our initial example from the beginning of this post:

• The NAME is ExampleDbEntities
• The Connection String for the example at the beginning of the post is (Remember this actually needs to be all in a single line, not formatted with line returns like this)::

metadata=res://*/Models.ExampleEntities.csdl|res://*/Models.ExampleEntities.ssdl|res://*/Models.ExampleEntities.msl;
provider=System.Data.SqlClient;
provider connection string=
"data source=tcp:MyAzureServer.database.windows.net;
initial catalog=ModelFirstExampleDb;
Persist Security Info=True;
User ID=MyUserLogin@MyAzureServer;
Password=MySuperSecretPassword"

Lastly, there is a drop-down selector for the provider type. The default is SQL Databases, but for Entity Framework, we want to select the "Custom" option.

If we were configuring the example from the beginning of this post, the configuration settings on the Azure portal would look something like this:

Once you have entered all these values, Click the Save icon at the bottom of the window. \

Troubleshooting

---

There are a lot of places for this to go just slightly wrong, thus borking your connection. For example, if you are developing against a local development database, and it is named slightly different than your Azure SQL Database, your will get an exception if this is not correctly addressed in the Azure Connection string. Also, there are simply a lot of places where a typographical error might creep in when replacing the values in the connection string template with your actual values.

Another area to keep an eye on is that your production database on Azure is identical to your development database. While we are working under the premise that the database is driving our development, it is possible that changes may be introduced to one and not the other.

Unfortunately, when we work in the Model-First approach, we don't get the easy database creation during deployment. Therefore, it is important to keep the database schema's in sync.

Windows Azure offers a number of helpful features in this regard. I will take a closer look at the overall building out data-backed websites on Windows Azure in an upcoming post.

Additional Resources and Items of Interest

---

• Reverse-Engineering an Existing Database in your ASP.NET MVC Application Using Entity Framework Model/Database-First
• Deploying an Azure Website from Source Control
• ASP.NET MVC: Configuring ASP.NET MVC 4 Membership with a SQL CE Database
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• C#: Query Excel and .CSV Files Using LinqToExcel

The recent release of Visual Studio 2013 and ASP.NET MVC 5 brought significant changes to the Accounts management system (formerly ASP.NET Forms Membership). Also, there have been some minor changes in how we manage Entity Framework Code-First Migrations.

In this post we will review setting up the basic Identity accounts, pointing them at an external SQL Server (or whatever other database you choose) instance instead of the default (local) SQL Server CE or SQL Express database in App_Data and configuring Entity Framework Migrations so seed the database with initial data.

Image by Wonderlane | Some Rights Reserved

• Configuring the Database Connection
• Configuring Entity Framework Migrations and Seeding the Database
• Seeding the Database with an Initial User Records
• Extending the IdentityModel Class with Additional Properties
• Updating the Database to Reflect Modified Entity Classes
• Additional Resources and Items of Interest
• Extending Identity Accounts and Implementing Role-Based Authentication in ASP.NET MVC 5

The Basic Components of the ASP.NET Identity System

---

Out of the box, when you create an ASP.NET MVC 5 project using the default template in Visual Studio 2013, your get a basic, ready-to-run website with the elementary Identity and Account management classes already in place. In the current configuration, the default action is that, when you run the application fro the first time and register as a user, the database will be created as a SQL Server CE (.sfd) or SQL Express (.mdf) file in the App_Data folder in your project.

The Identity Account classes in the Default MVC 5 Project Solution Explorer:

In the above, the IdentityModel.cs file is where the essential Identity system components are defined. Opening that file in the code editor, we see two classes defined:

Code in the IdentityModel.cs Code File:

using Microsoft.AspNet.Identity.EntityFramework;
namespace DbMigrationExample.Models
{
publicclass ApplicationUser : IdentityUser
    {
    }
publicclass ApplicationDbContext : IdentityDbContext<ApplicationUser>
    {
public ApplicationDbContext()
            : base("DefaultConnection")
        {
        }
    }
}

The ApplicationUser class, which inherits from a framework class IdentityUser. This is the basic identity unit for managing individual accounts in the ASP.NET MVC 5 Account system. This class is empty as defined in the default project code, and so brings with it only those properties exposed by the base class IdentityUser. However, we can extend the ApplicationUser class by adding our own properties, which will then be reflected in the generated database. More on this in a moment.

We also find here the class ApplicationDbContext. This is the Entity Framework context used to manage interaction between our application and the database where our Account data is persisted (which may, or may not be the same database that will be used by the rest of our application). Important to note that this class inherits not from DBContext (as is the usual case with EF), but instead from IdentityDbContext. In other words, ApplicationDbContext inherits from a pre-defined DB context defined as part of Microsoft.AspNet.Identity.EntityFramework which contains the "Code-First" base classes for the Identity system.

Between these two classes, the MVC framework has provided the basics for generating and consuming the complete Identity Account database. However, the basic classes are extensible, so we can tailor things to suit our needs.

Lastly, note the AccountViewModels.cs file. Here are defined the ViewModels which are actually used by the Views in our application, such that only that information needed to populate a view and perform whatever actions need to be performed is exposed to the public-facing web. View Models are not only an effective design component from an architectural standpoint, but also prevent exposing more data than necessary.

Configuring the Database Connection

---

As mentioned previously, the default MVC project will create a SQL CE or SQL Express in the project's App_Data folder unless we tell it to do otherwise. All we really need to do is change the connection string used by the ApplicationDbContext, and point it at our target database.

The ApplicationDbContext class passes a connection string name to the base class in the constructor, namely "DefaultConnection." If we open the Web.config file, we find that under the <connectionStrings> element there is a single node, in which the "DefaultConnection" string is added to the connection strings collection:

The Default Connection String in Web.config:

<connectionStrings>
<addname="DefaultConnection"
connectionString="Data Source=(LocalDb)\v110;
    AttachDbFilename=|DataDirectory|
    \aspnet-DbMigrationExample-20131027114355.mdf;
    Initial Catalog=aspnet-DbMigrationExample-20131027114355;
    Integrated Security=True"
providerName="System.Data.SqlClient"/>
</connectionStrings>

The easiest way to change our target database is to simply change the connection string details for "DefaultConnection" in Web.config. In this case, we will swap out the SQL CE connection for a SQL Server development database I have running on my development machine (obviously, you can point this at any database you wish, or simply leave it set to use the local SQL CE database):

Pointing "DefaultConnection" at a Local SQL Server Instance:

<connectionStrings>
<addname="DefaultConnection"
connectionString="Data Source=XIVMAIN\XIVSQL;
    Initial Catalog=DbMigrationExample;Integrated Security=True"
providerName="System.Data.SqlClient"/>
</connectionStrings>

Now, if I run the application, I am greeted with the default home screen offered by the VS 2013 MVC project template:

The Home Page of the Default MVC Project Template:

From here, I click on the "register" link upper right:

The Registration Page of the Default MVC Project Template:

When I complete registration and hit the "Register" button, I am redirected back to the home page. However, we can see now, in the upper right corner, that I am, in fact, signed in as a registered user:

None of this is surprising. The reason we just went through that little exercise was to see the resulting database created once we registered. If I open SQL Server Management Studio (SSMS), I should find a new Database named DbMigrationExample:

The New SQL Server Database Viewed in SSMS:

Note the tables created here. Despite the fact that only ApplicationUser is defined in our application, all of the above are created as a result of the IdentityDbContext class from which ApplicationDbContext inherits.

The default project configuration only actually makes use of the data from dbo.AspNetUsers. However, you can see that a full range of identity management tables have been created, including those for role management, and external authorization (using Google/Facebook/Twitter accounts).

Configuring Entity Framework Migrations and Seeding the Database

---

As we develop, we may make changes to our classes which need to be reflected in the database. Also, quite often we would like to redeploy our development database either in a fresh state, or possibly with some initial data (or Seed data) present. As with previous version of Entity Framework and MVC, we can use EF Code First Migrations to do this.

Before proceeding, I am going to delete the SQL Server database created when I registered on the site and start fresh. If you did something similar, do the same.

In order to start using Migrations with your project, go to the tools menu in Visual Studio, and select Library Package Manager => Package Manager Console. When the console opens at the bottom of the screen, we simply type:

PM> Enable-Migrations –EnableAutomaticMigrations

Once we hit enter, the console will be busy for a moment as the Migrations folder is configured in our project. When the task is complete, our console window should look like this:

Console After Enable-Migrations Command:

Seeding the Database with an Initial User Records

---

For various reasons we may want to deploy our database with some initial records in place . We may need tables for certain static values pre-populated, or we might simply want some test data to work with in development. In our current case, we will deploy the database with a couple of User records pre-populated for testing purposes.

Once we have run the Enable-Migrations command as above, there should be a Migrations folder at the root of our project. If we open Configuration.cs file in that folder, we see this:

Default Code in Migrations Configuration Class:

namespace DbMigrationExample.Migrations
{
using System;
using System.Data.Entity;
using System.Data.Entity.Migrations;
using System.Linq;
internalsealedclass Configuration 
        : DbMigrationsConfiguration<DbMigrationExample.Models.ApplicationDbContext>
    {
public Configuration()
        {
            AutomaticMigrationsEnabled = true;
        }
protectedoverridevoid Seed(
            DbMigrationExample.Models.ApplicationDbContext context)
        {
//  This method will be called after migrating to the latest version.
//  You can use the DbSet<T>.AddOrUpdate() helper extension method 
//  to avoid creating duplicate seed data. E.g.
//
//    context.People.AddOrUpdate(
//      p => p.FullName,
//      new Person { FullName = "Andrew Peters" },
//      new Person { FullName = "Brice Lambson" },
//      new Person { FullName = "Rowan Miller" }
//    );
//
        }
    }
}

We want to modify the Configuration class as follows so that our test user records are created whenever the Database is created. Note that we have added some using statements to the top of the file as well to being in the Microsoft.AspNet.Identity and Microsoft.AspNet.Identity.EntityFramework, namespaces, as well as the Models namespace from our own project:

Modified Code in Migrations Configuration Class:

using System;
using System.Data.Entity;
using System.Data.Entity.Migrations;
using System.Linq;
using Microsoft.AspNet.Identity;
using Microsoft.AspNet.Identity.EntityFramework;
using DbMigrationExample.Models;
namespace DbMigrationExample.Migrations
{
internalsealedclass Configuration 
        : DbMigrationsConfiguration<DbMigrationExample.Models.ApplicationDbContext>
    {
public Configuration()
        {
            AutomaticMigrationsEnabled = true;
        }
protectedoverridevoid Seed(ApplicationDbContext context)
        {
            var manager = new UserManager<ApplicationUser>(
new UserStore<ApplicationUser>(
new ApplicationDbContext()));
for (int i = 0; i < 4; i++)
            {
                var user = new ApplicationUser()
                {
                    UserName = string.Format("User{0}", i.ToString())
                };
                manager.Create(user, string.Format("Password{0}", i.ToString()));
            }
        }
    }
}

Now that we have added code to seed the user table, we run the following command from the console:

Enable-Migration Init Command:

Add-Migration Init

When the command is finished running (it can take a few seconds) our console window looks like this:

Console Output from Enable-Migration Init:

The previous Add-Migration Init command created the scaffolding code necessary to create the database, but to this point. If we look in the Migrations folder now, we will see a couple new files added containing that code. However, nothing we have done to this point has created or modified an actual database. All the preceding has been set up.

Create/Update the Seeded Database using the Update-Database Command

---

With all that done, run the following command from the console:

Update-Database

When the command finishes, your console should look like this:

Console Output from Update-Database:

If all went well, we now see the database has been re-created with all the expected tables as before. Additionally, if we SELECT * FROM dbo.AspNetUsers we find that we now have four test users:

Query Result from dbo.AspNetUsers Table:

Now that we have a basic migration strategy in place, let's take a look at extending the elementary ApplicationUser class to incorporate some additional data fields.

Extending the IdentityModel Class with Additional Properties

---

Under the ASP.NET new Identity Model, it is easier than before to extend the basic user representation to include arbitrary fields suitable for our application management. For example, Let's assume we would like our user information to include an email address, as well as full first and last names. We can add properties for these items to the ApplicationUser class, and then update the Controllers, ViewModels, and Views which rely on Application user for registration and such.

First, let's go back to the ApplicationUser class and add the properties we want:

using Microsoft.AspNet.Identity.EntityFramework;
// Add this to bring in Data Annotations:
using System.ComponentModel.DataAnnotations;
namespace DbMigrationExample.Models
{
publicclass ApplicationUser : IdentityUser
    {
        [Required]
publicstring FirstName { get; set; }
        [Required]
publicstring LastName { get; set; }
        [Required]
publicstring Email { get; set; }
    }
publicclass ApplicationDbContext : IdentityDbContext<ApplicationUser>
    {
public ApplicationDbContext()
            : base("DefaultConnection")
        {
        }
    }
}

In the above, we added our three new properties to the ApplicationUser class, and also added the [Required] attribute. To do so, we need to add System.ComponentModel.DataAnnotations to our using statements at the top of the class file.

Update the Register Method of the AccountController

---

We also need to update the Register method on the AccountController. Currently, the code creates an instance of ApplicationUser and sets only the UserName property:

Currently, Only the UserName Property is Set:

var user = new ApplicationUser() { UserName = model.UserName };

We need to add the following (the code following the comment) to make our controller work properly:

Register Method of AccountController Updated to Set the New User Properties:

[HttpPost]
[AllowAnonymous]
[ValidateAntiForgeryToken]
public async Task<ActionResult> Register(RegisterViewModel model)
{
if (ModelState.IsValid)
    {
// Add the following to populate the new user properties
// from the ViewModel data:
        var user = new ApplicationUser() 
        { 
            UserName = model.UserName, 
            FirstName = model.FirstName,
            LastName = model.LastName,
            Email = model.Email
        };
        var result = await UserManager.CreateAsync(user, model.Password);
if (result.Succeeded)
        {
            await SignInAsync(user, isPersistent: false);
return RedirectToAction("Index", "Home");
        }
else
        {
            AddErrors(result);
        }
    }
// If we got this far, something failed, redisplay form
return View(model);
}

Update the Register ViewModel

---

Now that we have added the new properties to our ApplicationUser class, we also need to provide a way for the user to input the values during the registration process. If we open the AccountViewModels.cs file, we see a number of ViewModel classes defined. At the bottom is the RegisterViewModel class. It currently looks like this:

The Default RegisterViewModel Class:

publicclass RegisterViewModel
{
    [Required]
    [Display(Name = "User name")]
publicstring UserName { get; set; }
    [Required]
    [StringLength(100, ErrorMessage = 
"The {0} must be at least {2} characters long.", MinimumLength = 6)]
    [DataType(DataType.Password)]
    [Display(Name = "Password")]
publicstring Password { get; set; }
    [DataType(DataType.Password)]
    [Display(Name = "Confirm password")]
    [Compare("Password", ErrorMessage = 
"The password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
}

We want to add our new properties, so we modify it as follows:

Modified RegisterViewModel Class:

publicclass RegisterViewModel
{
    [Required]
    [Display(Name = "User name")]
publicstring UserName { get; set; }
    [Required]
    [StringLength(100, ErrorMessage = 
"The {0} must be at least {2} characters long.", MinimumLength = 6)]
    [DataType(DataType.Password)]
    [Display(Name = "Password")]
publicstring Password { get; set; }
    [DataType(DataType.Password)]
    [Display(Name = "Confirm password")]
    [Compare("Password", ErrorMessage = 
"The password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
    [Required]
    [Display(Name = "First name")]
publicstring FirstName { get; set; }
    [Required]
    [Display(Name = "Last name")]
publicstring LastName { get; set; }
    [Required]
    [Display(Name = "Email")]
publicstring Email { get; set; }
}

Update the Register View

---

Now that we have that taken care of, we need to also modify the Register.cshtml View to match. In the folder Views => Account open the Register.cshtml file. It should look like this:

The Default Register.cshtml File:

@model DbMigrationExample.Models.RegisterViewModel
@{
    ViewBag.Title = "Register";
}
<h2>@ViewBag.Title.</h2>
@using (Html.BeginForm("Register", "Account", 
    FormMethod.Post, new { @class = "form-horizontal", role = "form" }))
{
    @Html.AntiForgeryToken()
<h4>Create a new account.</h4>
<hr />
    @Html.ValidationSummary()
<div class="form-group">
        @Html.LabelFor(m => m.UserName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.UserName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.Password, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.PasswordFor(m => m.Password, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.ConfirmPassword, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.PasswordFor(m => m.ConfirmPassword, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" class="btn btn-default" value="Register" />
</div>
</div>
}
@section Scripts {
    @Scripts.Render("~/bundles/jqueryval")
}

Add the new properties after the existing form-group element for "ConfirmPassword" as follows:

Modified Register.cshml File:

<h2>@ViewBag.Title.</h2>
@using (Html.BeginForm("Register", "Account", 
    FormMethod.Post, new { @class = "form-horizontal", role = "form" }))
{
    @Html.AntiForgeryToken()
<h4>Create a new account.</h4>
<hr />
    @Html.ValidationSummary()
<div class="form-group">
        @Html.LabelFor(m => m.UserName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.UserName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.Password, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.PasswordFor(m => m.Password, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.ConfirmPassword, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.PasswordFor(m => m.ConfirmPassword, new { @class = "form-control" })
</div>
</div>
// Add new properties here:
<div class="form-group">
        @Html.LabelFor(m => m.FirstName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.FirstName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.LastName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.LastName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.Email, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.Email, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" class="btn btn-default" value="Register" />
</div>
</div>
}
@section Scripts {
    @Scripts.Render("~/bundles/jqueryval")
}

Updating the Database to Reflect Modified Entity Classes

---

So far, we have modified one of our Data model Entity classes – namely, the ApplicationUser class. In our application, EF is mapping this class to the dbo.AspNetUsers table in our backend. We need to run Migrations again to update things. Before we do that though, there is one more thing we need to do. Our seed method is no longer in sync with what our classes (and shortly, our back-end tables) require. We need to add values for the new FirstName, LastName, and Email properties to our user Seed data:

Updated Seed method:

protectedoverridevoid Seed(ApplicationDbContext context)
{
    var manager = new UserManager<ApplicationUser>(
new UserStore<ApplicationUser>(
new ApplicationDbContext()));
for (int i = 0; i < 4; i++)
    {
        var user = new ApplicationUser()
        {
            UserName = string.Format("User{0}", i.ToString()),
// Add the following so our Seed data is complete:
            FirstName = string.Format("FirstName{0}", i.ToString()),
            LastName = string.Format("LastName{0}", i.ToString()),
            Email = string.Format("Email{0}@Example.com", i.ToString()),
        };
        manager.Create(user, string.Format("Password{0}", i.ToString()));
    }
}

Now, if we were to run the Update-Database command again, the changes to our entity objects will be reflected in the dbo.AspNetUsers table schema, but our seed data will not be updated, because Entity Framework doesn't like to do things which will cause data loss. While there are ways to make this happen, they are beyond the scope of this article. Instead, we will manually delete the database, and then run Update-Database again. However, since EF thinks that we have existing data from our previous migration, we have to use Update-Database -force.

Once we have deleted the database and run the Update-Database –force command, our console output should look like this:

Console Output Update-Database –force After Deleting Database:

Quickly re-running our query shows that indeed, the new fields have been added to our table, and the test data populated:

Query Result from dbo.AspNetUsers Table:

User Registration with Updated Registration Form

---

Now that we have updated our Registration.cshtml View, Controller method, ViewModel, and Database, when we run the application and go to register, we see the updated Registration form:

The Updated Registration Form:

Once we complete the form and hit the Register button, we are logged in successfully, wit our additional data persisted in the database, ready to be used in our application.

Logging in Using Seed Data

---

Alternatively, we can also log out, and log in as one of our test users by clicking the "Log in" link:

Logging in with Test Data:

Successful Log-in:

Only the Beginning

---

The updates to ASP.NET MVC 5 are numerous, and cool. In this article I have kept it really basic, and only scratched the surface of the updated Account management possibilities. The ASP.NET and MVC team has made it easy to do things like add role-based identity management, as well as external log-ins from social networks such as Google +, Facebook, and Twitter.

In my next post, I will take a closer look at creating a role-based identity management model for administering a "closed" site.

Additional Resources and Items of Interest

---

• ASP.NET MVC–Azure Websites and EF Model First Connection Strings when Deploying from Github
• Reverse-Engineering an Existing Database in your ASP.NET MVC Application Using Entity Framework Model/Database-First
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Customizing Routes in ASP.NET MVC
• Routing Basics in ASP.NET MVC

Nuget is cool.

What is not cool is when you push a project to source control and include a ton of installed packages, bulking up your repo with stuff that could be easily pulled in via Nuget by anyone cloning your project. However, what was equally irritating was having to include instructions for what packages need to be installed, if they were excluded from the source repo.

Enter Nuget Package Restore.

• Enable Nuget Package Restore for the Solution
• Edit .gitignore to Exclude Packages and Include NuGet.exe
• Ignore Packages Folder
• Make an Exception to Include NuGet.exe
• Inform Potential Consumers of Your Code
• Additional Resources and Items of Interest

Allow Visual Studio to Restore Nuget Packages During Build

---

Before you can avail yourself of Nuget Package Restore, we need to explicitly allow this behavior on our machine. This is required on a per-machine basis before Nuget can restore packages for a solution automagically, and can be set in Tools => Options => Package Manager:

Visual Studio Options Menu:

Package Manager Settings Dialog:

Now that our machine has been told it is ok to restore Nuget Packages automatically, we need to enable this behavior in our specific solution as well.

Enable Nuget Package Restore for the Solution

---

To enable Nuget Package Restore in our specific solution, right-click on Solution Explorer => Your Solution => Enable Package Restore:

Enabling Nuget Package Restore for a Specific VS Solution:

This may take a few seconds. When VS is done processing, an examination of Solution Explorer reveals a new folder at the root solution level:

Files Added to Solution by Nuget Package Restore:

Notice the NuGet.exe file in there? This file is required when, for example, someone clones your project from source and attempts to build with Nuget Package Restore enabled. Therefore, it needs to be committed to source control.

We also now want to exclude all the package files from source by editing our .gitignore file (I am assuming Git as the source control provider, but the principle here applies to whichever provider you are using – you need to tell your version control system what to include in the repository and what to keep out).

Edit .gitignore to Exclude Packages and Include NuGet.exe

---

A typical ASP.NET MVC 5 project created from the standard VS 2013 template will contain (as of this writing) 161 files from various Nuget packages included as part of the default solution. This is some significant bulk. Using the default .gitignore file (or any of the most common in use for Visual Studio/C# projects) the total number of files which will tend to be included as part of the project repo numbers over 200. Note this is after excluding all the binaries and VS housekeeping files. In other words, nearly 75% of the common files in a VS 2013 ASP.NET MVC 5 solution consist of Nuget packages, which can now be restored automatically instead of pushed up to our repo.

To cut down the bulk, lets modify our .gitignore as follows. Note, your .gitignore (or .hgignore, or .tfsignore, what have you) will most likely look a little different than mine. That's okay, because we're only going to do a few small tweaks to the file – keep the rest the same.

Ignore Packages Folder

---

Open your .gitignore file and add the following line to exclude the packages folder from source:

Ignore Packages Folder in .gitignore:

packages*/

Make an Exception to Include NuGet.exe

---

Most likely, your .gitignore file already excludes files with the .exe extension. We may want to make an exception for Nuget.exe, since it will be needed to restore packages by anyone cloning our repo:

Look through your .gitignore until you find the following:

*.exe

Then add this right AFTER it (the order here is important):

*.exe
!NuGet.exe

The above tells Git to ignore .exe files, but to make an exception for NuGet.exe.

The step above is optional, since someone cloning your solution could simply Enable Nuget Package Restore for the solution, at which point the NuGet.exe would be installed. However, this saves the step.

Inform Potential Consumers of Your Code

---

Now, we no longer need to include all the installed Nuget package files in our source repo. However, we should probably add a blurb to the README.txt file (or otherwise inform consumers of our code) letting users know that they will need to perform the VS configuration needed to allow Nuget to restore packages as described in the first step in this article.

Additional Resources and Items of Interest

---

• Documentation at Nuget.org
• Code-First Migration and Extending Identity Accounts in ASP.NET MVC 5
• Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
• Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project

In a previous post, we took a quick look at extending Identity Accounts in the context of the new Identity system under ASP.NET MVC 5. We also examined the basics of Entity Framework Code-First Migrations. If you haven't read that article, you might want to do so now, so we don't have to repeat some of the general ideas explained there.

Image by: Elif Ayiter | Some Rights Reserved

For the purpose of this post, we are going to look at a implementing relatively simple role-based authentication and identity management for an ASP.NET MVC 5 web application. The examples used will be deliberately simplified, and while they will effectively illustrate the basics of setting up role-based identity management, I can promise that the implementation here will lack certain things we would like to see in a production project (such as complete exception handling). Also, production application modeling would likely look a little different based upon business needs.

In other words, I'm keeping it simple, much like we ignored the effects of friction way back in high school physics.

That said, there's a lot to cover. The article is not as long as it seems, because I am including some large code samples, and images to illustrate what's going on. The complete project source code for the project discussed in this article can be found at my Github Repo.

• Simplifying AccountController – Remove the Clutter
• Remove Uneeded Views
• Clean Up Account-Related Views
• Remove Unneeded Model Classes
• Extending the Identity Management Models and View Models
• Extending the Account Controller
• Adding the UserRoles Method to the AccountController
• Basic Views for Role-Based Identity Management
• Use [Authorize] Attribute to Control Access
• Additional Resources and Items of Interest

Download the Source Code

The complete project source code for this article is available at my Gihub Repo. NOTE: You will need to enable Nuget Package Restore in order to build the project properly. 

Basic Hypothetical Application Requirements

---

We will assume our identity management needs to do the following for a Line-of-Business web application used primarily by internal users or others suitably authorized by management. The application will have a minimal public-facing interface, and will require all users to log-in to access even minimal functionality (it is easy to extend what we will be doing to include public users, but this is derived from an actual application I needed to create rather quickly at work).

• User accounts must be created by one or more Admin-level users. "Registration" as we know it from the ASP.NET Membership paradigm, does not exists (anonymous users cannot register and create accounts from the public site).
• User Identity accounts will be extended to include an email address, and first/last names
• For our purposes, there will be at least three Roles; Administrator (full access to everything), Editor (can perform most business functions of the application, but cannot access admin functions such as account management), and Read-Only User (what the name implies).
• Each user may be a member of zero or more roles. Multiple roles will have the access rights of all the roles combines.
• To keep things simple, roles are independently defined, and are not members of other roles.
• All application roles are pre-defined. There is no administrative creation of roles. Also, Role permissions are integral to the application, and not manageable by administrators (this is for simplicity at this point).
• Anonymous access to the site is not allowed, except to the log-in portal.
• There will be no use of external log-ins or OAuth (code for this is included as part of the default MVC project. We will remove it to keep things clean).

Getting Started – Stripping Unneeded Items from the MVC Project Template

---

While we could start with what we created in the previous article on Extending Identity Accounts, we will be re-arranging things sufficiently it will be cleaner for our purposes to start fresh. Create a new ASP.NET MVC project in Visual Studio. Before we do anything else, let's clear out some unneeded clutter so we are left with only what we need.

We are going to be removing a bunch of code related to managing external log-ins, as well as clearing out some of the extraneous comments included with the default project (which to me, just add noise to our code).

We will start with the AccountController.

Simplifying AccountController – Remove the Clutter

---

There are a number of m on AccountController related to External Logins which we don't need. If you examine AccountController carefully, you can go through and delete the code for the following methods:

• Dissociate()
  
• ExternalLogin()
  
• ExternalLoginCallback()
  
• LinkLogin()
  
• LinkLoginCallback()
  
• ExternalLoginConfirmation()
  
• ExternalLoginFailure()
  
• RemoveAccountList()

Additionally, if you look closely, there is a code #region (I know. I hate #region and think it should be done away with) for helpers. From here, we can delete the following items:

• The member constant XsrfKey
• The entire class ChallengeResult

At this point, we can also right-click in the code file and select Remove and Sort Usings to clear out some of the unneeded clutter here as well.

At this point, our AccountController.cs file should contain the following methods (reduced to simple stubs here for brevity – we'll get to the code shortly:

The Cleaned Up AccountController.cs File (Stubs Only - Code Hidden for Brevity):

using AspNetRoleBasedSecurity.Models;
using Microsoft.AspNet.Identity;
using Microsoft.AspNet.Identity.EntityFramework;
using Microsoft.Owin.Security;
using System.Threading.Tasks;
using System.Web;
using System.Web.Mvc;
namespace AspNetRoleBasedSecurity.Controllers
{
    [Authorize]
publicclass AccountController : Controller
    {
public AccountController()
            : this(new UserManager<ApplicationUser>(
new UserStore<ApplicationUser>(new ApplicationDbContext())))
        {
        }
public AccountController(UserManager<ApplicationUser> userManager)
        {
            UserManager = userManager;
        }
public UserManager<ApplicationUser> UserManager { get; privateset; }
        [AllowAnonymous]
public ActionResult Login(string returnUrl)
        {
            ViewBag.ReturnUrl = returnUrl;
return View();
        }
        [HttpPost]
        [AllowAnonymous]
        [ValidateAntiForgeryToken]
public async Task<ActionResult> Login(LoginViewModel model, string returnUrl)
        {
// . . . Code Hidden for brevity
        }
        [AllowAnonymous]
public ActionResult Register()
        {
return View();
        }
        [HttpPost]
        [AllowAnonymous]
        [ValidateAntiForgeryToken]
public async Task<ActionResult> Register(RegisterViewModel model)
        {
// . . . Code Hidden for brevity
        }
public ActionResult Manage(ManageMessageId? message)
        {
// . . . Code Hidden for brevity
        }
        [HttpPost]
        [ValidateAntiForgeryToken]
public async Task<ActionResult> Manage(ManageUserViewModel model)
        {
// . . . Code Hidden for brevity
        }
        [HttpPost]
        [ValidateAntiForgeryToken]
public ActionResult LogOff()
        {
            AuthenticationManager.SignOut();
return RedirectToAction("Index", "Home");
        }
protectedoverridevoid Dispose(bool disposing)
        {
// . . . Code Hidden for brevity
        }
        #region Helpers
private IAuthenticationManager AuthenticationManager
        {
// . . . Code Hidden for brevity
        }
private async Task SignInAsync(ApplicationUser user, bool isPersistent)
        {
// . . . Code Hidden for brevity
        }
privatevoid AddErrors(IdentityResult result)
        {
// . . . Code Hidden for brevity
        }
privatebool HasPassword()
        {
// . . . Code Hidden for brevity
        }
publicenum ManageMessageId
        {
// . . . Code Hidden for brevity
        }
private ActionResult RedirectToLocal(string returnUrl)
        {
// . . . Code Hidden for brevity
        }
        #endregion
    }
}

Remove Unneeded Views

---

Along with the unnecessary Controller methods we just removed, we can also remove the unnecessary views related to external logins. If we open the Views => Account folder in Solution Explorer, we find we can delete the highlighted views below from our project:

Solution Explorer – Remove Unneeded Views:

Now that the totally unnecessary views are out of the way, let's remove the External Log-in code from the remaining views as well.

Clean Up Account-Related Views

---

There is some remaining clutter to clear out of our Account-related views. We don't want dead-end links on our site, and we want to keep only relevant code in our views.

We can start with the Login.cshtml file, which contains a section related to creating an external log-in from various social networks (highlighted in yellow).

Login.cshtml - Remove Social Network Login Option:

@{
    ViewBag.Title = "Log in";
}
<h2>@ViewBag.Title.</h2>
<div class="row">
<div class="col-md-8">
<section id="loginForm">
            @using (Html.BeginForm("Login", "Account", new { ReturnUrl = ViewBag.ReturnUrl }, FormMethod.Post, new { @class = "form-horizontal", role = "form" }))
            {
                @Html.AntiForgeryToken()
<h4>Use a local account to log in.</h4>
<hr />
                @Html.ValidationSummary(true)
<div class="form-group">
                    @Html.LabelFor(m => m.UserName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
                        @Html.TextBoxFor(m => m.UserName, new { @class = "form-control" })
                        @Html.ValidationMessageFor(m => m.UserName)
</div>
</div>
<div class="form-group">
                    @Html.LabelFor(m => m.Password, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
                        @Html.PasswordFor(m => m.Password, new { @class = "form-control" })
                        @Html.ValidationMessageFor(m => m.Password)
</div>
</div>
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<div class="checkbox">
                            @Html.CheckBoxFor(m => m.RememberMe)
                            @Html.LabelFor(m => m.RememberMe)
</div>
</div>
</div>
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" value="Log in" class="btn btn-default" />
</div>
</div>
<p>
                    @Html.ActionLink("Register", "Register") if you don't have a local account.
</p>
            }
</section>
</div>
<div class="col-md-4">
<section id="socialLoginForm">
            @Html.Partial("_ExternalLoginsListPartial", new { Action = "ExternalLogin", ReturnUrl = ViewBag.ReturnUrl })
</section>
</div>
</div>
@section Scripts {
    @Scripts.Render("~/bundles/jqueryval")
}

In the above, the section highlighted in yellow can be deleted.

Next, let's remove similar External Login functionality from the Manage.cshtml file (highlighted in yellow, again):

Manage.cshtml – Remove External Login Items:

@using AspNetRoleBasedSecurity.Models;
@using Microsoft.AspNet.Identity;
@{
    ViewBag.Title = "Manage Account";
}
<h2>@ViewBag.Title.</h2>
<p class="text-success">@ViewBag.StatusMessage</p>
<div class="row">
<div class="col-md-12">
        @if (ViewBag.HasLocalPassword)
        {
            @Html.Partial("_ChangePasswordPartial")
        }
else
        {
            @Html.Partial("_SetPasswordPartial")
        }
<section id="externalLogins">
            @Html.Action("RemoveAccountList")
            @Html.Partial("_ExternalLoginsListPartial", new { Action = "LinkLogin", ReturnUrl = ViewBag.ReturnUrl })
</section>
</div>
</div>
@section Scripts {
    @Scripts.Render("~/bundles/jqueryval")
}

As before, the highlighted area can be safely removed.

Remove Unneeded Model Classes

---

As with the previous sections, there are unneeded model classes we can safely dispose of in order to clean up our project. If we expand the Models folder in Solution Explorer, we find there is a single code file, AccountViewModels.cs,  containing several ViewModel classes related to Identity Management. Review the file carefully, and delete the ExternalLogInConfirmationViewModel item highlighted in yellow below:

Account View Models File – Remove Unneeded Classes:

using System.ComponentModel.DataAnnotations;
namespace AspNetRoleBasedSecurity.Models
{
publicclass ExternalLoginConfirmationViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
    }
publicclass ManageUserViewModel
    {
        [Required]
        [DataType(DataType.Password)]
        [Display(Name = "Current password")]
publicstring OldPassword { get; set; }
        [Required]
        [StringLength(100, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
        [DataType(DataType.Password)]
        [Display(Name = "New password")]
publicstring NewPassword { get; set; }
        [DataType(DataType.Password)]
        [Display(Name = "Confirm new password")]
        [Compare("NewPassword", ErrorMessage = "The new password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
    }
publicclass LoginViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
        [Required]
        [DataType(DataType.Password)]
        [Display(Name = "Password")]
publicstring Password { get; set; }
        [Display(Name = "Remember me?")]
publicbool RememberMe { get; set; }
    }
publicclass RegisterViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
        [Required]
        [StringLength(100, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
        [DataType(DataType.Password)]
        [Display(Name = "Password")]
publicstring Password { get; set; }
        [DataType(DataType.Password)]
        [Display(Name = "Confirm password")]
        [Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
    }
}

Extending the Identity Management Models and View Models

---

As we have seen, the Model classes used by our application to manage identity and authorization are contained in the IdentityModels.cs file. Additionally, there are Identity-related ViewModel classes defined in the AccountViewModels.cs file used to manage the transfer of identity data between our views and controllers.

Important to note here that we would really like to get all of our model definitions correct before we run the application and create any new user accounts, or register using the normal (and soon-to-be-removed) MVC "registration" mechanism. We are going to use Entity Framework Migrations and Code-First to do the Database heavy-lifting for us. While it is not terribly difficult to update our models later (and hence, the database, through EF migrations), it is cleaner and smoother to get it right up front. 

In order to conform to our project specifications, one of the first things we need to do is extend the default ApplicationUser class to include Email, LastName, and FirstName properties. Open the IdentityModels.cs file. Currently, the code should look like this:

The Default IdentityModels File with Emply ApplicationUser Stub:

using Microsoft.AspNet.Identity.EntityFramework;
namespace AspNetRoleBasedSecurity.Models
{
publicclass ApplicationUser : IdentityUser
    {
    }
publicclass ApplicationDbContext : IdentityDbContext<ApplicationUser>
    {
public ApplicationDbContext()
            : base("DefaultConnection")
        {
        }
    }
}

In this step, we are going to extend our ApplicationUser class to include the properties required by our application specification. Also, we will add an IdentityManager class in which we consolidate our user and role management functions. We'll discuss how all this works in a moment. For now, add the following code to the IdentityModels.cs code file (note we have added some new using statements at the top as well):

Modified IdentityModels.cs File

using Microsoft.AspNet.Identity.EntityFramework;
using Microsoft.AspNet.Identity;
using System.ComponentModel.DataAnnotations;
using System.Collections.Generic;
namespace AspNetRoleBasedSecurity.Models
{
publicclass ApplicationUser : IdentityUser
    {
        [Required]
publicstring FirstName { get; set; }
        [Required]
publicstring LastName { get; set; }
        [Required]
publicstring Email { get; set; }
    }
publicclass ApplicationDbContext : IdentityDbContext<ApplicationUser>
    {
public ApplicationDbContext()
            : base("DefaultConnection")
        {
        }
    }
publicclass IdentityManager
    {
publicbool RoleExists(string name)
        {
            var rm = new RoleManager<IdentityRole>(
new RoleStore<IdentityRole>(new ApplicationDbContext()));
return rm.RoleExists(name);
        }
publicbool CreateRole(string name)
        {
            var rm = new RoleManager<IdentityRole>(
new RoleStore<IdentityRole>(new ApplicationDbContext()));
            var idResult = rm.Create(new IdentityRole(name));
return idResult.Succeeded;
        }
publicbool CreateUser(ApplicationUser user, string password)
        {
            var um = new UserManager<ApplicationUser>(
new UserStore<ApplicationUser>(new ApplicationDbContext()));
            var idResult = um.Create(user, password);
return idResult.Succeeded;
        }
publicbool AddUserToRole(string userId, string roleName)
        {
            var um = new UserManager<ApplicationUser>(
new UserStore<ApplicationUser>(new ApplicationDbContext()));
            var idResult = um.AddToRole(userId, roleName);
return idResult.Succeeded;
        }
publicvoid ClearUserRoles(string userId)
        {
            var um = new UserManager<ApplicationUser>(
new UserStore<ApplicationUser>(new ApplicationDbContext()));
            var user = um.FindById(userId);
            var currentRoles = new List<IdentityUserRole>();
            currentRoles.AddRange(user.Roles);
foreach(var role in currentRoles)
            {
                um.RemoveFromRole(userId, role.Role.Name);
            }
        }
    }
}

Yeah, I know. There is room for some refactoring here.We'll ignore that for now. In the above, we have extended ApplicationUser to include our new required properties, and added the IdentityManager class, which includes the methods required to create new users, and add/remove users from available roles.

We have also decorated our new ApplicationUser properties with the [Required] data annotation, which will be reflected both in our database (nulls will not be allowed) and our Model Validation for our views.

SIDE NOTE, REDUX: I am utilizing the methods available directly within the Microsoft.AspNet.Identity and Microsoft.AspNet.Identity.EntityFramework namespaces. I am content to let the ASP.NET team invent and provide the best practices for managing application security. Therefore, in the context of this application, I am not inventing my own. I strongly recommend you do as well. It is easy to spot ways to manage some of the Account/Identity stuff (including data persistence) which appear more direct or easier. I concluded that the team thought all this through more effectively than I can. Therefore, while we are creating an authorization management structure here, we are doing so using the core implementation provided by people who know better than we do.

Extending Account Management ViewModels

---

Now that we have expanded upon our basic Identity Models, we need to do the same with our Account ViewModels. ViewModels essentially represent a data exchange mechanism between our views and Controllers. Our goal here is to provide our Account management views with precisely the information required to perform the task at hand, and no more.

Also of note is that for the purpose of our presentation layer, I am not pushing User or Role id's out onto the page or the backing html. Instead I am relying on the unique nature of the Username and Role names to look up the proper Id value server-side.

Currently, before we do anything, our AccountVeiwModels.cs file looks like this:

The AccountViewModels.cs File Before Modification:

using System.ComponentModel.DataAnnotations;
namespace AspNetRoleBasedSecurity.Models
{
publicclass ManageUserViewModel
    {
        [Required]
        [DataType(DataType.Password)]
        [Display(Name = "Current password")]
publicstring OldPassword { get; set; }
        [Required]
        [StringLength(100, ErrorMessage = 
"The {0} must be at least {2} characters long.", MinimumLength = 6)]
        [DataType(DataType.Password)]
        [Display(Name = "New password")]
publicstring NewPassword { get; set; }
        [DataType(DataType.Password)]
        [Display(Name = "Confirm new password")]
        [Compare("NewPassword", ErrorMessage = 
"The new password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
    }
publicclass LoginViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
        [Required]
        [DataType(DataType.Password)]
        [Display(Name = "Password")]
publicstring Password { get; set; }
        [Display(Name = "Remember me?")]
publicbool RememberMe { get; set; }
    }
publicclass RegisterViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
        [Required]
        [StringLength(100, ErrorMessage = 
"The {0} must be at least {2} characters long.", MinimumLength = 6)]
        [DataType(DataType.Password)]
        [Display(Name = "Password")]
publicstring Password { get; set; }
        [DataType(DataType.Password)]
        [Display(Name = "Confirm password")]
        [Compare("Password", ErrorMessage = 
"The password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
    }
}

We are going to expand on this significantly. In fact, it may seem, redundantly. For, with a few minor differences, it might appear that one or two of the ViewModels in the following code are near-duplicates, and possible candidates for a refactoring into a single class. However, I decided that the purpose of the ViewModel is to represent the specific data required by a specific view. While in some cases these appear to be the same, that may change. I concluded that it is better, so far as Views and ViewModels go, to have some potential duplication, but preserve the ability of each view to evolve independently should the need arise, without having to fuss with the impact on other views dependent on the same ViewModel.

Modify the code above as follows (or simply replace it with the following). We'll take a closer look at the functionality in a moment, when we get to the Controller implementation:

Modified Code for AccountViewModels.cs File:

using System.ComponentModel.DataAnnotations;
// New namespace imports:
using Microsoft.AspNet.Identity.EntityFramework;
using System.Collections.Generic;
namespace AspNetRoleBasedSecurity.Models
{
publicclass ManageUserViewModel
    {
        [Required]
        [DataType(DataType.Password)]
        [Display(Name = "Current password")]
publicstring OldPassword { get; set; }
        [Required]
        [StringLength(100, ErrorMessage = 
"The {0} must be at least {2} characters long.", MinimumLength = 6)]
        [DataType(DataType.Password)]
        [Display(Name = "New password")]
publicstring NewPassword { get; set; }
        [DataType(DataType.Password)]
        [Display(Name = "Confirm new password")]
        [Compare("NewPassword", ErrorMessage = 
"The new password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
    }
publicclass LoginViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
        [Required]
        [DataType(DataType.Password)]
        [Display(Name = "Password")]
publicstring Password { get; set; }
        [Display(Name = "Remember me?")]
publicbool RememberMe { get; set; }
    }
publicclass RegisterViewModel
    {
        [Required]
        [Display(Name = "User name")]
publicstring UserName { get; set; }
        [Required]
        [StringLength(100, ErrorMessage = 
"The {0} must be at least {2} characters long.", MinimumLength = 6)]
        [DataType(DataType.Password)]
        [Display(Name = "Password")]
publicstring Password { get; set; }
        [DataType(DataType.Password)]
        [Display(Name = "Confirm password")]
        [Compare("Password", ErrorMessage = 
"The password and confirmation password do not match.")]
publicstring ConfirmPassword { get; set; }
// New Fields added to extend Application User class:
        [Required]
        [Display(Name = "First Name")]
publicstring FirstName { get; set; }
        [Required]
        [Display(Name = "Last Name")]
publicstring LastName { get; set; }
        [Required]
publicstring Email { get; set; }
// Return a pre-poulated instance of AppliationUser:
public ApplicationUser GetUser()
        {
            var user = new ApplicationUser()
            {
                UserName = this.UserName,
                FirstName = this.FirstName,
                LastName = this.LastName,
                Email = this.Email,
            };
return user;
        }
    }
publicclass EditUserViewModel
    {
public EditUserViewModel() { }
// Allow Initialization with an instance of ApplicationUser:
public EditUserViewModel(ApplicationUser user)
        {
this.UserName = user.UserName;
this.FirstName = user.FirstName;
this.LastName = user.LastName;
this.Email = user.Email;
        }
        [Required]
        [Display(Name = "User Name")]
publicstring UserName { get; set; }
        [Required]
        [Display(Name = "First Name")]
publicstring FirstName { get; set; }
        [Required]
        [Display(Name = "Last Name")]
publicstring LastName { get; set; }
        [Required]
publicstring Email { get; set; }
    }
publicclass SelectUserRolesViewModel
    {
public SelectUserRolesViewModel() 
        {
this.Roles = new List<SelectRoleEditorViewModel>();
        }
// Enable initialization with an instance of ApplicationUser:
public SelectUserRolesViewModel(ApplicationUser user) : this()
        {
this.UserName = user.UserName;
this.FirstName = user.FirstName;
this.LastName = user.LastName;
            var Db = new ApplicationDbContext();
// Add all available roles to the list of EditorViewModels:
            var allRoles = Db.Roles;
foreach(var role in allRoles)
            {
// An EditorViewModel will be used by Editor Template:
                var rvm = new SelectRoleEditorViewModel(role);
this.Roles.Add(rvm);
            }
// Set the Selected property to true for those roles for 
// which the current user is a member:
foreach(var userRole in user.Roles)
            {
                var checkUserRole = 
this.Roles.Find(r => r.RoleName == userRole.Role.Name);
                checkUserRole.Selected = true;
            }
        }
publicstring UserName { get; set; }
publicstring FirstName { get; set; }
publicstring LastName { get; set; }
public List<SelectRoleEditorViewModel> Roles { get; set; }
    }
// Used to display a single role with a checkbox, within a list structure:
publicclass SelectRoleEditorViewModel
    {
public SelectRoleEditorViewModel() {}
public SelectRoleEditorViewModel(IdentityRole role)
        {
this.RoleName = role.Name;
        }
publicbool Selected { get; set; }
        [Required]
publicstring RoleName { get; set;}
    }
}

Extending the Account Controller

---

Now that we have our Models and ViewModels mostly in place, let's look at how it all comes together in the Controller. Our current AccountController defines Controller Actions for the following:

• Register (Essentially creates a new user)
• Manage (Essentially allows the user to change their password)
• Login
• Log Off

Also, the above methods are focused upon allowing anonymous users to self-register, and create their own user account.

We are not planning to allow self-registration, and our requirements establish that user accounts are to be created by an administrator. Also, we have extended our ApplicationUser model to include some additional properties. From a functional perspective, we would like to se the following behavior implemented:

• View a list of user accounts (Index), with links to various relevant functionality (Edit, Roles, Etc.)
• Create a new User (We will co-opt the "Register" method for this, but we will extend it significantly).
• Edit a User (Administrators need to be able to edit user accounts, assign roles, and such)
• Delete a User (We want to be able to remove User accounts (or at least render them active or inactive)
• Assign Roles to a User
• Login
• Log Off

Before we proceed, understand that there are countless possible major and minor variations we could consider for the above. I chose an application model which was simple, and for our purposes, rather arbitrary. For example, it could be your application requirements allow for self-registration of anonymous users into a default Role of some sort. The model I represent here is by purpose rather limited in scope, as we are trying to see concepts without getting too distracted by a complex implementation. I leave to you to expand from here into more complex (and more useful to you) application models.

In keeping with the above, I have added the [Authorize(Roles = "Admin")] attribute to all of the administrative methods, with the assumption that our administrative role will be called (wait for it . . .) "Admin." More on this later too.

Where was I?

Oh, yeah. So, looking at the functional needs in the list above, I am going to modify my AccountController to incorporate the above items. As mentioned parenthetically, I am simply going to co-opt the Register controller method and use it for what should probably be named Create (out of laziness at this point!).

Modifying The AccountController Register Method (Create User)

---

First, we will look at modifying our existing Register method(s) to accommodate our new ApplicationUser properties. We want to be able to create a new ApplicationUser in our View, and then persist the new record in our database.

Modified Register Method:

[Authorize(Roles = "Admin")]
public ActionResult Register()
{
return View();
}
[HttpPost]
[Authorize(Roles = "Admin")]
[ValidateAntiForgeryToken]
public async Task<ActionResult> Register(RegisterViewModel model)
{
if (ModelState.IsValid)
    {
        var user = model.GetUser();
        var result = await UserManager.CreateAsync(user, model.Password);
if (result.Succeeded)
        {
return RedirectToAction("Index", "Account");
        }
    }
// If we got this far, something failed, redisplay form
return View(model);
}

In the above, we have not changed much except using the handy GetUser() method defined on our RegisterViewModel to retrieve an instance of ApplicationUser, populated and ready to persist in our database. Also, we are redirecting to a new Index method we will define momentarily on our AccountController.

Adding The AccountController Index Method (View List of Users)

---

Previously, the AccountController did not have an Index method. We need a way for our Administrators to view a list of users of our application, and access the functionality to edit, assign roles, and delete. Once again, accessing the user account data is an admin function, so we have added the [Authorize] attribute as well.

The New Index Method:

[Authorize(Roles = "Admin")]
public ActionResult Index()
{
    var Db = new ApplicationDbContext();
    var users = Db.Users;
    var model = new List<EditUserViewModel>();
foreach(var user in users)
    {
        var u = new EditUserViewModel(user);
        model.Add(u);
    }
return View(model);
}

Our Index method uses a List<EditUserViewModel> for now, as it contains all the information needed for display in our list. Contrary to what I said above, I have re-used a ViewModel here. I should probably fix that, but you can make your own decision on this point.

Notice that instead of performing the tedious mapping of properties from ApplicationUser instance to each EditUserViewModel within this method, I simply pass the ApplicationUser instance into the overridden constructor on EditUserViewModel. Our Index.cshtml View will expect a List<EditUserViewModel> as the model for display.

Adding The AccountController Edit Method

---

We have added an Edit method to facilitate administrative updating of User account data. There are some details to pay attention to in the Edit method implementation, at least in my version. First, while the method still accepts a parameter named id, what we will actually be passing to the method when a request is routed here will be a UserName. Why? I decided to follow the lead of the ASP.NET team on this. They are not passing User Id's (which are GUID's) out into the public HTML, so neither will I.

Also, by design and constraint, the UserName is unique in our database, and will already be a semi-public piece of information. Just something to keep in mind – the id parameter for public Account Action methods will be the User (or, as the case may be, Role) name, and not an integer. Lastly, I didn't want to add a whole new route just to rename a single route parameter which is serving essentially the same purpose as an int id.

That said, the following is the new Edit method, which will be used when an Administrator wishes to update user information:

The New Edit Method:

[HttpPost]
[Authorize(Roles = "Admin")]
[ValidateAntiForgeryToken]
public async Task<ActionResult> Edit(EditUserViewModel model)
{
if (ModelState.IsValid)
    {
        var Db = new ApplicationDbContext();
        var user = Db.Users.First(u => u.UserName == model.UserName);
// Update the user data:
        user.FirstName = model.FirstName;
        user.LastName = model.LastName;
        user.Email = model.Email;
        Db.Entry(user).State = System.Data.Entity.EntityState.Modified;
        await Db.SaveChangesAsync();
return RedirectToAction("Index");
    }
// If we got this far, something failed, redisplay form
return View(model);
}

In the above, we use Linq to grab a reference to the specific user based on the UserName passed in as the id parameter in the first (GET) Edit method. We then populate an instance of EditUserViewModel by passing the ApplicationUser Instance to the constructor, and pass the ViewModel on to the Edit.cshtml View.

When the View returns our updated model to the second (POST) Edit method, we do much the same in reverse. We retrieve the User record from the database, then update with the model data, and save changes.

In our View, it will be important to remember that we cannot allow editing of the UserName property itself (at least, not under our current model, which considers the UserName to be an inviolate identifier).

Adding the AccountController Delete Method

---

We are adding a Delete (GET) method and a DeleteConfirmed (POST) method to the AccountController class. In my implementation, this method will actually delete the selected user from the database. You may decide instead to flag the database record as deleted, or implement some other method of managing unwanted user records.

You might also forego a delete method, and instead add a Boolean Inactive property to the ApplicationUser class, and manage Active/Inactive status through the Edit method discussed previously. Again, there are many permutations to the design model here. I went with the simplest for the sake of clarity.

The Delete method implementation here is straightforward so long as we remember, once again, that the id parameter passed to each of the two related methods below is actually a UserName.

The New Delete Methods:

[Authorize(Roles = "Admin")]
public ActionResult Delete(string id = null)
{
    var Db = new ApplicationDbContext();
    var user = Db.Users.First(u => u.UserName == id);
    var model = new EditUserViewModel(user);
if (user == null)
    {
return HttpNotFound();
    }
return View(model);
}
[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
[Authorize(Roles = "Admin")]
public ActionResult DeleteConfirmed(string id)
{
    var Db = new ApplicationDbContext();
    var user = Db.Users.First(u => u.UserName == id);
    Db.Users.Remove(user);
    Db.SaveChanges();
return RedirectToAction("Index");
}

As we can see, the DeleteConfirmed method is decorated with a HttpPost attribute, and an ActionName attribute "Delete" which means POST requests routed to Delete will be routed here. Both methods use the UserName passed as the id parameter to look up the appropriate ApplicationUser in the database.

Once again, in contrast to what I said earlier, I re-used the EditUserViewModel to pass to the Delete.cshtml View.

Adding the UserRoles Method to the AccountController

---

Lastly, we add the UserRoles method pair. This is where we manage assignment of user accounts to various application roles.

The implementation here looks relatively simple, and pretty similar to the other controller methods we have examined so far. However, under the hood in the SelectUserRolesViewModel and in the IdentityManager class, there is a lot going on. First, the code:

The New UserRoles Method(s):

[Authorize(Roles = "Admin")]
public ActionResult UserRoles(string id)
{
    var Db = new ApplicationDbContext();
    var user = Db.Users.First(u => u.UserName == id);
    var model = new SelectUserRolesViewModel(user);
return View(model);
}
[HttpPost]
[Authorize(Roles = "Admin")]
[ValidateAntiForgeryToken]
public ActionResult UserRoles(SelectUserRolesViewModel model)
{
if(ModelState.IsValid)
    {
        var idManager = new IdentityManager();
        var Db = new ApplicationDbContext();
        var user = Db.Users.First(u => u.UserName == model.UserName);
        idManager.ClearUserRoles(user.Id);
foreach (var role in model.Roles)
        {
if (role.Selected)
            {
                idManager.AddUserToRole(user.Id, role.RoleName);
            }
        }
return RedirectToAction("index");
    }
return View();
}

As we can see above, and incoming GET request routed to the UserRoles method is handled similarly to those in previous methods. The UserName passed as the id parameter is used to retrieve the User record from the database, and then an instance of SelectUserRolesViewModel is initialized, passing the ApplicationUser instance to the constructor.

Here is where things get interesting. Let's take another look at the code for our SelectUserRolesViewModel from the AccountViewModels.cs file:

Code for SelectUserRolesViewModel – Revisited:

publicclass SelectUserRolesViewModel
{
public SelectUserRolesViewModel() 
    {
this.Roles = new List<SelectRoleEditorViewModel>();
    }
// Enable initialization with an instance of ApplicationUser:
public SelectUserRolesViewModel(ApplicationUser user) : this()
    {
this.UserName = user.UserName;
this.FirstName = user.FirstName;
this.LastName = user.LastName;
        var Db = new ApplicationDbContext();
// Add all available roles to the list of EditorViewModels:
        var allRoles = Db.Roles;
foreach(var role in allRoles)
        {
// An EditorViewModel will be used by Editor Template:
            var rvm = new SelectRoleEditorViewModel(role);
this.Roles.Add(rvm);
        }
// Set the Selected property to true for those roles for 
// which the current user is a member:
foreach(var userRole in user.Roles)
        {
            var checkUserRole = 
this.Roles.Find(r => r.RoleName == userRole.Role.Name);
            checkUserRole.Selected = true;
        }
    }
publicstring UserName { get; set; }
publicstring FirstName { get; set; }
publicstring LastName { get; set; }
public List<SelectRoleEditorViewModel> Roles { get; set; }
}

During initialization, we are populating a List<SelectRoleEditorViewModel>() with all the roles available in the application. First,this is a prime candidate for refactoring, as I am performing  data access within the object constructor (a general no-no). Second, SelectRoleEditorViewModel? What?

In my current implementation, we will see that the SelectUserRolesViewModel is passed to the UserRoles.cshtml view. We want to display the basic user details (so we know which user we are assigning roles to – always important to know), as well as a list of all available Roles. I have decided to facilitate role assignment using checkboxes, whereby roles are assigned to the user by checking one or more (or none!) checkboxes.

This is where the EditorViewModel comes in.

Let's revisit the code for SelectRoleEditorViewModel, which we defined in our AccountViewModels.cs file.

The SelectRoleEditorViewModel represents an individual role, and as we can see from the following code, includes a Boolean field used to indicate the Selected status for that role:

Code for SelectRoleEditorViewModel, Revisited:

publicclass SelectRoleEditorViewModel
{
public SelectRoleEditorViewModel() { }
public SelectRoleEditorViewModel(IdentityRole role)
    {
this.RoleName = role.Name;
    }
publicbool Selected { get; set; }
    [Required]
publicstring RoleName { get; set; }
}

This EditorViewModel will be used by a special View called an EditorTemplate, which we will look at shortly. For now, bear in mind that the SelectUserRolesViewModel contains a List of SelectRoleEditorViewModel objects (yes, the naming of these could be better and posed some challenges – I am open to suggestion here! For the moment, I try to think of them as "SelectUserRoles-ViewModel" and "SelectRole-EditorViewModel" if that helps).

That covers the modified or new items in our AccountController. Now let's look at our Views.

Basic Views for Role-Based Identity Management

---

We already have a few of the views we will need, we just need to modify them a bit. In addition, we need to add a few new ones. We'll start by modifying our existing views to suit our needs, beginning with the Register.cshmtl View.

Modifying the Register.cshtml View File

---

The Register view as it currently sits was designed to allow user self-registration. As we have co-opted the Register method on the AccountController for restricted administrative use, so we will co-opt the Register.cshtml View for our purposes.

Essentially, all we need to do is add some additional HTML and Razor-Syntax code to the file to accommodate the new properties we added to our ApplicationUser class:

Modifying the Register.cshtml File:

@model AspNetRoleBasedSecurity.Models.RegisterViewModel
@{
    ViewBag.Title = "Register";
}
<h2>@ViewBag.Title.</h2>
@using (Html.BeginForm("Register", "Account", FormMethod.Post, new { @class = "form-horizontal", role = "form" }))
{
    @Html.AntiForgeryToken()
<h4>Create a new account.</h4>
<hr />
    @Html.ValidationSummary()
<div class="form-group">
        @Html.LabelFor(m => m.UserName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.UserName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.Password, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.PasswordFor(m => m.Password, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.ConfirmPassword, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.PasswordFor(m => m.ConfirmPassword, new { @class = "form-control" })
</div>
</div>
// Add the LastName, FirstName, and Email Properties:
<div class="form-group">
        @Html.LabelFor(m => m.LastName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.LastName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.FirstName, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.FirstName, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
        @Html.LabelFor(m => m.Email, new { @class = "col-md-2 control-label" })
<div class="col-md-10">
            @Html.TextBoxFor(m => m.Email, new { @class = "form-control" })
</div>
</div>
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" class="btn btn-default" value="Register" />
</div>
</div>
}

Next, we will create our edit view. To do this, we can right-click on the Edit Action method declaration in AccountController and let VS do the work for us:

Create View for the Edit Method:

We next see the Add View Dialog. Choose the Edit template from the Template drop-down, and select the EditUserViewModel class from the Model Class drop-down. We already have a data context, so leave that blank.

Add View Dialog:

Repeat the process above for the Delete and Index methods. Choose the appropriate template for each (use the List template for the Index View, as we want to display a list of User Accounts), and use EditUserViewModel as the Model Class for both.

Fine-Tuning the Index View

---

We need to make a few minor changes to our index view.

Notice near the bottom, where the template has provided handy links for Edit, Details, and Delete. We will change the "Details" link to instead point to our UserRoles Action method. Also, we need to replace the commented out route parameters such that the Username is passed as the id Parameter.

Lastly, up near the top of the file the is some razor code for an Action link to create a new user. Replace the Action method parameter "Create" with our co-opted "Register" method.

After our modifications, the final Index.cshtml file should look like this:

Modified Index.cshtml File:

@model IEnumerable<AspNetRoleBasedSecurity.Models.EditUserViewModel>
@{
    ViewBag.Title = "Index";
}
<h2>Index</h2>
<p>
    @Html.ActionLink("Create New", "Register") 
</p>
<table class="table">
<tr>
<th>
            @Html.DisplayNameFor(model => model.UserName)
</th>
<th>
            @Html.DisplayNameFor(model => model.FirstName)
</th>
<th>
            @Html.DisplayNameFor(model => model.LastName)
</th>
<th>
            @Html.DisplayNameFor(model => model.Email)
</th>
<th></th>
</tr>
@foreach (var item in Model) {
<tr>
<td>
            @Html.DisplayFor(modelItem => item.UserName)
</td>
<td>
            @Html.DisplayFor(modelItem => item.FirstName)
</td>
<td>
            @Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
            @Html.DisplayFor(modelItem => item.Email)
</td>
<td>
            @Html.ActionLink("Edit", "Edit", new { id = item.UserName }) |
            @Html.ActionLink("Roles", "UserRoles", new { id = item.UserName }) |
            @Html.ActionLink("Delete", "Delete", new { id = item.UserName })
</td>
</tr>
}
</table>

Now we can get back to that whole User Roles issue.

Create the UserRoles.cshtml View

---

We can use the VS Add View method to create our UserRoles.cshtml View as we did with the previous views. However, we will be doing most of our work from scratch on this one. Right-Click on the UserRoles method of AccountController and select Add View. This time, however, choose the Empty template option from the Template drop-down, and choose SelectUserRolesViewModel from the Model Class drop-down.

You should now have a mostly empty UserRoles.cshtml file the looks like this:

The Empty UserRoles.cshtml File:

@model AspNetRoleBasedSecurity.Models.SelectUserRolesViewModel
@{
    ViewBag.Title = "UserRoles";
}
<h2>UserRoles</h2>

From here, we will add our code manually. We want to display the basic user information, followed by a list of the available roles to which the user can be assigned (or removed). We want the list of roles to feature checkboxes as the selection mechanism.

To accomplish the above, we will add our Razor code as follows:

Added Code to the UserRoles.cshtml File:

@model AspNetRoleBasedSecurity.Models.SelectUserRolesViewModel
@{
    ViewBag.Title = "User Roles";
}
<h2>Roles for user @Html.DisplayFor(model => model.UserName)</h2>
<hr />
@using (Html.BeginForm("UserRoles", "Account", FormMethod.Post, new { encType = "multipart/form-data", name = "myform" }))
{
    @Html.AntiForgeryToken()
<div class="form-horizontal">
        @Html.ValidationSummary(true)
<div class="form-group">
<div class="col-md-10">
                @Html.HiddenFor(model => model.UserName)
</div>
</div>
<h4>Select Role Assignments</h4>
<br />
<hr />
<table>
<tr>
<th>
                    Select
</th>
<th>
                    Role
</th>
</tr>
            @Html.EditorFor(model => model.Roles)
</table>
<br />
<hr />
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</div>
</div>
}

In the above, we have set up a display header featuring the UserName, and created an HTML Table with header elements for Select and Role. The Select column will contain the checkboxes for each role, and the Role column will, obviously, display the Role names.

Below the table header set up, notice the line:

@Html.EditorFor(model => model.Roles)

This is where we return to that EditorTemplate concept. An Editor template is a Shared View, and needs to be located in the Views => Shared => EditorTemplates folder in your project. You may need to create the folder yourself.

Create the SelectRoleEditorViewModel Editor Template by right-clicking on your new EditorTemplates folder and selecting Add View. Use the Empty template again, and name the view SelectRoleEditorViewModel (this is important). Choose SelectRoleEditorViewModel from the Model Classes drop-down. When you are done you should have a .cshtml file that looks like this:

The Empty SelectRoleEditorViewModel Editor Template File:

@model AspNetRoleBasedSecurity.Models.SelectRoleEditorViewModel
@{
    ViewBag.Title = "SelectRoleEditorViewModel";
}
<h2>SelectRoleEditorViewModel</h2>

From here, we will add a few lines, so that our file looks like this:

Modified SelectRoleEditorViewModel Editor Template File:

@model AspNetRoleBasedSecurity.Models.SelectRoleEditorViewModel
@Html.HiddenFor(model => model.RoleName)
<tr>
<td style="text-align:center">
        @Html.CheckBoxFor(model => model.Selected)
</td>
<td>
        @Html.DisplayFor(model => model.RoleName)
</td>
</tr>

Now we have an editor template for our SelectRoleEditorViewModel. The code in our UserRoles.cshtml View will use this template to render our list of roles, including the checkboxes. Selections made in the checkboxes will be reflected in our model and returned, with the Role name, to the controller when the form is submitted.

Adding the Admin Tab to the Main Site Page

---

We are almost there. However, none of these new views and functionality do us much good if we can't get to it from within our application. We need to add an Admin tab to our main site page, and also remove the ability for anonymous users to access the registration link included on the site by default.

To do this, we need to modify the _Layout.cshtml file in the Views => Shared folder.

Modified _Layout.cshtml File

<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>@Html.ActionLink("Home", "Index", "Home")</li>
<li>@Html.ActionLink("About", "About", "Home")</li>
<li>@Html.ActionLink("Contact", "Contact", "Home")</li>
<li>@Html.ActionLink("Admin", "Index", "Account")</li>
</ul>
    @Html.Partial("_LoginPartial")
</div>

The code above is from just about the middle of the _Layout.cshtml View file. Add the highlighted line to create a tab link pointing to the Index method of our AccountController.

Remove the Register Link from the _LoginPartial.cshtml View

---

Last, we want to remove the link to the Register method from the main site layout. This link is found on the _LoginPartial.cshtml file, again located in the Views => Shared folder. At the bottom of this file, remove the code line highlighted below:

Remove the Register Link from _LoginPartial.cshtml:

else
{
<ul class="nav navbar-nav navbar-right">
<li>@Html.ActionLink("Register", "Register", "Account", routeValues: null, htmlAttributes: new { id = "registerLink" })</li>
<li>@Html.ActionLink("Log in", "Login", "Account", routeValues: null, htmlAttributes: new { id = "loginLink" })</li>
</ul>
}

Now all our views should be ready.

Set Up and Run Entity Framework Migrations

---

Now that we have most of the pieces in place, it's time to set up Code-First Migrations with Entity Framework. Also, because we are ostensibly building an application in which only users in an administrative role can create or edit users, we need to seed our application with an initial Admin user. Further, since we don't plan to allow creation or modification of roles, we need to seed the database with the roles we expect to use in our application, since we can't create them from within the application itself.

We covered EF Code-First Migrations fairly thoroughly in the previous article, so I am going to skim through it this time.

First, enable migrations by typing the following in the Package Manager Console:

Enable EF Migrations in Your Project:

PM> Enable-Migrations –EnableAutomaticMigrations

Now, open the Migrations => Configuration.cs file and add the following code (tune it up to suit your specifics. You probably don't want to add MY information as your admin user. Also note, whatever password you provide to start with must conform to the constraints of the application, which appears to require at least one capital letter, and at least one number:

Modify the EF Migrations Configuration File with Seed Data:

using AspNetRoleBasedSecurity.Models;
using System.Data.Entity.Migrations;
namespace AspNetRoleBasedSecurity.Migrations
{
using System;
using System.Data.Entity;
using System.Data.Entity.Migrations;
using System.Linq;
internalsealedclass Configuration : DbMigrationsConfiguration<ApplicationDbContext>
    {
public Configuration()
        {
            AutomaticMigrationsEnabled = true;
        }
protectedoverridevoid Seed(ApplicationDbContext context)
        {
this.AddUserAndRoles();
        }
bool AddUserAndRoles()
        {
bool success = false;
            var idManager = new IdentityManager();
            success = idManager.CreateRole("Admin");
if (!success == true) return success;
            success = idManager.CreateRole("CanEdit");
if (!success == true) return success;
            success = idManager.CreateRole("User");
if (!success) return success;
            var newUser = new ApplicationUser()
            {
                UserName = "jatten",
                FirstName = "John",
                LastName = "Atten",
                Email = "jatten@typecastexception.com"
            };
// Be careful here - you  will need to use a password which will 
// be valid under the password rules for the application, 
// or the process will abort:
            success = idManager.CreateUser(newUser, "Password1");
if (!success) return success;
            success = idManager.AddUserToRole(newUser.Id, "Admin");
if (!success) return success;
            success = idManager.AddUserToRole(newUser.Id, "CanEdit");
if (!success) return success;
            success = idManager.AddUserToRole(newUser.Id, "User");
if (!success) return success;
return success;
        }
    }
}