Sunday, 10 March 2013

Build application using ASP.NET MVC 4, WEB API, EF 5.0 (database first) Knockout (MVVM pattern), Breezejs, KoGrid, Autofac,...

Next Post(Continuation of this post): Simple CRUD with Knockout, Breeze, WEB API, Twitter bootstrap ,...


As mentioned in my introductory post, English is not my mother tongue and so before I really start writing anything, I have to apologize in advance for any language mistakes I make.
Now let's start.


So here today I'll build the application using the following technologies: ASP.NET MVC 4, Entity Framework 5.0, ASP.NET WEB API, AUTOFAC (DI container) and the following JavaScript frameworks: BreezeJS, JQuery, KnockoutJs, KoGrid,... Bear in mind that this is only for learning purposes! As I want to build a Tax calculation app, this will be a small excerpt of it, but showing the complete architecture (with only one screen : Tax payer screen). The purpose of this post is to show how easy (and clean and elegant) it is to get data from the server and bind them on the client using MVVM pattern and all the technologies I've listed above. Of course, along the way I'll try to convince you to use DI containers and couple of other techniques.
I'll try to go into details and do it as simply as I can, so even fresh new developers can understand what I am trying to say. The source code can be found at the github. So please take it, play with it, extend it...feel free to change it in any way and let me know what you think about it. The project is built using Microsoft Visual studio 2012 and SQL Server 2008R2, if you use Visual studio 2010 then you'll have to add yourself MVC4 templates.
So in short we have a simple UI with a grid (KoGrid) that is bound to ViewModel (Knockout observable collection). In the ViewModel we reference breezeJS data service which is querying data from our persisting service. That would all happen on the client side, while on the server side we set our persisting service which is ASP.NET Web API and by using Breeze.NET API and Repository pattern we request data from our model which is Entity Framework. The dependecies are managed by Autofac DI container. For the debugging purposes I have used a simple logger class.
The architecture that I am trying to build looks like the figure below.

Tax payer application architecture



I chose the ASP.NET MVC. Why do I like the ASP.NET MVC? The list is long, but the first things that come to mind are: Separation of concerns, Testability, URL Routing, Built-in and shipped JQuery support :), WEB API (MVC-like framework that we can use to create a RESTful service), good mobile support, etc... The MVC lets you separate business logic from presentation logic so that they can be independently tested. It also lets you easily extend your application or replace any of the components as they are independent of each other.
In my example, everything will be a part of the same project even though they can and they should be sitting in the separate assemblies (e.g. WEB API, EF,...).
So lets start. Run your VS2012 - choose ASP.NET MVC 4 template - type the name of the project (TaxAppBlog). If you want to learn more about ASP.NET MVC 4 - David Hayden is writing a nice tutorial on his blog.

After you clicked ok, the new screen came up and there we choose the WEB API template.


It is, in my humble opinion, a huge step forward to make simple SOA architecture available to anyone. You remember the time when people started talking about SOA, it was a huge buzz word. You couldn't pass by any meeting room without hearing somebody mentioning it. Using services in your application was a powerful idea but making your code become available through services required learning different frameworks and doing a lot of plumbing  and configuration to make it work. The learning curve was high, the apps that came out were brutal and the market was full of the proprietery technologies to make this happen, including WCF. With all this in mind Microsoft finally produced the framework that uses only open standards and is very easy to set it up and use. So here are a couple of bullet points on ASP.NET WEB API.
  • It is a framework for building pure HTTP based services, where the request and response happens with HTTP protocol.
  • It is an ideal platform for building RESTful applications on the .NET Framework.
  • Next iteration of WCF REST
  • Incorporated into ASP.NET MVC 4
  • Uses HTTP protocols
  • Using REST to consume the service. Basic URL + HTTP method (GET, PUT, POST, DELETE).
In my example I am going to use WEB API to get data and send it to the client in JSON format. The format of the returning data can be requested differently (instructions in the Accept Header). I am not going to explore much more on WEB API here (not the main purpose of this post) but if you want to learn more, than the best place to start is here.
After the visual studio finishes creating a project, the solution explorer will look like picture below.

