Tutorial

AfterCreate, AfterUpdate, AfterDelete, & AfterBinaryDelete

You may find a few more protected methods useful with respect to overriding:

• protected virtual AfterCreate(int id, EntityT entityItem, DetailMvcModelT mvcModelItem)
• protected virtual AfterUpdate(int id, EntityT entityItem, DetailMvcModelT mvcModelItem)
• protected virtual AfterDelete(int id, EntityT entityItem)
• protected virtual AfterBinaryDelete(int id, EntityT entityItem, DetailMvcModelT mvcModelItem)

These methods are called before a transaction closes. There are two common reasons to use these methods:

1. If you wish to make some final changes to the Entity before it gets created, updated, or deleted (another way to do it is to override the BeforeSave() method), and
2. If after updating/creating/deleting you wish to go to a different page than what the method redirects you to by default.

Another useful method for overriding is:

• protected virtual IQueryable<EntityT> GetItems( )

This method will get all items from whatever data source you're using. By default, it will get the items from the database using Entity Framework, but if you override this method to get items from some other source, you can easily change your controller to go against an XML file, for example, instead of the database. Another possible usage of this would be to introduce a filter. For example, if the controller is only supposed to work with the items that belong to the User that is currently logged-in, you could override this method to only return items that belong to the currently logged-in User:

protected override IQueryable<EntityT> GetItems()
{
	var currentUserId = ... 
//Get Id of User currently logged-in
	return base.GetItems().Where(x => x.CreatedBy.Id == currentUserId);
}

Note that when using AfterCreate( ), the Entity has not yet been fully created and saved yet, so the Id of the Entity will not yet exist. In some cases, this is exactly what you need because you might want to tweak the Model before it is saved (for example, by setting a CreatedBy property to the current logged-in user). On the other hand, if you need to know the Id of the Entity that is about to be created, it's important to use the UnitOfWorkContext to save your Entity before you use the Id. In the example below, we want to tell the User that their profile was successfully created through a pop-up and keep them on the screen they were just on by redirecting them to the Update Profile screen for the Id that was just created.

protected override ActionResult AfterCreate(int id, User EntityItem, UserMvcModel mvcModelItem)
{
	UnitOfWorkContext<MyFirstProjectDbContext>.CurrentDbContext.FinalSaveChanges();
	tempData.Supermodel().NextPageModalMessage = "User was created successfully!";
	var routeValues = HttpContext.Request.QueryString.Supermodel().ToRouteValueDictionary();
	return this.Supermodel().RedirectToActionStrong(x => x.Edit(EntityItem.Id, new HttpGet()), routeValues);
}

Supermodel requires you to preserve query string parameters from the List to the Detail pages and back. This is important if you have some searching, paging, and sorting parameters (see the section on Paging, Sorting, and Searching for more information) that control your List. If you do not preserve those query string parameters, when you are done with the Detail screen, your search/page/sort state will be lost. That is why we use var routeValues = HttpContext.Request.QueryString.Supermodel().ToRouteValueDictionary(); to grab the query string route values and pass them to the RedirectToActionStrong( ) method.

For two of the most frequently used cases of redirects, Supermodel provides shortcut methods on the base CRUD Controllers: StayOnDetailScreen( ) and GoToList( ). Therefore, the code snippet above could be simplified to the following:

protected override ActionResult AfterCreate(int id, User EntityItem, UserMvcModel mvcModelItem)
{
	UnitOfWorkContext<MyFirstProjectDbContext>.CurrentDbContext.SaveChanges();
	tempData.Supermodel().NextPageModalMessage = "User was created successfully!";
	
return StayOnDetailScreen(EntityItem);
}

If, on the other hand, you wanted the User to be redirected to the List View, you would use the GoToList( ) method:

protected override ActionResult AfterCreate(int id, User EntityItem, UserMvcModel mvcModelItem)
{
	UnitOfWorkContext<MyFirstProjectDbContext>.CurrentDbContext.SaveChanges();
	tempData.Supermodel().NextPageModalMessage = "User was created successfully!";
	
return GoToList();
}

StayOnDetailScreen( ) and GoToList( ) take care of preserving the query string parameters for you.

As you can see in these methods, UnitOfWorkContext allows you to access the CurrentDbContext and operate on it (for example, by calling the SaveChanges( ) method). For your convenience, Supermodel also exposes shortcut methods right on the UnitOfWorkContext that give you access to the most commonly used DbContext methods. For example, the code snippet above could be further simplified to:

protected override ActionResult AfterCreate(int id, User EntityItem, UserMvcModel mvcModelItem)
{
	
UnitOfWorkContext.SaveChanges();
	tempData.Supermodel().NextPageModalMessage = "User was created successfully!";
	return GoToList();
}

As mentioned in the UnitOfWorkContext Shortcuts section, UnitOfWorkContext provides the following shortcuts, all of which can also be accessed through DbContext:

• SaveChanges( )
• SaveChangesAsync( )
• FinalSaveChanges( )
• FinalSaveChangesAsync( )
• CommitOnDispose( )

If you wish to display a message after a User profile is updated but before redirecting to the next page, you can use the AfterUpdate( ) method. Note that you do not need to use the UnitOfWorkContext SaveChanges( ) method, as the User already exists in the database and its Id at this point is already set:

protected override ActionResult AfterUpdate(int id, User EntityItem, UserMvcModel mvcModelItem)
{
	TempData.Supermodel().NextPageModalMessage = “User was updated successfully!"
	
return this.AfterUpdate(EntityItem.Id, new HttpGet()));
}

Next Page Properties

You might be wondering what is underneath the NextPageModalMessage( ) method and how it works to display messages in the browser. Supermodel makes available three different NextPage properties:

• TempData.Supermodel().NextPageModalMessage
• TempData.Supermodel().NextPageAlertMessage
• TempData.Supermodel().NextPageStartupScript

• NextPageModalMessage is the same as TempData["sm-modalMessage"]
• NextPageAlertMessage is the same as TempData["sm-alertMessage"]
• NextPageStartupScript is the same as TempData["sm-startupScript"]

If you are using Twitter Bootstrap or JQuery Mobile, the Master Layout page will respect these TempData variables in the following way:

• If you have a NextPageModalMessage set, a Twitter Bootstrap or JQMobile ModalMessage dialog box is going to be shown with the message being the content of the NextPageModalMessage property.


• If you have a NextPageAlertMessage set, an JavaScript alert( ) will be shown with a message being the content of the NextPageAlertMessage property.


• If you have NextPageStartupScript set, a JQuery startup script will be executed when the next page loads. The script itself will be (you guessed it) the content of the NextPageStartupScript property.

If you're using a generic render (as opposed to Twitter Bootstrap or JQuery Mobile), these properties will not by default be wired up because there is no default MasterLayout. However, you can still use them and create your own MasterLayout that will respect those properties. For example, if you use Twitter Bootstrap and Bootbox, you might use the following in your MasterLayout.cshtml file:

@if (TempData.Supermodel().NextPageStartupScript != null) 
{ 
	<text> 
		@MvcHtmlString.Create(TempData.Supermodel().NextPageStartupScript.ToString()) 
	</text>
}
@if (TempData.Supermodel().NextPageAlertMessage != null)
{ 
	<text> 
		alert("@TempData.Supermodel().NextPageAlertMessage"); 
	</text> 
}
@if (TempData.Supermodel().NextPageModalMessage != null)
{ 
	<text> 
		bootbox.alert("@TempData.Supermodel().NextPageModalMessage"); 
	</text> 
}

Custom Rendering for a View

Within a Supermodel project, you can always create a normal custom View. For example, we can use @Html.EditorFor(x => x.PropertyName) type methods.

Even better, instead of using @Html.EditorFor, we can use @Html.Supermodel().EditorFor. This method does everything that the standard EditorFor method does, but in addition to it, it respects ISupermodelEditorTemplate, ISupermodelDisplayTemplate, and ISupermodelHiddenTemplate. For example:

@model QuoteMvcModel
@{
    Layout = "~/Views/Shared/MasterLayout.cshtml";
}
@using (Html.BeginForm())
{
	if (!Model.IsNewModel) 
	{
		@Html.HttpMethodOverride(HttpVerbs.Put)
	}
	
	<div>@Html.LabelFor(x => x.Username)</div>
	<div>@Html.Supermodel().EditorFor(x => x.Username)</div>
	
	<div>@Html.LabelFor(x => x.FirstName)</div>
	<div>@Html.Supermodel().EditorFor(x => x.FirstName)</div>
	
	<div>@Html.LabelFor(x => x.LastName)</div>
	<div>@Html.Supermodel().EditorFor(x => x.LastName)</div>
	
	<div>@Html.LabelFor(x => x.Age)</div>
	<div>@Html.Supermodel().EditorFor(x => x.Age)</div>
	
	<input type="button" value="Back" href="/User/List">
	<input type="submit" value="Submit"/>
}