Notice that there are two controllers created by default: Home and Values controller. The differences between them is that Home is inherited from System.Web.Mvc.Controller and Values from System.Web.Http.ApiController. If you are familiar with ASP.NET MVC then you already know how the Routing works. If I can explain it in one sentence then I would probably say that it is an interpretation of URLs  by the server to decide what code should handle the request. The difference with ApiControllers is that the actions are not defined by URL but by HTTP methods so the same URL can contain two different HTTP methods, therefore they do two different actions (e.g. can retreive data(GET) or save data(PUT)). To learn more about routing and much more about ASP.NET MVC I would highly reccomend reading the book Pro ASP.NET MVC Framework by Steven Sanderson.

Entity Framework

To manage data in my application I'll use entity framework 5.0. EF provides you with three ways to define the model of your entities:

The Database First - begins with an existing database and reverse-engineer into a conceptual model.
The Model First - begins with an empty diagram - use the visual designer to design an EDM, then generate database schema from that model.
The Code First - begins with classes that describe your conceptual model.
In this example I'll use the Database First method. I will reverse-engineer only one table from my Tax database - Person table (again, I don't want here to build the whole Tax application but just to demonstrate how I would build a web app.) As mentioned above, the source code is on the GitHub and there you can find the SQL script that would generate and populate the database for you (in the script and in the source code on the GitHub I call the database TaxBlog, while here it is called Tax. It was changed after I wrote this post so I could continue working on my Tax app and have another database side by side). So if you want to follow and build the application while reading this blog, then make sure you build the database before you continue (see the Readme file on the GitHub).
Creating Model for Tax application (only Person)
  • Select Add and then New Item from the menu.

  • Select ADO.NET Entity Data Model from the filtered list of item templates. Change the name of the model to Tax.edmx and click Add

  • In the Choose Model Contents window, select Generate from database and then click the Next button.

  • On the Choose Your Data Connection page, select Tax database in the data connection drop down and click Next.

  • Then save entity connection settings in the Web.config and click Next.

  •  Then choose only table Person from the database.

And as a result we get the entity Person which represents the table from the Tax database.
To be honest we could use here DTOs (see the article that Antony Sneed wrote a long time ago) which might happen in some of the next blog posts but for now we'll be using classic enitites.

 Breeze.NET API

Breeze is made by the company called IdeaBlade and it is basically, a JavaScript data management library. It helps you manage data in rich client application. Breeze has a two parts of the setup: server and client. First we'll talk about the server part. There are a lot of reasons why I really like and choose Breeze but one that helps me decide is that Breeze ships with out-of-the-box support for the ASP.NET Web API and Entity Framework. As my example uses ASP.NET Web API controller (which will be covered further in the post) to handle the HTTP requests from the client and it uses the Entity Framework to model and access a SQL database, the Breeze offers me a wrapper component (called EFContextProvider) around the application's DbContext. It takes care of a lot of routine plumbing. I'll use out-of-the-box EFContextProvider but in real life you would probably customize it (e.g. intercept save requests and validate them, etc...). As we really appreciate a separation of concerns and loosely coupled layers:  we always try to reference interfaces so that the concrete implementation can be supplied at runtime. In that light, I will build repository pattern which allows me to easily replace EF with some other ORM (e.g. NHibernate,etc...) But before that I'll add Breeze for ASP.NET Web API using NuGet.

Now I'll build the repository interface:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace TaxAppBlog.Models.Contracts
    public interface IBreezePersonRepository
        IQueryable People { get; }
        string Metadata();
Using IQueryable I am taking advantage of oData. Now I can use OData syntax of paging and querying people which I'll present you later in the post. Metadata is needed for the Breeze setup. "Breeze needs this metadata to communicate with the persistence service during query and save, to create new entities on the client, and to navigate among entities in cache. Because Breeze has metadata, it can generate your JavaScript model “classes” on the fly."
Now we'll be adding a new class BreezePersonRepository which will implement the interface IBreezePersonRepository.
Here we'll be using a Breeze EFContextProvider to query on EF or to get breeze metadata.