This will result in a view that looks like the following:

@Html.Supermodel().EditorFor View

In the same way that @Html.Supermodel().EditorFor relies on the ISupermodelEditorTemplate, @Html.Supermodel().DisplayFor relies on the ISupermodelDisplayTemplate and @Html.Supermodel().HiddenFor relies on the ISupermodelHiddenTemplate.

For DRYer code, we can take advantage of the templates (in this case, we will be using ISupermodelEditorTemplate). Doing so will render all of the fields in our MVC Model. This way, when a property is added, removed, or changed, there is no need to update the View. For example, if we were to customize our Detail View for the QuoteMvcModel, we could do the following:

@model QuoteMvcModel
@{
    Layout = "~/Views/Shared/MasterLayout.cshtml";
}
@using (Html.BeginForm())
{
	if (!Model.IsNewModel) 
	{
		@Html.HttpMethodOverride(HttpVerbs.Put)
	}
	
	
@Model.EditorTemplate(Html)
	
	<input type="button" value="Back" href="/User/List">
	<input type="submit" value="Submit"/>
}

Using the Editor Template

We can also replace the header and footer of the above code so that it looks like the following:

@model QuoteMvcModel
@{
    Layout = "~/Views/Shared/MasterLayout.cshtml";
}
@(Html.Supermodel().TweeterBS.CRUDEditHeader<Quote, QuoteMvcModel>())
@Model.EditorTemplate(Html)
@(Html.Supermodel().TweeterBS.CRUDEditFooter<Quote, QuoteMvcModel>())

Using CRUDEditHeader and CRUDEditFooter eliminates the need for us to create own "Back" and "Submit" buttons as well as the need to specify the beginning of an HTML form. Additionally, by using the TweeterBS HTML extension, our buttons and textfields will have the look and feel of a standard Twitter Bootstrap application:

Using the Editor Template with CRUDEditHeader and CRUDEditFooter

As you may have noticed, our View is equivalent to the View generated by:

@(Html.Supermodel().TweeterBs.CRUDEdit<Quote, QuoteMvcModel>())

For further customization, we can add our own HTML and use ScreenOrder parameters to choose where to place fields on the screen. First, we will need to go into the UserMvcModel to specify the ScreenOrder attribute of the properties. If the ScreenOrder attribute is not specified, it is implicitly assumed to be "100." Properties with the same ScreenOrder are rendered in the order in which they are listed within the class.

For example, let's specify the screen order for the Quotation field to be below that of the Author field.

public class QuoteMvcModel : TweeterBS.ChildMvcModelForEntity<Quote, User>
{
	[
ScreenOrder(300)
, ListColumn, Required] public TweeterBS.TextBoxForStringMvcModel Quotation { get; set; }
	[
ScreenOrder(200)
, ListColumn, Required] public TweeterBS.TextBoxForStringMvcModel Author { get; set; }
	
	public override string Label { get { "'" + Quotation.Value + "'" + " - " + Author.Value; } }
	
	public override User GetParentEntity(Quote Entity)
	{
		return Entity.ParentUser;
	}
	
	public override void SetParentEntity(Quote Entity, User parent)
	{
		Entity.ParentUser = parent;
	}
}

As expected, the Author field now appears before the Quotation field:

Using the Editor Template with CRUDEditHeader and CRUDEditFooter

The ScreenOrder attribute is particularly useful when using inheritance, allowing us to order fields coming from base classes and derived classes in any way we want.

@model QuoteMvcModel
@{
    Layout = "~/Views/Shared/MasterLayout.cshtml";
}
@(Html.Supermodel().TweeterBs.CRUDEditHeader<Quote, QuoteMvcModel>())
@Model.EditorTemplate(Html, 200, 200)
<div>This is some custom HTML</div>
@Model.EditorTemplate(Html, 300, 300)
@(Html.Supermodel().TweeterBS.CRUDEditFooter<Quote, QuoteMvcModel>())

And, as you can see above, we can also insert our own custom HTML code on the screen.

Screen Order and Custom HTML

Creating a Web API CRUD Service by Hand

Similarly to the MVC "world", Supermodel provides free CRUD for Web API as well. But before we delve into that, let's take a look at creating a very simple CRUD service by hand using Supermodel. First, the API Model for your Entity should inherit from an API Model base class. Just like in the Supermodel MVC "world", there is an ApiModel and ApiModelForEntity<>.

ApiModel implements the abstract class ViewModel without the Entity backing.

ApiModelForEntity<>, on the other hand, takes an Entity parameter and inherits from the ApiModelForAnyEntity class. ApiModelForEntity<> implements IValidatableObject and IRMapperCustom and it includes an Id property to match one on the Entity.

public class 
UserApiModel : ApiModelForEntity<User>
{
	[Required] public string Username { get; set; }
	public string FirstName { get; set; }
	public string LastName { get; set; }
	[Required] public int? Age { get; set; }
}

Web API Controllers

We will need to create a new API controller for our domain object in order to include Web API functionality. The convention is to place Web API Controllers in an APIControllers directory under your Web Project as opposed to the Controllers directory under the Web Project where your MVC Controllers reside. It is important to place API and MVC Controllers in separate directories (and therefore separate namespaces) because they are likely to have the same names. For example, below you'll see that in the folder ApiControllers and in the folder Controllers, there is a controller class called UserController.

Controllers vs. ApiControllers

url/NameOfObject/NameOfActionMethod/id

However, using Web API, your url will include an HTTP verb instead of a traditional Action Method:

url/api/NameOfObject/id

For more information, see ASP.NET Web API documentation.

Our updated controller will need to include methods for each HTTP verb (GET, DELETE, POST, and PUT):

public class UserController : ApiController
{
	public HttpResponseMessage Get(int id)
	{
		using (new UnitOfWork(ReadOnly.Yes))
		{
			var user = RepoFactory.Create<User>().GetById(id);
			var userApiModel = new userApiModel().MapFrom(user);
			return Request.CreateResponse(HttpStatusCode.OK, userApiModel);
		}
	}
	
	public HttpResponseMessage Delete(int id)
	{
		using (new UnitOfWork())
		{	
			var user = RepoFactory.Create<User>().GetById(id);
			user.Delete();
			return Request.CreateResponse(HttpStatusCode.OK);
		}
	}
	
	public HttpResponseMessage Post(UserApiModel userApiModel)
	{
		using (new UnitOfWork())
		{
			var user = userApiModel.MapTo(new User());
			user.Add();
			return Request.CreateResponse(HttpStatusCode.OK);
		}
	}
	
	public HttpResponseMessage Put(int id, UserApiModel userApiModel)
	{
		using (new UnitOfWork())
		{
			var user = userApiModel.MapTo(RepoFactory.Create<User>().GetById(id));
			return Request.CreateResponse(HttpStatusCode.OK);
		}
	}
}

In order to debug our Web API service, we will use a utility that's called Fiddler. Fiddler is an HTTP traffic analyzer, but it can also act as an HTTP Client. This is the role we are going to be using it in.

Now, we can run our API calls in Fiddler. Before we run our Web project though, let's go to Web properties (right-click Web and select properties). Under the tab "Web", select the option "Don't open a page. Wait for a request from an external application." This way, a web browser won't open when we start our Web project. Also, in the properties window, note that you can see what your localhost port number is (you will need this port number in Fiddler).

Let's go ahead and run our Web project and open Fiddler. We can write our first API request under the Composer tab. Let's try running a GET to return the User with an Id of 1. To do so, we will select our HTTP Verb from the dropdown menu and then type in the following to the text field: "http://localhost:#####/api/User/1". Remember to replace ##### with your localhost port number.

Get User with Id of 1 in Fiddler

Click "Execute". You'll notice on the left side of the Fiddler window a list of results. A result of "200" signifies the HTTP status code for "Success," and, in our case, a successful return of the data from the API call.

Fiddler Result List

If we click on the result, we'll see our User with Id "1" returned in JSON format:

Success! User with Id "1"

Let's try a few more API calls while we're at it. Let's try updating Jane Doe's information by using a PUT. We'll change her age from 99 to a more youthful 20. First, change the HTTP Verb to "PUT". Our URL will remain the same.

Updating User Jane Doe's Age with PUT

Then, in our header, we must specify the Content-Type of our Request Body. We'll pass our updated data in JSON format, so we'll add "Content-Type: application/json":

Updating the Header in Fiddler

Finally, we'll need to add our updated data about Jane Doe to the Request Body:

Updating the Request Body in Fiddler

Now, if we execute our request, we should get a 200 HTTP status code as a result.

Success!

And sure enough, if we look at the User table in our database, we'll see that Jane's age has been updated there, too:

Updated Database

Now, let's try deleting Jane from our database. Remember to change the HTTP verb in the dropdown to DELETE. When we do this, the Request Body section will turn red. We'll go ahead and delete the text from the Request Body.