And finally BreezePersonRepository looks like this:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using Breeze.WebApi;
using TaxAppBlog.Models.Contracts;

namespace TaxAppBlog.Models.Implementations
    public class BreezePersonRepository : IBreezePersonRepository
        readonly EFContextProvider _contextProvider =
            new EFContextProvider();
        public IQueryable People
            get { return _contextProvider.Context.People; }

        public string Metadata()
            return _contextProvider.Metadata();
Now when the Breeze is set on the server, we are ready to build our WEB API. But before we do that we'll set the Autofac as our DI container.

Autofac - IoC container

Even though in my small example I wouldn't need to use any of IoC containers I did it to show that it's not so complicated (there is a lot of fear around about the complexity of the setup of the Ioc containers). I strongly advise everybody to use it when they build their application. At my work we are mostly using Unity but here I'll set another one which is called Autofac. I chose Autofac as it had correct benchmark results (benchmarks from some time ago IoC Container Benchmark - Performance comparison; IoC Container Benchmark ReRevisted - Ninject updated, Autofac added ) and it has ASP.NET MVC 4 Integration package as well as ASP.NET WEB Api Integration package. So to start adding the Autofac we'll call in help...who else but NuGet :) We'll be adding Autofac and its two integrations (ASP.NET MVC 4 and WEB Api)

To configure Autofac we'll add a new class and give it a name AutofacConfig:

In this class we'll register all MVC controllers then API controllers. We'll also set their lifetime scope: InstancePerApiRequest is part of the Web API integration, and InstancePerHttpRequest is part of the MVC integration. They both apply the same tag to the lifetime scope but it was done this way because you might have services that are dependencies of both Web API and MVC controllers. Then we register our container for MVC controllers and API controllers.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Mvc;
using Autofac;
using Autofac.Integration.Mvc;
using Autofac.Integration.WebApi;
using TaxAppBlog.Models.Implementations;

namespace TaxAppBlog.App_Start
    public class AutofacConfig
        public static void Register(HttpConfiguration config)
            var builder = new ContainerBuilder();
            var container = builder.Build();
            DependencyResolver.SetResolver(new AutofacDependencyResolver(container));
            GlobalConfiguration.Configuration.DependencyResolver = new AutofacWebApiDependencyResolver(container);
Now we need to call this class at the start of the application so we call it from Global.asax
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Mvc;
using System.Web.Optimization;
using System.Web.Routing;
using TaxAppBlog.App_Start;

namespace TaxAppBlog
    // Note: For instructions on enabling IIS6 or IIS7 classic mode, 
    // visit

    public class WebApiApplication : System.Web.HttpApplication
        protected void Application_Start()

So kids, that wasn't difficult :). Start using DI containers in your future projects if you haven't already done so. Now for the last element of server side setup we'll build our WEB Api service.


We'll add a new ApiController called BreezePeopleController (probably unfortunate name - should have omitted Breeze from the name).

Now our controller will look very simple
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using Breeze.WebApi;
using TaxAppBlog.Models;
using TaxAppBlog.Models.Contracts;

namespace TaxAppBlog.Controllers
    public class BreezePeopleController : ApiController
        IBreezePersonRepository repository;
        public BreezePeopleController(IBreezePersonRepository repository)
            this.repository = repository;

        public IQueryable GetPeople()
            return repository.People;

        // ~/api/BreezePeople/Metadata 
        public string Metadata()
            return repository.Metadata();
You noticed that our controller is decorated with the attribute BreezeController. Now why did we do that? "A Breeze server (read Web API controller) and a Breeze client (read BreezeJS) have a shared understanding about the nature and format of HTTP requests, responses and payloads. The Web API pipeline has to be configured to conform to that "understanding". Because your Breeze Web API Controller may cohabitate with other, non-Breeze controllers, Breeze shouldn't impose its configuration requirements on them. Therefore, we should configure the Web API pipeline on a controller basis ... and that's what this BreezeController attribute does.
When the Web API routes a request to the BreezePeopleController, it creates a new instance of that controller type and then calls the BreezeController attribute to configure the Web API pipeline for this controller instance only.
Always decorate your Breeze controller with the BreezeController attribute."
We used Constructor Injection to inject references of our IBreezePersonRepository implementation (here one can see how this is really decoupled.) Before we go further and setup the client we'll test the server side setup. In short, we'll run the application and request the URL of the method GetPeople.
As a result we'll get the JSON formatted results. The question to open it pops up...
...and after we open it in notepad we see our data in JSON format.
Here I am going to show how you can inspect the results in more elegant way by using Fiddler. First you enter the url in the composer and execute it.
Then go to the Inspector tab and verify your results.
As the last thing before we move on to the client setup, I'll show you how to query/sort data using OData syntax (which I promised above while setting People property as IQueryable). Again, open the Composer tab in the Fiddler and change the URL into something like this: http://localhost:17612/api/breezePeople/getPeople?$top=1&$orderby=FamilyName (where 17612 is only my development web server port - if you run your project in visual studio chances are you are going to get a different port number). Take note that we specified that we want the top 1 record and to be ordered by FamilyName.

After executing composer, go and verify your results (Inspector tab) - we actually retreived only one record and sorted by FamilyName.

 Finally, the server side is up and running so we can move to the client side.