Delete Jane

Go ahead and click "Execute". Once again, you should get a 200 HTTP status code. If we look in our database, we'll see that Jane no longer exists:

Jane No Longer Exists in the Database

Finally, we can also add Users to our database through the HTTP verb POST. Now that we've deleted Jane, let's try adding her back to the database as a new User. First, change the HTTP verb in the dropdown to POST. Then, in the URL, remove the Id "1" (a new User won't have an Id yet).

Updating the HTTP Verb and URL for a POST

In the Request Body, we'll need to pass the information about our new User in JSON format (also make sure that in the Header you've specified "Content-Type: application/json"). We must give our new User an Id of 0, or else we'll get an error.

Updating the Request Body

Once we execute this API call and receive a 200 HTTP status code, we can look in our database and see that Jane Doe has been added as a new User.

And She's Back!

From the above, you just saw how easy it is to create a rudimentary custom CRUD Web API service. However, with Supermodel, we can do even better than that, and have completely free CRUD in the context of Web API just like we have free CRUD in the context of MVC. The free CRUD that we get with Supermodel base controllers is actually a lot more sophisticated with built-in validation, paging, sorting, and querying.

There are eight API controllers you can choose from depending on your application's needs. There are really just two controllers, but with four flavors each just like in MVC (sync vs. async and single API Model vs. separate List and Detail API Models): CRUD controller and Enhanced CRUD Controller.

In general, CRUD API Controllers mirror the CRUD MVC Controllers, having a simple CRUD Controller family with four controllers, and an Enhanced CRUD Controller family with four controllers. But there are a few notable differences:

• There is no such thing as Child API CRUD Controllers. API Models, unlike MVC Models, are usually not "flat". Therefore the root Model is likely to include the collection of Child Models without the need for them to be a special type.
• Unlike in the MVC world, simple API CRUD Controllers include paging. This was done in order to accomodate consuming large amounts of data. This way a client can ask for that data in chunks.
• API CRUD Controllers, in addition to the standard methods that you would expect, API CRUD Controllers include Count methods. For example, you can ask for a count of all records or a count of records that satisfy a certain query.

Simple API CRUD Controllers

Enhanced API CRUD Controllers

Using an ApiCRUDController, you can do all of the things our very simple ApiController did, but without doing any of the work because it comes with default implementations for the HTTP Verbs GET, PUT, POST, and DELETE. For example, we could have an AsyncApiCRUDController like the following:

public class UserController : AsyncApiCRUDController<User, UserApiModel, MyFirstProjectDbContext> {}

Let's try running the same GET method we ran earlier, but instead of the User with an Id of 1 (which no longer exists since we deleted and created a new Jane Doe), we'll get the User with an Id of 2:

Getting User with Id 2

Getting User with Id 2

As you can see, our UserController works just as it did before, but it comes with default implementations for the HTTP Verb methods. In addition, we can now use the CountAll method to return the number of Users in the database. Let's try the CountAll method in Fiddler:

CountAll in Fiddler

As expected, this method returns 8, the number of Users we currently have in the database.

CountAll in Fiddler

Adding Validation to an Entity in Web API

Just like with MVC models, you can choose where to put the validation for your application. If you want the validation logic to apply to all Users over all aspects of the application and in any UI for the application, you should put the the validation in the Entity object. However, if you want the validation logic to apply to only those controllers that use a certain API Model, you should add the validation to the Model.

Let's add the validation logic to our User Entity so that no User under 21 years of age can be added to the system.

public class User : Entity
{
	
public override IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
	{
		var vr = (ValidationResultList)base.Validate(validationContext) ?? new ValidationResultList();
		if (Age < 21) vr.AddValidationResult(this, x => x.Age, "Must be of legal drinking age");
		return vr;
	}
	
	[Required] public string Username { get; set; }
	public string FirstName { get; set; }
	public string LastName { get; set; }
	[Required] public int? Age { get; set; }
}

Now, if we try to update the age property of one of the Users in our system to be 19 years old, we will get an error. For example, let's attempt to change John Doe's age to 19:

Updating John Doe's Age to 19

When we execute the API call in Fiddler, we will receive an HTTP Status code of 417: Expectation Failed.

HTTP Status Code for Validation Error

And if we look at the returned JSON, we will see that the error message we created for our age validation method, "Must be of legal drinking age," was returned.

Returned JSON for Validation Error

Adding Searching, Sorting, and Paging to the Web API

You can add searching, sorting, and paging functionality by adding a SearchApiModel for your Entity and modifying your controller to be an Enhanced API CRUD Controller:

We'll add a new Search API Model for our User Entity. Let's create some new fields, FromAge and ToAge to find Users in a certain age range.

public class UserSearchApiModel : SearchApiModel
{
	public string Username { get; set; }
	public string FirstName { get; set; }
	public string LastName { get; set; }
	public int? FromAge { get; set; }
	public int? ToAge { get; set; }
}

Now we must change the UserController from a simple API CRUD controller to an Enhanced API CRUD Controller, which comes with built-in searching, sorting, and paging capabilities.

namespace Web.ApiControllers
{
	public class UserController : AsyncEnhancedApiCRUDController<User, UserApiModel, UserSearchApiModel, MyFirstProjectDbContext>
}

By default, our controller will know how to do paging and simple sorting. However, we still need to tell it how to do searching. You can do this by overriding the ApplySearchBy( ) method.

namespace Web.ApiControllers
{
	public class UserController : AsyncEnhancedApiCRUDController<User, UserApiModel, UserSearchApiModel, MyFirstProjectDbContext>
	{
		protected override IQueryable<User> ApplySearchBy(IQueryable<User> items, UserSearchApiModel searchBy)
		{
			if (!string.IsNullOrEmpty(searchBy.FirstName)) 
			{
				items = items.Where(x => x.FirstName.ToLower().Contains(searchBy.FirstName.ToLower()));
			}
			
			if (!string.IsNullOrEmpty(searchBy.LastName))
			{
				items = items.Where(x => x.LastName.ToLower().Contains(searchBy.LastName.ToLower()));
			}
            
			if (!string.IsNullOrEmpty(searchBy.Username))
			{ 
				items = items.Where(x => x.Username.ToLower().Contains(searchBy.Username.ToLower()));
			}
            
			if (searchBy.FromAge != null) items = items.Where(x => x.Age >= searchBy.FromAge);
			if (searchBy.ToAge != null) items = items.Where(x => x.Age <= searchBy.ToAge);
			return items;
		}
	}
}

To run a search, you will use the GET API call in Fiddler. Try running a search to find all the Users whose first names contain the letter "J":

Search for Users with a First Name that Contains the Letter "J"

Our database has two Users whose first names contain the letter "J", John Doe and Jane Doe. Our returned JSON data reflects this.

Search for Users with a First Name that Contains the Letter "J"

Now, try running a search using the FromAge and ToAge properties.

Search for Users with Ages Between 50 and 100

There are two Users whose ages fit the bill: Doctor Jeckyll and Sherlock Holmes, 55 and 58 years of age, respectively. This is accurately reflected in the JSON data that is returned.

Search for Users with Ages Between 50 and 100

We can also sort our search results using Fiddler. Let's sort the Users between the ages of 50 and 100 by their last name by tacking the query "smSortBy=LastName" onto our URL:

Sorting by Last Name

Now, the Users returned by our query are sorted by last name in the returned JSON data:

Sorting By Last Name

Adding Authorization and Authentication to your Web API

In order to prevent users from accessing things they should not be able to access, you can implement authorization and authentication in your Web API application.

Microsoft provides a very convenient authorization mechanism for Web API that works much the same way that it works in MVC, through the [Authorize] attribute and an optional RoleProvider. For more information on how this works, please see Microsoft's documentation.

Web API Authentication, on the other hand, is a different story. If you are using your Web Service in an AJAX application, your authentication is taken care of by (most likely) Web Forms Authentication that already exists for your web pages. In other words, if your User has logged-in to your website, the individual website pages that make AJAX calls to the server will pass along the session cookie that will authenticate you for the web server. However, if you are writing a mobile application, or if you have two servers talking to each other using web services, using Web Forms Authentication is not an option. For those scenarios, Supermodel offers several solutions based on industry standards.

Authentication in Web API can be done through Basic Authentication. Basic Authentication uses what's called an Authorization Header. The information contained within the Authorization Header is a Base-64 encoding of your login credentials in the format Authorization: Basic username : password.

Let's try to authorize a controller without any authentication:

namespace Web.ApiControllers
{
	
[Authorize]
	public class UserController : AsyncEnhancedApiCRUDController<User, UserApiModel, UserSearchApiModel, MyFirstProjectDbContext>
	{
		protected override IQueryable<User> ApplySearchBy(IQueryable<User> items, UserSearchApiModel searchBy)
		{
			if (!string.IsNullOrEmpty(searchBy.FirstName)) 
			{
				items = items.Where(x => x.FirstName.ToLower().Contains(searchBy.FirstName.ToLower()));
			}
			
			if (!string.IsNullOrEmpty(searchBy.LastName))
			{
				items = items.Where(x => x.LastName.ToLower().Contains(searchBy.LastName.ToLower()));
			}
            
			if (!string.IsNullOrEmpty(searchBy.Username))
			{ 
				items = items.Where(x => x.Username.ToLower().Contains(searchBy.Username.ToLower()));
			}
            
			if (searchBy.FromAge != null) items = items.Where(x => x.Age >= searchBy.FromAge);
			if (searchBy.ToAge != null) items = items.Where(x => x.Age =< searchBy.ToAge);
			return items;
		}
	}
}

At this point, if we try to run an API call within Fiddler, we will receive an HTTP status code of 401: Unauthorized. This is because we haven't authenticated any Users yet, so we can't authorize them.

Unauthenticated User

In order to implement security on your server, we will create a folder in your Domain under "Supermodel" called "Auth". Within this folder, we'll add a class called "MyFirstProjectAuthenticateAttribute.cs". This class will derive from the Supermodel base class AuthenticateAttribute. AuthenticateAttribute is an abstract class, so we will need to implement the missing members within our class. There are three missing members, AuthenticateBasicAndGetIdEntityByName( ), AuthenticateEncryptedAndGetIdEntityName( ), and EncryptionKey. The second and third missing members are used for more advanced security, which will look at later. For Basic Authentication, just throw System.NotImplementedException() in those methods. We will implement the AuthenticateBasicAndGetIdEntityByName( ) shortly:

public class MyFirstProjectAuthenticateAttribute : AuthenticateAttribute
{
	protected override string AuthenticateBasicAndGetIdentityName(string username, string password) {}
	
	protected override string AuthenticateEncryptedAndGetIdentityName(string[] args, out string password)
	{
		throw new System.NotImplementedException();
	}
	
	protected override byte[] EncryptionKey
	{
		get { throw new NotImplementedException(); }
	}
}

In our UserController, let's add the second attribute [MyFirstProjectAuthenticate].

namespace Web.ApiControllers
{
	[Authorize, 
MyFirstProjectAuthenticate
]
	public class UserController : AsyncEnhancedApiCRUDController<User, UserApiModel, UserSearchApiModel, MyFirstProjectDbContext>
	{
		protected override IQueryable<User> ApplySearchBy(IQueryable<User> items, UserSearchApiModel searchBy)
		{
			if (!string.IsNullOrEmpty(searchBy.FirstName)) 
			{
				items = items.Where(x => x.FirstName.ToLower().Contains(searchBy.FirstName.ToLower()));
			}
			if (!string.IsNullOrEmpty(searchBy.LastName))
			{
				items = items.Where(x => x.LastName.ToLower().Contains(searchBy.LastName.ToLower()));
			}
			if (!string.IsNullOrEmpty(searchBy.Username))
			{ 
				items = items.Where(x => x.Username.ToLower().Contains(searchBy.Username.ToLower()));
			}
			
			if (searchBy.FromAge != null) items = items.Where(x => x.Age >= searchBy.FromAge);
			if (searchBy.ToAge != null) items = items.Where(x => x.Age =< searchBy.ToAge);
			return items;
		}
	}
}

For simplicity's sake, we'll go ahead and hardcode this information into our AuthenticateBasicAndGetIdentityName( ) method in our MyFirstProjectAuthenticateAttribute class:

public class MyFirstProjectAuthenticateAttribute : AuthenticateAttribute
{
	protected override string AuthenticateBasicAndGetIdentityName(string username, string password)
	{
		
if (username == "Aladdin" && password == "open sesame") return "1";
		return null;
	}
	
	protected override string AuthenticateEncryptedAndGetIdentityName(string[] args, out string password)
	{
		throw new System.NotImplementedException();
	}
	
	protected override byte[] EncryptionKey
	{
		get { throw new NotImplementedException(); }
	}
}

AuthenticateBasicAndGetIdentityName( ) and AuthenticateEncryptedAndGetIdentityName( ) methods return null if the User can not be authenticated, or return a string that will be used by Windows as the Principal Identity of the logged-in User. It is common to return the integer Id converted to string for the User in the database. For this hardcoded example, we're just returning "1".

To add an authenticated User, we'll use the following Authorization Header and paste it into the header on Fiddler:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Encoded in the above header is the Username "Aladdin" and the Password "open sesame".

Authorization Header in Fiddler

Now, if you run an API call in Fiddler, it will return a 200 HTTP Success code and return the data from the API call.

Also, any CRUD API controller will have a ValidateLogin method. Let's try using the ValidateLogin method if we don't have an AuthHeader:

ValidateLogin if No AuthHeader

As expected, we receive a 401: Unauthorized response:

ValidateLogin 401 Unauthorized Response

However, if we add the AuthHeader, our ValidateLogin method should work:

ValidateLogin with AuthHeader

And, as we predicted, we receive a 200 HTTP success response:

ValidateLogin Success

ValidateLogin( ) is particularly useful in mobile apps that need to validate credentials to log in the users without performing any other operation.

Since it could get tiresome to add the MyFirstProjectAuthenticate attribute to every controller, there is a way to streamline this. You can do this by going into your Global.asax file and adding a parameter to your SupermodelInitialization.Init( ) method called webApiAuthFilter. This way, all Web API methods will authenticate using this filter. They may or may not allow an anonymous user still. That would be determined by whether or not the authorization is required.

public class Global : HttpApplication
{
	void Application_Start(object sender, EventArgs e)
	{
		
//Code that runs on application startup
		AreaRegistration.RegisterAllAreas();
		
		
SupermodelInitialization.Init<MyFirstProjectDbContext>(webApiAuthFilter: new MyFirstProjectAuthenticateAttribute());
		InitializerManager.InitPerConfig(new List<IDatabaseInitializer<MyFirstProjectDbContext>>
		{
			new MyFirstProjectCreateDatabaseIfNotExists(),
			new MyFirstProjectDropCreateDatabaseIfModelChanges(), 
			new MyFirstProjectDropCreateDatabaseAlways()
		});
	}
}

Batch Processing

Batch processing makes it easier to create Enterprise Systems (large-scale systems) with Web API. Supermodel gives you a mechanism to create batch jobs, which are a combination of different Web API operations that are submitted in one HTTP request and treated by the server as one transaction. This means that batch processing is an all-or-nothing operation: either all of the Web API operations succeed or they all fail.

Supermodel implements an industry emerging standard for batch processing using HTTP multicast.

Let's walk through batch processing usage.

We'll need to specify a few things in our header in Fiddler. First, our Content-Type will be "multipart/mixed;". We also need to specify the boundary, which is a long string of characters that is unique and will be used as an escape character for your request.

Batch Processing Header Modifications in Fiddler

We also need to update our HTTP request. Our HTTP Verb needs to be changed to POST and URL will point to api/$batch. All batch requests will be posted to this URL. This is an emerging industry standard that Supermodel followed.

Batch Processing HTTP Request

Finally, we need to update the Request Body in Fiddler. The Request Body should be formatted like so:

--boundary string
Content-Type: application/http; msgtype=request

GET /api/User/Query HTTP/1.1
Host: localhost:#####


--boundary string
Content-Type: application/http; msgtype=request

GET /api/User/AnotherQuery HTTP/1.1
Host: localhost:#####


--boundary string--

Note that spacing is important for the batch process to execute correctly. Furthermore, you don't have to stop at two requests. In fact, you can have an unlimited number of requests. Below is an example of an actual Request Body for a batch process:

Batch Processing Request Body

When we execute the batch processing request, the following raw data is returned to us:

Batch Processing Raw Data

As you can see, we were returned the Users with Ids 5 and 7, as requested.

You can have any number of requests in a batch and the action methods for those don't need to be written in any special way.

Creating a Client for your Web Service

Let's create a command line utility that will communicate with our web service. Before getting started, it should be noted that there is no such thing as synchronous Web API calls on the client. This is because the new HttpClient class by Microsoft only allows async. Besides, it would be a very bad practice to make HTTP calls in a blocking way.

To start, add a new Console Application project within your project directory called "HttpClientCmd". This program will be what communicates with our web service.

Then, create a Util directory within your project. Add a new Console Application project under Util called "ModelGenerator", which is a program that will generate the models for our web service. For both HttpClientCmd and ModelGenerator, you will need to reference the WebProject, ReflectionMapper, and Supermodel. In addition, add the NuGet packages Entity Framework, JSON.NET, MVC, and WebAPI to both projects.

Within "ModelGenerator", write the following code:

namespace ModelGenerator
{
	class Program
	{
		static void Main()
		{
			var modelGenerator = new Supermodel.Mobile.Xamarin.ModelGenerator(typeof (UserController).Assembly);
			var modelsCS = modelGenerator.GenerateModels();
			File.WriteAllText(@"..\..\" + "Supermodel.Mobile.ModelsAndRuntime.cs", modelsCS.ToString());
			File.WriteAllText(@"..\..\..\HttpClientCmd\Supermodel.Mobile.ModelsAndRuntime.cs", modelsCS.ToString());
		
			Console.WriteLine("All done! Press enter.");
			Console.ReadLine();
		}
	}
}

In the above code snippet, Supermodel will inspect the Web API (that belongs in the assembly that we passed to the ModelGenerator. In this case: typeof (UserController).Assembly.) and generate Models and runtime libraries. You should set this up to copy new models and rumtime to any project that needs an HTTP Client and you should rerun this command line utility to regenerate your Models every time you change your Web API on the server. When you run the ModelGenerator code, a new file called Supermodel.ModelsAndRuntime.cs will be created under both the HttpClientCmd and the ModelGenerator directory.

In your Solution Explorer, you will need to select "Show All Files" before the new files appear. Right-click on each of these files and select "Include in Project". We only want Supermodel.ModelsAndRuntime.cs to compile in HttpClientCmd, so under ModelGenerator, right-click Supermodel.ModelsAndRuntime.cs and select Properties. Next to the section Build Action, select "None".

Within this file are two regions: Models and Supermodel.Mobile.Runtime. Within the Models region, you will find that the Models for your Entity, as well as all dependent classes and enums, have been generated and are grouped by their respective controllers. The Supermodel.Mobile.Runtime region contains a runtime library for your Web Service client application.

At the top of the Supermodel.ModelsAndRuntime.cs file, you will see a section called Project Setup Instructions, which tells you what references you need to include in your project in order for it to successfully compile. First, under HttpClientCmd, right-click References and select "Add Reference..." Select the Assemblies tab and search for each of the following:

//PROJECT SETUP INSTRUCTIONS:
//
//1) Please add the following references:
//   a. System.Net.Http
//   b. If programming on the server, System.Net.Http.Formatting
//   c. System.Data.Sqlite (if using Visual Studio) or Mono.Data.Sqlite (if using Xamarin Studio). If programming for server, add it as a Mono.Data.Sqlite NuGet
//   d. System.Data
//   e. If programming on the server, System.Web
//   f. System.ComponentModel.DataAnnotations
//   g. System.Runtime.Serialization
//   h. System.Web.Services
//   i. Json.NET (NuGet package)
//   j. ModernHttpClient (NuGet package) -- this one is only for Mobile
//   k. Xamarin.Forms (NuGet package) -- this one is only for Mobile
//
//2) For iOS only: under build options please add --nolinkaway to Additional mtouch arguments
//   For more info on this, pleasee see: 
//   https://spouliot.wordpress.com/2011/11/01/linker-vs-linked-away-exceptions/

namespace HttpClientCmd
{
	public class MyFirstProjectWebApiDataContext : WebApiDataContext
	{
		public override string BaseUrl
		{
			get { return "http://localhost:#####/api/"; }
		}
	}
}

Now, let's specify the UnitOfWork for our client. Under HttpClientCmd, add a class called MyFirstProjectWebApiUnitOfWork. The UnitOfWork on the client is almost symmetrical to the UnitOfWork on the server. Note that it also implements a stack (see UnitOfWork Stack), but their stacks are independent. Just like the UnitOfWork stack on the server, the UnitOfWork on the client supports unlimited nesting. One key difference between the two, however, is that the UnitOfWork on the client does not support UnitOfWorkIfNoAmbientContext. Otherwise, the client's UnitOfWork possesses all of the same functionality as the server's UnitOfWork, managing a set of operations that happen within a single transaction. Note that the UnitOfWork class our MyFirstProjectWebApiUnitOfWork derives from is Supermodel.Mobile.DataContext. Within our UnitOfWork, we need to specify the default constructor as well as a constructor that takes the ReadOnly enum:

namespace HttpClientCmd
{
	public class MyFirstProjectWebApiUnitOfWork : UnitOfWork<MyFirstProjectWebApiDataContext>
	{
		public MyFirstProjectWebApiUnitOfWork() { }
		public MyFirstProjectWebApiUnitOfWork (ReadOnly readOnly) : base(readOnly) { }
	}
}

We can now start writing code that will allow the client to communicate with the server. Remember that everything on the client must be async. We can only call async methods from another async method that returns void or a Task. We cannot make the Main( ) method async, so we need to create another method that will allow us to run asynchronously. We'll call this method RunAsync( ). Go to Program.cs under HttpClientCmd and write the following:

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

Note the use of await before the GetAllAsync( ) call in the code snippet above. This means RunAsync( ) will not wait for the call to be completed and return, and the rest of the method will be run as a completion handler.

If the Authenticate Attribute is still included in your UserController (see the previous section "Adding Security and Authentication to your Web API"), you will need to specify the AuthenticationHeader in your client application, or else you will not be able to authorize your Web API client. If you do not wish to include security features in your Web API, simply remove the Authenticate Attribute and do not include the following added line of code (in red).

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				
UnitOfWorkContext.AuthHeader = HttpAuthAgent.CreateBasicAuthHeader("Aladdin", "open sesame");
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

Be sure to always include the following line in your RunAsync( ) method:

UnitOfWorkContext.AuthHeader = HttpAuthAgent.CreateBasicAuthHeader("Aladdin", "open sesame");

In order to run/debug the code, we have to run two projects in the same solution: first, we will run our Web project (which we will set as our startup project) and then we can right-click your HttpClientCmd project and under "Debug", select "Start New Instance". Now you have two projects running within the same solution.

When the code runs, we'll get the following as a result:

Web API Client Console Application

Furthermore, there are a number of read-only async methods that the repo can call. These include the following:

Let's try a few of these methods now. Let's start by using the GetCountAllAsync() method.

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				
var countAll = await repo.GetCountAllAsync();
				
Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

When we run this, we will get a count of all the users in the database:

GetCountAllAsync() Example

Let's add another method to our program that counts all of the Users whose first name contains the letter "J". To do this, we'll use the GetCountWhereAsync( ) method. This method takes our UserSearchApiModel that we defined earlier and our search parameters.

public class UserSearchApiModel : SearchApiModel

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				var countAll = await repo.GetCountAllAsync();
				Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				
				
var countWhereContainsJ = await repo.GetCountWhereAsync(new UserSearchApiModel {FirstName = "j"});
				
Console.WriteLine("Count Where Contains J: " + countWhereContainsJ);
                
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

In our database, there are two users who have first names that contain the letter "J": Jane Doe and John Doe. Sure enough, the count returned is 2.

GetCountWhereAsync() Example

You can also make changes to the database using the client. The first thing we must do is change the UnitOfWork within our program to be Read/Write. To do this, change ReadOnly.Yes to ReadOnly.No:

using (new MyFirstProjectWebApiTrainingUnitOfWork(
ReadOnly.No
))

You can also just leave it blank, as the UnitOfWork is ReadOnly.No by default:

using (new MyFirstProjectWebApiTrainingUnitOfWork())

We'll now attempt to delete all users with the first name "Jane" in the database. Try running the code below:

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				var countAll = await repo.GetCountAllAsync();
				Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				
				var countWhereContainsJ = await repo.GetCountWhereAsync(new UserSearchApiModel {FirstName = "j"});
				Console.WriteLine("Count Where Contains J: " + countWhereContainsJ);
				
				
var janes = await repo.GetWhereAsync(new UserSearchApiModel {FirstName = "Jane"});
				
foreach (var jane in janes) jane.Delete();
                
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

If you tried running this code, you will see that we get an exception:

FinalSaveChangesAsync( ) Exception

The exception reads "Must run FinalSaveChangesAsync or Finalize otherwise before you are done with the unit of work". So, what happened?

Within the server, UnitOfWork implements IDisposable Interface. This means that there is a dispose method that is going to get called whenever UnitOfWork becomes out of scope. On the server, it is within the Dispose( ) method that the SaveChanges( ) method is called.

On the server side, we're used to changes being saved automatically. However, you cannot do the same thing on the client. This is because you can only save changes asynchronously on the client and on the client you cannot call an asynchronous method within the synchronous IDisposable implementation.

So, if you make any changes to your database through your client application (Add or Delete or modifications to your Entities), it's fundamental that, after you have made all of the changes you plan to make to the database, you call the function:

await UnitOfWorkContext.FinalSaveChangesAsync();

Note that the call to FinalSaveChangesAsync( ) doesn't need to be at the very end of the program. Rather, it simply needs to be after you have made all of the changes you plan to make to the database. This is because the FinalSaveChangesAsync( ) method marks the UnitOfWork as finalized, so any changes made after the method is called will not be persisted to the database.

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				var countAll = await repo.GetCountAllAsync();
				Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				
				var countWhereContainsJ = await repo.GetCountWhereAsync(new UserSearchApiModel {FirstName = "j"});
				Console.WriteLine("Count Where Contains J: " + countWhereContainsJ);
				