For client side setup we'll start with BreezeJS. In general, what we'll do is download script libraries by using NuGet then we'll "bundle" them and we'll also add reference in the _Layout.cshtml so they can be available in all views (only those that are using _Layouts.cshtml as master page of course). Breeze scripts are already downloaded and added to the project with the package "Breeze for ASP.NET Web Api projects" that we got during the Breeze setup in the server section (see above "Breeze.NET API").
On the client side we work with Breeze Entity manager class. The Entity Manager is a core class in Breeze. When the client app asks for data it calls a method on an instance of an Entity Manager. Entity Manager is a gateway to our persistance model. It reads the data model supplied by our services metadata and produces a Java Script "entity" object which we'll use further for our data binding. The brilliant thing is that it doesn't require you to do anything on the client side in terms of manually defining entity classes or write any mapper. The Entity Manager acts as its own data context on the client side which means when you create multiple instances of the Entity Manager then they are completely independent, each having its own cache. What they share is that they talk to the same service and they share the same Metadata store. I prefer to have a shared entity manager. The way that we can achieve this is if we encapsulate the application manager within the "dataservice" module. All the other modules reference this dataservice module and ask it for data.
(function (root) {
    var breeze = root.breeze;
    var app = = || {};
    // show logger initially;    
    log("Window is loaded.");

    var serviceName = 'api/BreezePeople';
    var manager = new breeze.EntityManager(serviceName);

    // add members to the dataservice
    var dataservice = {
        getAllPersons: getAllPersons

    // extend the app with this dataservice
    app.dataservice = dataservice;

    // gets all Persons asynchronously
    // returning a promise you can wait for     
    function getAllPersons(peopleArray) {
        log("querying for all persons")
        var query = new breeze.EntityQuery()

        return manager
           .then(function (data) {
               processResults(data, peopleArray);

    // clears observable array and loads the person results 
    function processResults(data, peopleArray) {
        log("Clears observable array and loads the person results.");
        var persons = data.results;
        persons.forEach(function (person) {
            log("adding " + person.FirstName._latestValue + " " + person.FamilyName._latestValue);

    function queryFailed(error) {
        log("Query failed: " + error.message);


For debugging purposes I've used a logger class which prints debugging messages on a separate console window at the bottom of the web browser (which is very handy). The logger can be found here.  So what we did here is create an entity manager and use it to execute the query (.executeQuery(query)) which is an asynchronous method and returns a promise to call back either the processResults method if the query succeeds or the queryFailed method if the query execution fails with an exception. The dataservice is added to the namespace app so it can be called from different viewmodels. Now we finally come to UI data binding with Knockout.


First we'll download Knockout using NuGet:

...then we'll "bundle" them:

As a big fan of the KnockoutJS I'll say just a couple of words about what KO (short for Knockout) is, what it is not and why and how to use it. KnockoutJS is a JavaScript library that helps you to create rich and responsive interfaces with a clean underlaying data model by using a MVVM approach. Basically, when you make calls via ajax and update your UI elements, things can get a little messy. Knockout can make it simpler and more uniform. It is a self contained JavaScript library (14Kb - gzip), supports all mainstrem browsers and what is really nice - no dependencies. It is important to understand that it is not a replacement for JQuery and it is not a Prototype for JavaScript. There are three core features of KnockoutJS. The first is Observables and dependency tracking - it updates your UI automatically. When you change a viewmodel it updates UI elements also. How can Knockout  know that a part of your viewmodel changed, well the answer is: it needed to query model properites as observables because they are special JavaScript objects that can notify the subscribers about changes and then it can automatically detect dependencies. The second feature is Declarative Bindings - this is a simpe and obvious way to connect a part of your UI to your data model. You can now construct complex dynamic UI easily and arbitrarily using these databinding contracts. The third important feature is Templating - Template binding populates the DOM element with the results of rendering template. This means that teamplates are a simple and convinient way to build UI structures possibly with repeating or nested blocks as a function of your viewmodel data. To learn more on KnockoutJS please go here. One of the reasons that Knockout was created was enabling MVVM style development for websites/web applications. So I'll say a couple of words about it also. MVVM is a design pattern for building user interfaces. It describes how you can keep a potentially sophisticated UI simple by splitting it in three parts (separation of concerns). The first part is Model. The model is simply your application store data (in our application we use breeze/web api to read and write model data) The second part is ViewModel - Entity(field) structure of your data. This is a pure code representation of the data and operations in the UI. When using KnockoutJS your ViewModel is pure JavaScript that holds no knowledge of HTML. Keeping the ViewModel abstract this way let us stay simple so we can easily manage more sophisticated behaviour without getting lost :) And finally the last part is View - UI representation of the current state of ViewModel and interactions within it. So when using KnockoutJS your view is simply in your HTML document with declarative binding that links to the ViewModel (alternatively you can use templates that generate HTML using data from your ViewModel). The beauty of solid MVVM library such as Knockout is that you can focus on develping business logic instead of writing code to attach/detach event handler an manually update UI elements whenever data values change. Our ViewModel exposes people as observableArray and hide as observable bool to be bound on the view.

(function (root) {
    var app =;
    var dataservice = app.dataservice;

    var vm = {
        people: ko.observableArray([]),
        hide: ko.observable(true)

        // reveal view when query succeeds
        .then(function () { vm.hide(false); });

    app.peopleViewModel = vm;

    function getAllPersons() {
        return dataservice.getAllPersons(vm.people);


To get data we used our breeze dataservice. We also added our viewModel (peopleViewModel) to the app namespace so it can be accessed and data bound in the Main.js
(function (root) {
    var app =;

    log("Breeze Devices is booting");




And finally in the view I will use KoGrid. I haven't explored KoGrid much, but as far as I have played with it, it is extremely simple and friendly to make work with KnockoutJS. As for all other libraries we'll first download it and add it to the project using NuGet.
Now when all libraries are downloaded and added to the project I will show you what Bundle.Config looks like:
using System.Web;
using System.Web.Optimization;

namespace TaxAppBlog
    public class BundleConfig
        // For more information on Bundling, visit
        public static void RegisterBundles(BundleCollection bundles)
            bundles.Add(new ScriptBundle("~/bundles/jquery").Include(

            bundles.Add(new ScriptBundle("~/bundles/jqueryui").Include(

            bundles.Add(new ScriptBundle("~/bundles/jqueryval").Include(

            bundles.Add(new ScriptBundle("~/bundles/knockout").Include(

            bundles.Add(new ScriptBundle("~/bundles/koGrid").Include(

            bundles.Add(new ScriptBundle("~/bundles/q").Include(

            bundles.Add(new ScriptBundle("~/bundles/breeze").Include(

            bundles.Add(new ScriptBundle("~/bundles/logger").Include(

            bundles.Add(new ScriptBundle("~/bundles/app").Include(
            // Use the development version of Modernizr to develop with and learn from. Then, when you're
            // ready for production, use the build tool at to pick only the tests you need.
            bundles.Add(new ScriptBundle("~/bundles/modernizr").Include(

            bundles.Add(new StyleBundle("~/Content/css").Include(

            bundles.Add(new StyleBundle("~/Content/themes/base/css").Include(

...and also what our master page looks like containg all necessary references:
 <!DOCTYPE html>
   <meta charset="utf-8" />  
   <meta name="viewport" content="width=device-width" />  
   <nav class="container">  
     <div id="header" >  
       <div id="logo">  
         <h1>Tax Application (sample for blogging purposes :))</h1> 
       <ul id="menu">
         <li>@Html.ActionLink("Home", "Index", "TaxPayer")</li>
         <li>@Html.ActionLink("Tax Payer", "Index", "TaxPayer")</li>
     <div id="main">
   @RenderSection("scripts", required: false")  
Notice that we are referencing JavaScript files in the bottom of the page. Why? Well first because the entire visual markup is processed before the script references are and thus will be displayed on the screen while the referenced JavaScript libraries are downloading and being processed into browser memory; and second some of this libraries works with DOM (e.g. Knockout) and in order to do so the browser needs to have created and rendered portions of the DOM before the Knockout executes.
Now finally in the TaxPayer view we bind our grid to the "people" propery of our viewModel but also we use the property "hide" to first show loading gif(ajax-loader.gif) while data is loading and then hide the gif but show the grid:
   ViewBag.Title = "Index";  
 <!DOCTYPE html>  
   <div id="body">  
     <div id="imageWrapper" align="center">  
       <img id="loader" src="images/ajax-loader.gif" data-bind="visible: hide()" />  
     <div id="gridWrapper" data-bind="visible: !hide()">  
       <div id="sandBox" style="height: 200px;" data-bind="koGrid: { data: people,  
          columnDefs: [{ field: 'FirstName', width: 100 },  
                    { field: 'FamilyName', width: 110 }, 
                   { field: 'BirthDate', width: 100 },  
                   { field: 'Profession', width: 100 },  
                   { field: 'Telephone', width: 100 },  
                   { field: 'Address', width: 150 },  
                   { field: 'City', width: 100 },  
                   { field: 'Country', width: 100 },  
                   { field: 'Email', width: 150},  
                   { field: 'Twitter', width: 110 } 
              autogenerateColumns: false,  
              isMultiSelect: true,
              enablePaging: false }">  

Here you can see how easy and elegantly we bind our kogrid. Now when we run the project we'll first get the loading gif:

...until the data is loaded when the grid is shown:

So here we have a taxpayer screen up and running. Now we can think of adding more features (e.g. add/update/delete) and e.g. setup all maintenace screens uniformly like this one.
Thanks for reading this post and letting me know if you like it or not, what would you change and how.

Hello world :)

Welcome to my latest blog! This is my New Year's resolution, even though I don't have much time for it (full time job + wife and three kids + a couple of other occupations, including learning the Luxembourgish language and brushing up on my French and English...).
Here, I'll be writing some C#, some Java script (especially web UI development), some Azzure and at work lately I am doing a lot of SQL and also Sharepoint development (working with some really knowledgeable colleagues) so I'll be posting some interesting things.
Before of any of my posts I'll remind you that my English is not perfect (far from it) with the following statement:
As English is not my mother tongue and before I really start writing anything, I have to apologize for any language mistakes I make.