				var janes = await repo.GetWhereAsync(new UserSearchApiModel {FirstName = "Jane"});
				foreach (var jane in janes) jane.Delete();
				
				
await UnitOfWorkContext.FinalSaveChangesAsync();
                
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

Now that we have added FinalSaveChangesAsync( ), our program will now work:

Jane was Deleted

You will also need to use FinalSaveChangesAsync( ) when using the Add( ) method to add an object to the database. Let's try adding a new User to the database:

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				var countAll = await repo.GetCountAllAsync();
				Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				
				var countWhereContainsJ = await repo.GetCountWhereAsync(new UserSearchApiModel {FirstName = "j"});
				Console.WriteLine("Count Where Contains J: " + countWhereContainsJ);
				
				var janes = await repo.GetWhereAsync(new UserSearchApiModel {FirstName = "Jane"});
				foreach (var jane in janes) jane.Delete();
				
				
var newUser = new User {FirstName="Julius", LastName="Caesar", Username="EtTuBrute", Age=54};
				
newUser.Add();
				await UnitOfWorkContext.FinalSaveChangesAsync();
                
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

After running this code, our new User, Julius Caesar, appears in our database:

New User in Database

While on the server, the IDisposable implementation will save whatever pending changes it can find synchronously, the same cannot be done on the client (only an asynchronous way exists). In order to prevent the programmer from accidentally forgetting to save changes, IDisposable implementation on the client will throw an exception if we are inside a read/write UnitOfWork and some pending changes were not saved. Checking if pending changes exists will take some CPU cycles, even if no pending changes are there. Thus, for performance reasons, it's better to use FinalSaveChangesAsync( ). The method will tell the UnitOfWork that no more changes will be made, so there's no need for the IDisposable implementation to check for unsaved pending changes.

Delayed Reads

In order to further improve your application's performance, you can use Delayed Reads. Delayed Reads register the read, but don’t return any data until the changes are saved. This allows for better performance because your client application will only make one big call to the server, as opposed to many smaller calls. The delayed reads are rolled into one batch call with the rest of the pending changes.

Let's first implement the class DelayedModels, which takes the type of the Model as a parameter. Additionally, there are delay methods that are symmetric to the async methods listed previously in this section (scroll down for the full list of delayed read methods). We will then call the method DelayedGetAll( ) on the repo. We need to specify where the returned data goes, which we will do by passing it the Delayed Model we created:

DelayedModels<User> delayedAll;
repo.DelayedGetAll(out delayedAll);

When the DelayedGetAll(out delayedAll) method is called, delayedAll will be registered. However, it will remain empty until changes are saved. Once FinalSaveChangesAsync( ) is called, the delayedAll object will be populated. Then, after the call to save changes, we can print out all the read data by doing the following:

await UnitOfWorkContext.FinalSaveChangesAsync();
foreach (var user in delayedAll.Values) Console.WriteLine("First name:{0}, Age:{1}", user.FirstName, user.Age);

The full code would appear like so (note that the methods that write to the database have been deleted):

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				var countAll = await repo.GetCountAllAsync();
				Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				
				var countWhereContainsJ = await repo.GetCountWhereAsync(new UserSearchApiModel {FirstName = "j"});
				Console.WriteLine("Count Where Contains J: " + countWhereContainsJ);
				
				Console.WriteLine();
				
				
DelayedModels<User> delayedAll;
				
repo.DelayedGetAll(out delayedAll);
				
				await UnitOfWorkContext.FinalSaveChangesAsync();
				
				
foreach (var user in delayedAll.Values) Console.WriteLine("First Name:{0}, Age:{1}", user.FirstName, user.Age);
                
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

As a result, our console will print out the same results that the GetAllAsync( ) method outputs:

DelayedGetAll( ) Example

Let's add another method called DelayedGetById, which we will pass the Delayed Model and the Id of the User we wish to get. Note that since only one User will be returned, we specify DelayedModel<User>, as opposed to the plural DelayedModels<User> we used previously:

DelayedModel<User> delayedUserId7;
repo.DelayedGetById(out delayedUserId7, 7);

As with the delayedAll object, the delayedUserId1 object will not be populated until after the FinalSaveChangesAsync( ) method is called. Once it has been called, we can print out the read data:

await UnitOfWorkContext.FinalSaveChangesAsync();
...
Console.WriteLine("User with Id #7: First Name: {0} Last Name: {1}", delayedUserId7.Value.FirstName, delayedUserId7.Value.LastName);

The full code would appear like so:

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("First Name: {0} Age: {1}", user.FirstName, user.Age);
				
				Console.WriteLine();
				
				var countAll = await repo.GetCountAllAsync();
				Console.WriteLine("Count All: " + countAll);
				
				Console.WriteLine();
				
				var countWhereContainsJ = await repo.GetCountWhereAsync(new UserSearchApiModel {FirstName = "j"});
				Console.WriteLine("Count Where Contains J: " + countWhereContainsJ);
				
				Console.WriteLine();
                
				DelayedModels<User> delayedAll;
				repo.DelayedGetAll(out delayedAll);
				
				
DelayedModel<User> delayedUserId7;
				
repo.DelayedGetById(out delayedUserId7, 7);
				
				await UnitOfWorkContext.FinalSaveChangesAsync();
                
				foreach (var user in delayedAll.Values) Console.WriteLine("First Name:{0}, Age:{1}", user.FirstName, user.Age);
                
				Console.WriteLine();
				
				
Console.WriteLine("Person with Id #7: First Name: {0} Last Name: {1}", delayedUserId7.Value.FirstName, delayedUserId7.Value.LastName);
				
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

As a result, the User with Id 7, Robin Hood, is returned and printed to the console:

DelayedGetById( ) Example

Below are all of the delayed read methods that you can make use of. Note that you must specify where to store the data:

Delayed reads happen in the order in which they are listed within your UnitOfWork. In other words, if you just added an Entity before the delayed read, you'll be able to read it with the delayed read. Furthermore, if you delete an Entity after the delayed read, it will still be visible at the time of the delayed read because you haven't deleted it yet. This applies to Add and Delete, but doesn't work the same way with Update. The reason for that is that updates always happen last in a transaction because when you call a save changes method, any Models that have been updated are detected at that time and added to the list of pending changes that you need to make. Therefore, making updates will always be at the end of the list of pending changes regardless of when the Model was actually modified within the UnitOfWork.

Advanced Security Topics

If you do not wish to use the standard Basic Authentication header, you can use your own custom header by overriding a method called AuthHeaderName() within your MyFirstProjectAuthenticateAttribute class. All custom headers, by convention, need to start with "X-":

protected override string AuthHeaderName
{
	get { return "X-MyFirstProject-Authorization"; }
}

Then, within your client application, you must register the header within the UnitOfWorkContext:

namespace HttpClientCmd
{
	class Program
	{
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
			
				
UnitOfWorkContext.AuthHeader = HttpAuthAgent.CreateBasicAuthHeader("Aladdin", "open sesame");
				
UnitOfWorkContext.AuthHeader.HeaderName = "X-MyFirstProject-Authorization";
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("Name: {0} Age: {1}", user.FullName, user.Age);
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

You can also make the Authentication Header encrypted. Instead of using the AuthenticateBasicAndGetIdEntityName( ) method, we will implement the AuthenticateEncryptedandGetIdEntityName( ) method. This method takes an array of strings of any length that are encrypted and will use the provided encryption key. You will need to implement the EncryptionKey( ) method to return the encryption key. You will want to change the sample key provided below for your own project.

public class MyFirstProjectAuthenticateAttribute : AuthenticateAttribute
{
	
public readonly static byte[] _key = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF };
	
	protected override string AuthenticateBasicAndGetIdEntityName(string Username, string password)
	{	
		return null;
	}
	
	
protected override string AuthenticateEncryptedAndGetIdEntityName(string[] args, out string password)
	{
		if (args.Length != 2)
		{
			password = null;
			return null;
		}
		
		var Username = args[0];
		password = args[1];
		
		if (Username == "Aladdin" && password == "open sesame") return "1";
		return null;
	}
	
	protected override byte[] EncryptionKey
	{
		get { return _key; }
	}
}

Now, on the client-side, we need to provide the key and change the AuthHeader to use the Encrypted AuthHeader by calling the method CreateCustomEncryptedAuthHeader(key, Username, password).

namespace HttpClientCmd
{
	class Program
	{
		
public readonly static byte[] _key = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF };
		
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				
UnitOfWorkContext.AuthHeader = HttpAuthAgent.CreateCustomEncryptedAuthHeader(_key, "Aladdin", "open sesame");
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("Name: {0} Age: {1}", user.FullName, user.Age);
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

The encrypted AuthHeader can also go into a custom authorization header:

namespace HttpClientCmd
{
	class Program
	{
		
public readonly static byte[] _key = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF };
		
		static void Main()
		{
			RunAsync();
			Console.WriteLine("Running. Press enter at any time to quit...");
			Console.WriteLine();
			Console.ReadLine();
		}
		
		public static async void RunAsync()
		{
			using (new MyFirstProjectWebApiUnitOfWork(ReadOnly.Yes))
			{
				
UnitOfWorkContext.AuthHeader = HttpAuthAgent.CreateCustomEncryptedAuthHeader(_key, "Aladdin", "open sesame");
				
UnitOfWorkContext.AuthHeader.HeaderName = "X-MyFirstProject-Authorization";
				var repo = RepoFactory.Create<User>();
				var all = await repo.GetAllAsync( );
				foreach (var user in all) Console.WriteLine("Name: {0} Age: {1}", user.FullName, user.Age);
				Console.WriteLine();
				Console.WriteLine("Done.");
			}
		}
	}
}

Model Hooks

BeforeSave

Just like Entities, each Model implements a virtual BeforeSave( ) method that is called right before the Model is about to be saved. Just like with Entities, this method, for example, is very useful for updating CreatedOn or ModifiedOn dates for your Entity. For example:

public override void BeforeSave(PendingAction.OperationEnum entityState)
{
	if (entityState == PendingAction.OperationEnum.AddWithExistingId || entityState == PendingAction.OperationEnum.GenerateIdAndAdd) 
	{ 
		CreatedOn = ModifiedOn = DateTime.Now;
	}
	
	if (entityState == PendingAction.OperationEnum.Update) 
	{
		ModifiedOn = DateTime.Now;
	}
	
	base.BeforeSave(entityState);
}

Just as with Entities, it is very important to understand that if you make any changes to other Models inside the BeforeSave( ) method, the results could be unpredictable. That's because Supermodel detects changes to your Models right before they're about to persisted, and once it has created a List of Models that have been either modified, or deleted, or added, it will call BeforeSave( ) for every one of those Models in the List. If inside one of those BeforeSave( ) methods you make changes to another Model, that Model's BeforeSave( ) will not run unless it's already in the List for another reason. Therefore, it is considered best practice to have a Model only make changes to itself in the BeforeSave( ) method.

Creating a Self-Documenting Web API

Documenting your Web API is incredibly easy using the NuGet package Microsoft ASP.NET Web API 2.2 Help Page. Once you have installed the package, all you need to do is make sure you have the following line in your Global.asax file:

AreaRegistration.RegisterAllAreas();

Now, if you go to the url localhost:#####/Help (replacing "#####" with your localhost number), you'll see the entire API Documentation for your Web API application.

Portion of Web API Documentation for a Simple CRUD Controller

Custom Web API Methods

In some cases, it is useful to create custom Web API methods - the ones that CRUD Controllers do not give you for free. These methods could be created as part of a completely separate controller or they could extend an existing CRUD Controller. Let's look at a (contrived) example: let's imagine that we want to create a method on the server that will take a local time on the client and return a difference in minutes between that time and the time on the server. On the server, this method would look like this:

public class TimeDifferenceController : ApiController
{
	[HttpPost]
	public HttpResponseMessage Post(DateTime clientTime)
	{
		var serverTime = DateTime.Now;
		var timeSpan = serverTime - clientTime;
		return Request.CreateResponse(HttpStatusCode.OK, timeSpan.Min);
	}
}

Now let's extend our client data context to support this method.

public class MyFirstProjectWebApiDataContext : WebApiDataContext
{
	public override string BaseUrl
	{
		get { return "http://localhost:#####/api/"; }
	}
	
	
public async Task<int> GetTimeDiffAsync(DateTime time)
	{
		var request = new HttpRequestMessage(HttpMethod.Post, BaseUrl + "TimeDifference");
		var dataResponse = await HttpClient.SendAsyncAndPreserveContext(request);
		var responseContentStr = dataResponse.Content != null ? await dataResponse.Content.ReadAsStringAsync() : "";
		
		if !(dataResponse.IsSuccessStatusCode) throw new SupermodelWebApiException(dataResponse.StatusCode, responseContentStr);
		var timeDifference = JsonConvert.DeserializeObject<int>(responseContentStr);
		return timeDifference;
	}
}

This is how we could use this newly created method:

var timeDifference = await UnitOfWorkContext<MyFirstProjectWebApiDataContext>.CurrentDataContext.GetTimeDiffAsync(DateTime.Now);

Reference

public enum FavoriteColor
{
	Red = 1;
	[Disabled] Orange = 2;
	Yellow = 3;
	Green = 4;
	Blue = 5;
	Indigo = 6;
	Violet = 7;
}

public class PersonEditMvcModel : MvcModelForEntity<Person> 
{ 
	[DisplayOnly] public TextBoxForStringMvcModel Name { get; set; }
} 
public class Person : Entity 
{ 
	#region Properties 
	public string Name { get; set; } 
	#endregion 
}

public enum FavoriteColor
{
	Red = 1;
	Orange = 2;
	[Description("Lemon")] Yellow = 3;
	Green = 4;
	Blue = 5;
	Indigo = 6;
	Violet = 7;
}

[ListColumn(Header="User's Name", OrderBy = "Name", OrderByDesc = "-Name"), Required] 


public string Name { get; set; }

[DataType(DataType.Password), MustEqualTo("ConfirmPassword")] 
 public string NewPassword { get; set; }
[DataType(DataType.Password), MustEqualTo("NewPassword")]
 public string ConfirmPassword { get; set; }

public enum FavoriteColor
{
	Red = 1;
	Orange = 2;
	[ScreenOrder(200)] Yellow = 3;
	Green = 4;
	Blue = 5;
	Indigo = 6;
	Violet = 7;
}

UI Components

---

Supermodel provides three styles of UI Components: Customizable Generic, Twitter Bootstrap, and JQuery Mobile style, allowing you to easily create a beautiful Bootstrap-style website or JQMobile mobile application, or create your own.

These UI components expose properties that control their behavior and their look. For example, most UI controls expose a property that controls HTML attributes that go onto the HTML tag for this component, or UI components for numeric values expose properties that control the valid range. You can easily explore those properties using IntelliSense in Visual Studio.

Generic

---

Binary Files and Images

Binary File Input

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	[Required] public BinaryFileMvcModel UserImage { get; set; }
} 
public class User : Entity 
{ 
	#region Properties 
	public BinaryFile UserImage { get; set; } 
	#endregion 
}

---

Image MVC Model

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	[Required] public BinaryFileMvcModel UserImage { get; set; }
	[RMapTo(PropertyName = "UserImage"), HideLabel] 
	public ImageMvcModel UserImageView { get; set; }
} 
public class User : Entity 
{ 
	#region Properties 
	public BinaryFile UserImage { get; set; } 
	#endregion 
} 

Checkbox

Checkbox List Horizontal Using or Checkbox List Vertical Using

Red Orange Yellow Green Blue Indigo Violet

If you want to create a checkbox for an Entity, simply use the following template. You can replace any instance of "Horizontal" with "Vertical" to get a vertical list of checkboxes.

public class UserMvcModel : MvcModelForEntity<User>
{ 
 	public CheckboxesListHorizontalMvcModelUsing<FavoriteColorMvcModel> Colors { get; set; } 
} 
public class User : Entity 
{ 
	#region Properties 
	public virtual IEnumerable<favoritecolor>
	Colors { get; set; } 
	#endregion 
} 

namespace Domain.Entities 
{ 
	public class FavoriteColorMvcModel : MvcModelForEntity<FavoriteColor>
	{ 
		public string Name { get; set; } 
		public override string Label { get { return Name;  } } 
	} 
	
	public class FavoriteColor : Entity 
	{ 
		#region Properties 
		public string Name { get; set; } 
		#endregion 
	} 
} 

---

Checkbox Mvc Model

Check If True

You can create a checkbox for a boolean using the following method:

public class UserMvcModel : MvcModelForEntity<User> 
{ 
 	public CheckboxMvcModel CheckIfTrue  { get; set; } 
} 
public class User : Entity 
{ 
	#region Properties 
	public bool? CheckIfTrue { get; set; } 
	#endregion 
} 

Date Model

DateMvcModel

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	[DisplayName("Date of Birth")] public DateMvcModel DOB { get; set; } 
} 
public class User : Entity 
{ 
	#region Properties 
	public DateTime? DOB { get; set; } 
	#endregion 
}

Dropdown

DropdownMvcModelUsingEnum

Favorite Color

• Red
• Orange
• Yellow
• Green
• Blue
• Indigo
• Violet

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public DropDownMvcModelUsingEnum<User.FavoriteColorEnum>  
		FavoriteColor { get; set; } 
}
 
public class User : Entity 
{ 
	public enum FavoriteColorEnum { Red, Orange, Yellow, Green, Blue, Indigo, Violet }; 
	#region Properties 
	public FavoriteColorEnum FavoriteColor { get; set; } 
	#endregion 
} 

---

Dropdown Lookup

Favorite Color

• Red
• Orange
• Yellow
• Green
• Blue
• Indigo
• Violet

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public DropDownMvcModelUsing<FavoriteColorMvcModel>
}
 
public class User : Entity 
{
	#region Properties 
	public virtual FavoriteColor FavoriteColor { get; set; } 
	#endregion 
}

public class FavoriteColorMvcModel : MvcModelForEntity<FavoriteColor> 
{ 
	public string FavoriteColorName { get; set; }
	public override string Label
	{
		get { return FavoriteColorName; }
	}
}
 
public class FavoriteColor : Entity 
{
	#region Properties 
	public string FavoriteColorName { get; set; } 
	#endregion 
}

public static void Seed(MyFirstProjectDbContext context)
{
	var favoritecolors = new[]
	{
		new FavoriteColor{ FavoriteColorName = "Red" },
		new FavoriteColor{ FavoriteColorName = "Orange" },
		new FavoriteColor{ FavoriteColorName = "Yellow" },
		new FavoriteColor{ FavoriteColorName = "Green" },
		new FavoriteColor{ FavoriteColorName = "Blue" },
		new FavoriteColor { FavoriteColorName = "Indigo" },
		new FavoriteColor { FavoriteColorName = "Violet" }
	};
	
	foreach (var  favoritecolor in favoritecolors) context.Set<FavoriteColor>().Add(favoritecolor);
}

Radio Button

Lookup Radio Button

Red Orange Yellow Green Blue Indigo Violet

public class FavoriteColorMvcModel : MvcModelForEntity<FavoriteColor>
public string Name { get; set; }
{
	get {return Name;}
}
public class FavoriteColor : Entity 
{ 
	public string Name; 
}

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public RadioSelectHorizontalMvcModelUsing<FavoriteColorMvcModel> FavoriteColor {get; set;}
} 
public class User : Entity 
{ 	
	#region Properties 
	public virtual FavoriteColor FavoriteColor { get; set; } 
	#endregion 
}

---

Enum Radio Button

Red Orange Yellow Green Blue Indigo Violet

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public RadioSelectHorizontalMvcModelUsingEnum<Person.FavoriteColorEnum>  
		FavoriteColor { get; set; } 
}
 
public class User : Entity 
{ 
	public enum FavoriteColorEnum { Red, Orange, Yellow, Green, Blue, Indigo, Violet }; 
	#region Properties 
	public FavoriteColorEnum FavoriteColor { get; set; } 
	#endregion 
}

---

Vertical Radio Select Using an MVC Model

Red Orange Yellow Green Blue Indigo Violet

public class FavoriteColorMvcModel : MvcModelForEntity<FavoriteColor>
public string Name { get; set; }
{
	get {return Name;}
}
public class FavoriteColor : Entity 
{ 
	public string Name; 
}

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public RadioSelectVerticalMvcModelUsing<FavoriteColorMvcModel> FavoriteColor {get; set;}
} 
public class User : Entity 
{ 	
	#region Properties 
	public virtual FavoriteColor FavoriteColor { get; set; } 
	#endregion 
}

---

Vertical Radio Select Using Enum

Red Orange Yellow Green Blue Indigo Violet

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public RadioSelectVerticalMvcModelUsingEnum<Person.FavoriteColorEnum>  
		FavoriteColor { get; set; } 
} 
public class User : Entity 
{ 
	public enum FavoriteColorEnum { Red, Orange, Yellow, Green, Blue, Indigo, Violet }; 
	#region Properties 
	public FavoriteColorEnum FavoriteColor { get; set; } 
	#endregion 
}

Textbox

Textarea

Description

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public TextAreaMvcModel Description { get; set; }
} 
public class User : Entity 
{ 
	#region Properties 
	public string Description { get; set; } 
	#endregion 
} 

---

Textbox For Double

Height

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public TextBoxForDoubleMvcModel Height { get; set; }
}
 
public class User : Entity 
{ 
	#region Properties 
	public double Height { get; set; } 
	#endregion 
} 

---

Textbox For Int

Age

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public TextBoxForIntMvcModel Age { get; set; }
} 
public class User : Entity 
{ 
	#region Properties 
	public int Age { get; set; } 
	#endregion 
} 

---

Textbox For Password

Secret

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public TextBoxForPasswordMvcModel Secret { get; set; }
} 
public class User : Entity 
{ 
	#region Properties 
	public string Secret { get; set; } 
	#endregion 
} 

---

Textbox For String

Name

public class UserMvcModel : MvcModelForEntity<User> 
{ 
	public TextBoxForStringMvcModel Name { get; set; }
}
 
public class User : Entity 
{ 
	#region Properties 
	public string Name { get; set; } 
	#endregion 
}

Twitter Bootstrap

---

To provide the Twitter Bootstrap framework for your app, simply add the TweeterBS class to your MVC models and MasterLayout. For example, your UserMvcModel would be changed to the following (note the changes in red):

public class UserMvcModel : 
TweeterBS
.MvcModelForEntity<User> 
{ 
	public 
TweeterBS
.TextBoxForStringMvcModel Name { get; set; }
}
 
public class User : Entity 
{ 
	#region Properties 
	public string Name { get; set; } 
	#endregion 
}

And your Master Layout would also need to call the TweeterBS class:

@using Supermodel.Extensions
@Html.Supermodel().
TweeterBS
.MasterLayout(this, "Your App Name", "1.10.1", "2.3.2")

Twitter Bootstrap also comes with some unique UI Components, such as Accordion sections.

Accordion

Creates an accordion with collapsible panel components.

If you wanted to have your Search View displayed in an Accordion Panel, you could update your Search.cshtml file to appear as follows:

@model UserSearchMvcModel
<script src="/Content/Scripts/Custom/search-panel.js"></script>
      
<div class="row">
    <div class="span4">
        @MvcHtmlString.Create(Html.Supermodel().TweeterBS.CRUDSearchFormInAccordeonForModel("Accordion", Model.GetPanels()).ToString().Replace("form-horizontal", ""))
    </div>
</div>

You would also need to update your UserSearchMvcModel to include the GetPanels( ) method. The TweeterBS.AccordeonPanel( ) HTML extension takes the following parameters: an string for the element Id, a string for the panel title, and two ints, ScreenOrderFrom and ScreenOrderTo, that control where elements are placed on the screen. In the following code, we've stated that we want the UserSearch field and the MaximumAge search field to be placed in two different panels.

public class UserSearchMvcModel : TweeterBS.MvcModel
{
	
public List<TweeterBS.AccordeonPanel> GetPanels()
	{
		var panels = new List<TweeterBS.AccordeonPanel>()
		{
			new TweeterBS.AccordeonPanel("UserSearch", "User Search", 100, 100)
			new TweeterBS.AccordeonPanel("MaximumAge", "Maximum Age", 200, 200)     
		};
		return panels;
	}
	
	
[ScreenOrder(100)]
 public string UserSearch { get; set; }
	
[ScreenOrder(200)]
 public int? MaximumAge { get; set; }
}

So, if we open the UserSearch panel, we would see the following Search View screen:

Search View Accordion with UserSearch Panel Open

If we open the MaximumAge panel, the UserSearch panel collapses automatically:

Search View Accordion with MaximumAge Panel Open

JQuery Mobile

---

To provide the JQuery Mobile framework for your app, simply add the JQMobile class to your MVC models and MasterLayout. For example, your PersonMvcModel would be changed to the following (note the changes in red):

public class UserMvcModel : 
JQMobile
.MvcModelForEntity<User> 
{ 
	public 
JQMobile
.TextBoxForStringMvcModel Name { get; set; }
} 
public class User : Entity 
{ 
	#region Properties 
	public string Name { get; set; } 
	#endregion 
}

And your Master Layout would also need to call the JQMobile class:

@using Supermodel.Extensions
@Html.Supermodel().
JQMobile
.MasterLayout(this, "Your App Name", "1.10.1", "1.3.1", true)

JQuery Mobile also comes with some unique UI Components, such as Sliders.

Slider For Int

Displays a slider for a property of type integer with a default minimum value of 0 and a default maximum value of 100.

Within your entity you need a property of type int:

public int? Rating { get; set; } 

And within your MVC Model, you need to call JQMobile.SliderForIntMvcModel

public JQMobile.SliderForIntMvcModel Rating { get; set; }

Slider For Double

Displays a slider for a property of type double with a default minimum value of 0 and a default maximum value of 100.

Within your entity you need a property of type int:

public int? Height { get; set; }

And within your MVC Model, you need to call JQMobile.SliderForIntMvcModel

public JQMobile.SliderForDoubleMvcModel Height { get; set; }