Requirements of RequireJS

I got couple of errors in my journey to use RequireJS. Looking at stackoverflow, I see many people stumble thru these problems. Many problems stems thru not reading the complete documentation of ‘require’ and lot of wrong and incomplete noise on internet. When you scroll thru RequireJS site, and see an example, you say oh, yea this is so simple, and with out reading much detail you jump into coding. In this article, I will go thru commons errors you may receive and their fix. In end and we will reach to a working code.

This code is referring to ECMA script5 using TypeScript 1.6. You choose ECMA version in project properties -> “TypeScript Build” pane in visual studio.

Here is my simple ‘Hello world’ application

<!DOCTYPE html>
<html lang="en">
<head>
         <script src="scripts/require.js></script>
</head>
<body>
       <div id="content"></div>
</body>
</html>

Here is my simple module

ModuleA {
      export class A {
        public static add(x: number, y: number): number {
           return x + y;
       }
    };
}

here is app.ts file, which is referring to ‘ModuleA’ which is sitting in scripts/js directory.

/// &lt;reference path="scripts/js/modulea.ts"&gt;
/// &lt;reference path="scripts/typings/requirejs/require.d.ts" &gt;

import moduleA = require('./scripts/js/ModuleA');
import _mA = moduleA.ModuleA;

window.onload = () => {
document.getElementById('content').innerHTML = "Answer:" +         _mA.A.add(2, 2).toString();
};

This is as simple as you can get. But when I tried to run this sample, my first build error was

TS1148 Cannot compile modules unless the ‘–module’ flag is provided.

This is simple, you have to go to Project properties by right clicking on project, choose “typescript build” and then choose “AMD” in module system.

After fixing this, I got the next error:

Error TS2306 File ‘E:/code/Require/Require/scripts/js/moduleA.ts’ is not a module. Require E:\code\Require\Require\app.ts 4

And you look at your code and it clearly says it is a module.  But soon you realize to put an ‘export’ in front of Module.

export ModuleA {
   export class A {
          public static add(x: number, y: number): number {
            return x + y;
          };
   };
};

Now, the code is compiling and running, but there is nothing just a blank page. Nothing on console, no clue what’s going wrong, it is just a blank page. There was no other option for me other than to go back and read RequireJS slowly and thoroughly and then I realized my mistake. I forgot “data-main” attribute in my html.

<script src="scripts/require.js" data-main="app"></script>

But, after fixing this, i run the application but there is again nothing on the page. But, now i can hit the break-point in my app.ts file. I hit the breakpoint and then F5, but nothing on the screen.

Back to RequireJS Site, now again reading their documentation slowly and thoroughly. And finally i hit to this :

It is possible when using RequireJS to load scripts quickly enough that they complete before the DOM is ready. Any work that tries to interact with the DOM should wait for the DOM to be ready. For modern browsers, this is done by waiting for the DOMContentLoaded event.

However, not all browsers in use support DOMContentLoaded. The domReady module implements a cross-browser method to determine when the DOM is ready. Download the module and use it in your project like so:

/// <reference path="scripts/js/modulea.ts" />
/// <reference path="scripts/typings/requirejs/require.d.ts" />

import moduleA = require('./scripts/js/ModuleA');
import _mA = moduleA.ModuleA;

require(['./scripts/domReady'], function (domReady) {
domReady(function () {
     document.getElementById('content').innerHTML =                      "Answer:" + _mA.A.add(2, 2).toString();
   });
});

Who knew that document.onload which works every where will not work with RequireJS.

However, using “domReady” solved the problem.

HTH

Parsing complex JSON

We were building a UI control which gets data from JSON. To keep things simple, we wanted our users to specify JSON in a simple “.” manner e.g. if JSON looks like this

var obj = {
     name: 'Rafat Sarosh',
     address: 'Redmond. Seattle'
}

then the HTML can be as simple as this:

<my-control column='name' data='name'>;

and then in our directives we can parse the JSON by simply writing row[data] and get the data. Here row is referring to the JSON obj and ‘data’ is referring to ‘name’. Effectively, row[data] will translate to obj[name] in my directive. So far so good. This all works fine, till you get a simple JSON, and you are more or less certain of the shape of JSON. The user of my directive is happy to write a simple dot notation in his HTML to access the data. But imagine, if JSON is little complex. e.g.

var obj = {

      f1: "Angular",
      f2: { 
             "name": "Rafat", 
             "address": [{ city: 'Seattle'}, {zip: '98059' }] 
           },
      f3: {
             "name": "Tim", 
             "address": [{ city: 'Redmond'}, {house: () => "I am function" }]
           },
      f4: [1, 2, 3]
}

then it becomes little difficult to write a simple parsing function. Imagine the following test cases if user want to access the data as follows:


'f3.address[1].house')()  //Should return "I am function"

'f3.address[0].city' //Should return 'Redmond'

'f2.name' //Should return 'Rafat'

'f4[2]' //Should return 3

'f1' //Should return 'Angular'

So here is the code to parse JSON of any complexity.

function getValue(object: any, path: string, replace: boolean = true): T {

  //convert, all the .,[,] to * so I can break the strings on *
  if (replace) //A switch so I don't do this every time in my recursive loop
      path = path.replace(/\]\.|\.|\[|\]/g, "*");
 
  var index = path.indexOf('*');
  if (index === -1)
      return object[path];

  //Get the first segment
  var firstSegment= path.slice(0, index);
  var remainingSegments= path.slice(index + 1);

  if (object[firstSegment] !== undefined && remainingSegments.length > 0) {
       return getValue(object[firstSegment], remainingSegments, false);
  } else
       return object[firstSegment];
}

Happy Coding!!!

Angular Directive – Table

I have to develop an application where most of the data is displayed in a table. Putting data in a table is pretty straight forward, but when you have multiple pages then you would like to have a table control which can be driven by data and added to pages with one line of HTML. Something like this:

<rmt-table data="data" columns="columns" on-row-clicked="RowClicked(Id)"></rmt-table/>

AngularDirectiveTable

To understand this post, get the full working code for the table directive from this plnkr. This directive takes two arrays of objects, name of columns, and the real data. This table directive has encapsulated paging and sorting functionality. Now dynamically you can supply different data and the page will show you different tables.

Code is straight forward, but I learn few things on the way. My first issue, was to get click on the table back to main controller with the row Id value. Unfortunately, this does not work as straight forward as you may think.

In main controller I have defined a function as follows:

  $scope.RowClicked = function(id) {
    alert(id);
  };

and as you can see in html, this function is defined on on-row-clicked.

<rmt-table data="data" columns="columns" on-row-clicked="RowClicked(Id)"></rmt-table/>

There are many angular courses and documentation where people are advised not to pass the parameter in the function, unfortunately this advice does not hold good anymore. Not only you have to pass the parameter in the function but the parameter name should be exact same as defined in your function definition.

Here is the function in directive:


angular.module('app').directive('rmtTable', function() {
  return {
    restrict: 'E',
    templateUrl: 'myTable.html',
    scope: {
      originalData: '=data',
      columns: '=columns',
      notifyParent: '&onRowClicked',
    },
 snip ....snip 

      $scope.rowClicked = function(row) {
        $scope.notifyParent({
          Id: row.Id
        });

Line 8, wire the external function to the directive. Line 13, calls the external function with the row id value. Here is the rub, you would think you could have called the function as follows:

      $scope.rowClicked = function(row) {
        $scope.notifyParent(row.Id);

But this will not work, this straight and simple way of calling function will not work, no matter what god you believe in :) You may think, that you can do some more javascript jugglery like

      $scope.rowClicked = function(row) {
        $scope.notifyParent()(row.Id);

but still this will not work. It has to be a object. And make sure your object, key must match the parameter you are passing in the function, in my case it is “Id”. Thanks to Dan Wahlin who taught me this trick.

My second issue was to debug the scripts in plnkr. By default, it shows the output in the same window, and if you press F12 you are presented by hundreds of minified JS. Fortunately, in the display IFrame you will find a blue color button which will ‘launch the preview window in a separate window’. In this separate window, it is just you and your code. Much easier to debug the issues.

Go ahead and play with this plnkr. Remember, this is a prototype, there are many things can be improved (for example, max row can also be supplied to directive), this is just to get you started on table directive.

Happy coding!

Tree View control with JavaScript and Knockout for large trees

[To understand this post, get the code from git]

Few days back, I needed  a Tree View, which should be able to show tree with thousands of nodes, a big tree, a really very big tree.

Most of the existing tree views used to crash my browser, they are making the naive mistake to load all the nodes in one shot. The simple solution was to load the nodes on demand, and when you open a node with thousands of children, and then you open another node which again has thousands of children, it is better to close the previous node and let go all their children than crash the browser.

Now, this tree automatic closing the previous node can have little more intelligent, and not necessarily close the node if the number of its children is small. So this tree is little intelligent in few aspect, it loads the children on demand, closes and flushes the nodes which creates the danger of crashing the browser. This tree trade performance over reliability.

To build a tree with JavaScript and  Knockout, you need to understand how knockout templeting works. The template binding populates the associated DOM element with the results of rendering a template. Templates are a simple and convenient way to build sophisticated UI structures. String-based templating is a way to connect Knockout to a third-party template engine. Knockout will pass your model values to the external template engine and inject the resulting markup string into your document.

If you don’t know about KO templating, then you should stop here and read more about it here.

To create a new string template engine, start with an existing nativeTemplateEngine.

CreateStringTemplateEngine method does that task.

SetEngine() {
         this.customTemplateEngine = TreeTempate.createStringTemplateEngine(
                new ko.nativeTemplateEngine(), this.templates);
        ko.setTemplateEngine(this.customTemplateEngine);
}

Inside createStringTemplateEngine, we use passed templateEngine and override it’s makeTemplateSource function to returns our stringTemplate, as follows:

     templateEngine.makeTemplateSource = function (templateName) {
           return new stringTemplate(templateName, templates);
    }

So again, take a nativeTemplateEngine of ko, and override it’s makeTemplateSource and return your own stringTemplate. This makeTemplateSource method is called from ko.renderTemplate function, which in turn calls your template “text” method.

Here is how template engine is implemented, you just have to implement one methods ‘text’:

class stringTemplate {

private _templateName: string;
private _templates: any;

constructor (templateName, templates) {
    this._templateName = templateName;
    this._templates = templates;
}
text (value) {
    if (arguments.length === 0) {
        return this._templates[this._templateName];
    }
    this[this._templateName] = value;
}
};

Templates is defined as follows:

knockoutTemplate

Pay close attention to how templates are recursively calling each other to draw the tree. First template (tree) calls nodes and nodes calls nodeCore to draw the real node. NodeCore has two calls one is to subNodes, and the other one is to nodeContent. Writing this recursive template is key to drawing your tree on the browser.

KO will call stringTemplate, text method again and again with the template names it keep encountering and we will keep returning their value e.g, for ‘tree’ text will return ”

The html of the page is as simple as this:

<html>
    <body>
       <div data-bind="template: { name: TreeTemplate }"  />
    </body>
</html>

<script>
 $(document).ready(function () {
        var d = new data.Data();
        var vm = new Tree.viewModel(d);
        ko.applyBindings(vm);
 });
</script>

This is how the tree will look.
TreeChild

When the Ko hit the following html  data-bind=”template: { name: TreeTemplate }”  It start processing the ‘tree’ template in templates. Which says for each item, please apply the node template. And then node template says for data apply the nodeCore template, and this templating continues on till we reach to nodeContent.

Rest of the code deals with clicking on nodes and loading children on demand, checking the status of tree, and automatically closing nodes which are too big and pose a threat to crash the browser. These cut-off number are configurable in the code, and you should be able to change and play with it. Interesting part of the code is many of the recursive functions. These functions need to traverse down thru the child nodes before they close a parent node.

Hopefully, this will get started you on your journey of creating a TreeView with KO and JavaScript.

Knockout click event knocking you out

Here is my simple viewmodel:

knockoutBindingViewModel

here is a simple html

knockoutBindinghtml

When I open this html in browser, I see removePerson method is called again and again, in fact all three times. Looks like whenever I bind a value of ‘people’ to html,  knockout calls removePerson. I don’t want this repeated call to ‘removePerson’, I want it to be called only on click, not on every bind.

Digging little deeper into knockout, you will find that ko registers the event and because of $data binding context, ko calls the removePerson again and again for every binding. So what is the solution?

Turns out that solution is simple, just remove $data from removePerson method and ko will stop calling this method for every binding.knockoutBindinghtml2

However, you may wonder once you have removed $data context from removePerson, then how your method will know about the person to be removed?

Here comes the ko magic, when ko calls the click method it automatically passes two arguments, first one is the current model value, which will point to the exact person and second one is event object. Read here more.

Once this repeated function call problem is solved, you get into another problem and you realize that your ‘anotherFunction’ is not called and in browser debugger window you find an error.

knockoutBindingError

The error says: Uncaught TypeError: undefined is not a function.

Before you go any further, Read this section again and see if you can find the source of  error.

What happens here is ko calls removePerson in eventHandler context which changes the meaning of “this”. You can see the value of ‘this’ in debugger. The documentation suggest you use ‘self’ or other variables and refer it in the function in place of ‘this’, and don’t be dependent on the ‘this’ value. But, if you are using typescript then you are stuck and isn’t typescript suppose to save you from ‘this’ and ‘self’ funny javascript behavior.

It turns out that there is another easy solution, to preserve the value of ‘this’ in typescript you should use lambda syntax. Just change the function as follows:

knockoutBindingViewModel2

This syntax of typeScript preserve the value of this. Read here how typeScript saves you from ‘this’ and ‘that’ of JavaScript.

Interestingly all this solution is simple once you know it, but if you don’t know,  you may break your head for hours, like I did :) hopefully it will save you some headache of ko and typeScript mood swings.

KISS

Few days back, I came across this clever piece of code, an extremely simplified version. Please give it 5 seconds to see what is happening here. OK, give it 10 second and you will see what this code is doing:


namespace LaLaLambda
{
    class Program
    {
        static void Main(string[] args)
        {
            Process();
        }

        static void  Process (){
            WriteResponse(
                (writer) =>
                {
                    writer.WriteIt("write this line");
                });
        }

        static void WriteResponse ( Action  writeAction)
        {
            using (TextWriter writer = File.CreateText("C:\\temp\\test.txt"))
            {
                writeAction( new MessageWriter (writer));
            }
        }
    }

    class MessageWriter {

        TextWriter tw;

        public MessageWriter (TextWriter t){
            tw = t;
        }
        public void WriteIt (string s)
        {
            tw.WriteLine (s);
        }
    }

I am showing you a very simple code which has all the details removed, and objects are simplified. Imagine, it is a code base of hundreds of files, Process and WriteResponse is in different files and part of different complex object. So what is the problem with the above code. Here are couple of problems I see:

While looking at Process, I am scratching my head, thinking what the hell is writer? Is it a text writer, memory writer or a sand writer (a writer which writes on sand). Remember, this is simplified version, it can be named foo in real code, and you have no clue what is foo? and there is not one object but bunch more object are passed to this anonymous function in real code, and you wonder about all other parameters too.

Second, when you reach to WriteResponse function, somewhere deep in the guts you find writeAction, and then you wonder hah! what writeAction do? You cannot search it as it has come to this function as a delegate. After realizing that, you go back to Process, and you see that it is calling WriteIt on the writer. So, what exactly is writer and then you go back to WriteResponse method again. After couple of jumping back and forth you understand what the hell is happening here.

I will say this is abusing lambda and delegate. Please don’t do it. Write a clever code, appreciate it, show it to your friend, but don’t check it in.

Here is a simplified version of above code:


namespace LaLaLambda
{
    class Program
    {
        static void Main(string[] args)
        {
            Process();
        }

       static void Process()
        {
            WriteResponse("write this line");
        }

        static void WriteResponse(string val)
        {
            using (TextWriter writer = File.CreateText("C:\\temp\\test.txt"))
            {
                MessageWriter mw = new MessageWriter(writer);
                mw.WriteIt (val);
            }
        }
    }

    class MessageWriter {

        TextWriter tw;

        public MessageWriter (TextWriter t){
            tw = t;
        }
        public void WriteIt (string s)
        {
            tw.WriteLine (s);
        }
     }

Above code has all the context together. It is simple, anyone can understand it. You look at it, and immediately you understand it, your eyes will not even wonder up and down.

I know, many of you will be starting your flame thrower to throw many examples at me where we need this kind of code where anonymous calling anonymous and taking a delegate as parameter and they all are tangled together like snakes. Yes, there are legitimate use cases, and use it when you cannot simplify it. For example


  static void  Process (){
            WriteResponse(
                (writer) =>
                {
                   //lot of complicated logic is happening here, for example you are checking writer and depending on it's type you are changing the further logic
                }
             );
        }

You can have different flavor of Process with almost similar construct. Different anonymous can keep the structure of code same but adding a new behavior only in certain cases. A good example of Open/close pattern. The existing code written is not changed, it is closed for modification but using lambda you can extend certain behavior of it.

In last, Write code as Hemingway wrote his stories. keep it simple!

Encroachment on Hard disk

Yesterday, I noticed my 100+ GB SSD has no space left. After investigation, I found my Skydrive is taking 20 GB. It was an easy fix, right click on Skydrive, click on property menu, choose Location tab and set a new location where your file should be synced. I moved all my skydrive files to E: drive and thought this will solve the problem.

Next day, when I came in office, I found again there is no free space left on my c drive. Empty the deleted folder, It helped with few hundred MB but still not much free space left. I looked around, try to find any huge files, music, pictures, video etc and deleted many files from C drive.  All this deleting did not free up any significant amount of space. Then I went ahead and tried the followings (you can reach to all these options by right clicking on drive and choos property):

  • Disk cleanup.
  • Compress this drive to save disk space.
  • Uncheck “allow files on this drive to have contents indexed in addition to file properties”
  • On tools tab you will find, ‘Error Checking’
  • Optimize and defragment drive

I ran all the above options, still no luck! Hard disk is still showing no space left.

Searched the hidden files (In explorer, click on view tab and check on  show all the hidden files to see hidden files) but found nothing.

When all else failed, I got a TreeSize utility (not recommending any particular product, as I did not use anything from web. There are many products, let me know which one you like) and looked at my hard disk. TreeSize showed me two hidden files hiberfile.sys and pagefile.sys both of 20 GB each. These files are not visible to naked eye, you have to use one of the TreeSize utilities.  Now how to delete this file:

Start Command Prompt as “Run as administrator.”
type powercfg -h off

This gets rid of your hiberfile.sys. But now, there is no more option to set your computer to hibernation. Hibernation feature creates this file. You can turn it ‘on’ by typing powercfg -h on.

for pagefile.sys, go to ControlPanel -> system->click on Advance -> then setup your page file size to a reasonable size.

Just fixing this freed up 40 GB for me.

Hope this will save you some time. I wasted almost two hours to solve this problem.

 

TypeScript taking care of ‘This’ and ‘That’ of JavaScript

The bane of javascript developer is the powerful keyword, “this”. ‘this’ is a variable that’s set when a function is called. it is a very powerful and flexible feature, but it comes at the cost of always having to know about the context that a function is executing in. This can be extremely confusing when a function is used as a callback.

See the simple TypeScript and JavaScript equivalent code. Look for the problem in below code?

TypeScript

class Greeter {
    element: HTMLElement;

    constructor(element: HTMLElement) {
        this.element = element;
        this.element.innerHTML += "The time is: " + new Date().toUTCString();
    }

    start(){
        setInterval(function ()  {
            this.element.innerHTML = "The time is: " + new Date().toUTCString(), 500
        });
    }
}

window.onload = () => ; {
    var greeter = new Greeter(document.getElementById('content'));
    greeter.start();
};

JavaScript

var Greeter = (function () {
    function Greeter(element) {
        this.element = element;
        this.element.innerHTML += "The time is: " + new Date().toUTCString();
    }
    Greeter.prototype.start = function () {
        setInterval(function () {
            this.element.innerHTML = "The time is: " + new Date().toUTCString(), 500;
        });
    };
    return Greeter;
})();

window.onload = function () {
    var greeter = new Greeter(document.getElementById('content'));
    greeter.start();
};

So do you see the problem in above code?

This simple code will not work. This is because the ‘this’ being used in the function created by ‘greeter.start()’ will be set to ‘window’ instead of our ‘greeter’ object. Here is the error message you will see:

Unhandled exception at line 8, column 13 in http://localhost:51370/app.js

0x800a138f – JavaScript runtime error: Unable to set property ‘innerHTML’ of undefined or null reference

This happens as a result of calling ‘start()’ from window.onload. There is no dynamic binding for ‘this’ other than Window. (note: under strict mode, this will be undefined rather than window).

We can fix this by making sure the function is bound to the correct ‘this’ before we return the function to be used later. This way, regardless of how its later used, it will still be able to see the original ‘greeter’ object.

To fix this, you will often see in JavaScript, people use ‘that’ variable to bind the right ‘this’ to it. (SideNote: I will prefer some other more descriptive name than ‘that’, but there are too many people using this to set it as a convention.)

To fix the above JavaScript, we need to add one line in start() as follows, and then in SetInterval refer to ‘that’, so no matter from where start() method is called it will always refer to the right ‘this’.

 Greeter.prototype.start = function () {
        var that = this;
        setInterval(function () {
            that.element.innerHTML = "The time is: " + new Date().toUTCString(), 500;
        });
    };

Now, all this can turn out to be complicated if you have many functions and functions returning functions returning functions etc. However, if you are using TypeScript, you just change the simple function call with a lambda call and everything will be taken care for you. Notice, i am still using ‘this’, in SetInterval. Isn’t it neat?
TypeScript

start(){
        setInterval(() =>;  {
            this.element.innerHTML = "The time is: " + new Date().toUTCString(), 500
        });
    }

Switching the function expression to use the lambda syntax ( ()=>{} ) rather than the JavaScript function expression will automatically capture the ‘this’ available when the function is created rather than when it is invoked.

Now here is new TypeScript function, notice the only lamda difference

class Greeter {
    element: HTMLElement;

    constructor(element: HTMLElement) {
        this.element = element;
        this.element.innerHTML += "The time is: " + new Date().toUTCString();
    }

    start(){
        setInterval(() =>;  {
            this.element.innerHTML = "The time is: " + new Date().toUTCString(), 500
        });
    }
}

window.onload = () =>; {
    var greeter = new Greeter(document.getElementById('content'));
    greeter.start();
};

and here is equivalent new JavaScript function:

var Greeter = (function () {
    function Greeter(element) {
        this.element = element;
        this.element.innerHTML += "The time is: " + new Date().toUTCString();
    }
    Greeter.prototype.start = function () {
        var _this = this;
        setInterval(function () {
            _this.element.innerHTML = "The time is: " + new Date().toUTCString(), 500;
        });
    };
    return Greeter;
})();

window.onload = function () {
    var greeter = new Greeter(document.getElementById('content'));
    greeter.start();
};

Hopefully with this your love for TypeScript increased little more :)

MVC 5, OAuth2, OWIN and Wireless Speakers

I was looking at ASP.NET MVC 5 in Visual Studio 2013. Here is step by step tutorial by Rick Anderson. Here is another great tutorial by Rick on how to add Oauth2  Sign-on.

Note: Go thru the above tutorial, generate the code and have it working. We will be referring to this code often. Should not take more than 10 min. Rick Anderson has done an awesome job.

Lots of code is generated by Visual studio scaffolding for you. However, while trying to understand what is going on, I felt like a man from 1940 looking at wireless speakers. You see that music is coming out of speakers but you don’t know how, where are the wires?

There are pieces of code which sort of make sense, but you don’t know who is calling them, what exactly they are doing. How all this code is wired. There are lots of behind the scene wiring happening.

Generated code, created more unanswered questions than the questions I got answered. I will make this post a step by step journey to completely understand MVC 5, Owin and Katana interaction. I will keep the repetition to minimum. Different pieces of puzzle are explained by many talented people, so I will be redirecting you to them. The only problem is all this writing is scattered in different places. Many articles are written by expert and they assume that you are already familiar with other piece of technology. However, this can be daunting for new developers who are left of their own to connect all the dots. This post is amalgamation of pieces and about solving the puzzle.

So without any further adieu, to completely understand the code and what is happening here is the laundry list of things you need to know:

Only after knowing all these pieces and thrashing on internet between many blogs, articles and stackoverflow slowly you will start completing the picture. I saw lot of frustration from new people to piece the story together. Same time many writers, Microsoft was trying their best to help you understand, they are often fighting the battle to keep things simple but still give you the full pictures. It is a fine balance to give you enough details but still keep things simple, as you can see in this article, i will be loosing the simplicity many times as i will get in to code which will muddy the water. But, hopefully you will be left with many pointers to investigate your own and slowly everything will fall in place.

Now, coming back to code. Here are the few questions, jumped at me while going thru the MVC5 application.

  • What is this attribute I see on one of the class.
    [assembly: OwinStartupAttribute(typeof(WindWood.Startup))]

    Note: windwood is my application name

  • There is a startup class, which has only one method called “Configuration”, what is it? Why it is called Configuration, can I call it something else?
  • Just uncommenting  app.UseGoogleAuthentication(); makes my google login work.  Magic!!! But how and why?
  • Whats the below code do, I don’t see any method call UseFacebookAuthentication on IAppBuilder. What the hell, am I hallucinating?

    app.UseFacebookAuthentication(
    appId: "25345345688543",
    appSecret: "1456785555658b24964345332224a02");
    
  • How the login details saved in DB.

You press F5, and every thing works fine. Kudos to Microsoft!  But If you are curious you will wonder how all this is wired up? So lets dig it up. First thing, I wanted to know what happens when you press F5. For that investigation, I have to step out of the MVC5 and get into Katana.

You can get the Katana code from github.  (Note: get the Katana code and have it open in another instance of visual studio. It is important to have the code in front of you to understand all the wiring.) As you know, OWIN is a standard interface between .NET web servers and web applications and Katana is a flexible set of components for building and hosting OWIN-based web applications.

We will go far from MVC but not too far (if you will go too far, then you may get lost in Http and IIS, TCP/IP and Network stack), we don’t want to get lost. So keeping this in mind, lets look at the MVC code. We found the following code in Startup.cs.

using Microsoft.Owin;
using Owin;
[assembly: OwinStartupAttribute(typeof(WindWood.Startup))]
namespace WindWood{
  public partial class Startup {
      public void Configuration(IAppBuilder app){
           ConfigureAuth(app);
      }
}}

Hmmm .. .so what is it, and who calls it. You can look up and down in your project but you will never find it.  Actually the answer is hidden in Katana code.  Now, lets take  a look at the Katana, but before that lets talk about OWIN for a bit. OWIN is a specification that describes how components in a HTTP pipeline should communicate. The goal of OWIN is to decouple server and application. All the interaction between web server and application reduces to a very small set of types and single function signature known as AppFunc. AppFunc is defined in OwinAppContext.cs as


using AppFunc = Func<idictionary<string,object>, Task>;

AppFunc is a delegate which takes IDictionary and returns Task when it has finished processing. This IDictionary is a generic object bag, it carries all the states for application state, request and server state etc. This bag is passed from one component to another.

OWIN-compatible web server is referred to as a “host“, and an instance of an application delegate (described below) is referred to as an “Application“. In simple words, host invokes an application, and provids it with the key-value dictionary.

These two simple, a key-value dictionary and application delegate element enables this beautiful harmony between different framework and components to interoperate in an OWIN Pipeline.

So how does the Applications are provided to host? Here is another important actor of OWIN implementation, it is no more part of specification, but he is the glue between host and application. Application is provided to a host using the IAppBuilder interface.

public interface IAppBuilder{
       IDictionary<string, object> Properties { get; }
       object Build(Type returnType);
       IAppBuilder New();
       IAppBuilder Use(object middleware, params object[] args);
       }

Ok, so far we have seen IAppBuilder,  and understood every component in an OWIN-based application supplies an application delegate to a server. The components are then chained together into a pipeline into which an OWIN-based server pushes requests. Now, lets understand Katana on high level. Katana is a flexible set of components for building and hosting OWIN-based web applications . There are different stacks of  Katana and they consists of  following layers:

Host: The process that runs the application and can be anything from IIS or a standalone executable, to your own custom program. The host is responsible for startup, loading of other OWIN components and shutting down gracefully.

Server: Responsible for binding to a TCP port, constructing the environment dictionary and processing requests through an OWIN pipeline.

Middleware: The name given to all of the components that handle requests in an OWIN pipeline. It can range from a simple compression component to a complete framework such as ASP.NET Web API, though from the server’s perspective, it’s simply a component that exposes the application delegate.

Application: This is your code. Because Katana is not a replacement for ASP.NET but rather a new way to compose and host components, existing ASP.NET Web API and SignalR applications remain unchanged, as those frameworks can participate in an OWIN pipeline. In fact, for these kinds of applications, Katana components will be visible only in a small configuration class.

So, on a high level, we can guess that our Startup code is called from Katan. Let’s dig deep to see how Katana get started and how its code is wired up with out code. To see Katana stack implementation, lets start our journey from OwinHttpHandler in Katana code. OwinHttpHandler process request from System.Web as OWIN requests. When we press F5, IIS Express starts and an OwinHttpHandler is inserted in pipeline as HttpHandler. This is how an Owin Application looks.

owin

Remember. for Owin, application is just an instance of AppDelegate, which is defined as

Func<IDictionary<string, object>, Task>

Just for fun lets walk the trail till we reach to our Startup class which we seen in our application and Visual Studio was kind enough to write for us.

Owin hosts provides a factory method that accepts an AppDelegate as a parameter. In  ASP.NET an HttpHandler accepts this as a parameter.  Take a look at OwinHandler code

internal OwinHttpHandler(string pathBase, Func appAccessor)
   { _pathBase = pathBase;
     _appAccessor = appAccessor;
   }

However, the default OWIN Application get processed by this constructor

public OwinHttpHandler():
  this(Utils.NormalizePath(HttpRuntime.AppDomainAppVirtualPath), OwinApplication.Accessor){
 }

Notice here the  Accessor is a static method defined as follows in OwinApplication.cs


internal static<OwinAppContext> Accessor
{
 get { return () => _instance.Value; }
 set { _instance = new Lazy(value); }
}

Accessor is a delegate to a function, which means if you call Accessor.Invoke() you will get back a OwinAppContext, and _instance is defined as

private static Lazy _instance = new Lazy(OwinBuilder.Build)

Lazy initialization is used to defer the creation of a large or resource-intensive object, or the execution of a resource-intensive task. To prepare for lazy initialization, you create an instance of Lazy. The type argument of the Lazy object that you create specifies the type of the object that you want to initialize lazily. The constructor that you use to create the Lazy object determines the characteristics of the initialization. Lazy initialization occurs the first time the Lazy.Value property is accessed.

So, when _appAccessor is touched way up in HttpHandler BeginProcessing, the whole domino effect of Lazy initialization starts and OwinBuilder.Build static method is called to build an OwinAppContext.

internal static OwinAppContext Build(){
   Action<IAppBuilder> startup = GetAppStartup();
   return Build(startup);
   }

The above function in short returning a OwinAppContext. But in between, GetAppStartup is the method which in wiring your code with the OwinCode. Let’s see what happens in GetAppStartup, this method calls DefaultLoader Load method (DefaultLoader.cs), which in turn checks the following:

  1. If the web.config file has an appSetting with key=“owin:AppStartup”, the loader uses the setting value. The value must be a valid .NET-type name.
  2. If the assembly has the attribute [assembly: OwinStartup(typeof(MyStartup))], the loader will use the type specified in the attribute value.
  3. If neither of these conditions are true, the loader will scan the loaded assemblies looking for a type named Startup with a method that matches the signature void Configure(IAppBuilder app).

The above point 2, answers one of my first question about OwinStartup attribute.

[assembly: OwinStartupAttribute(typeof(WindWood.Startup))]

This Attribute is used to find  the entry point. The OwinStartup attribute overrides the naming convention.

Basically, GetAppStartup returns an Action<IAppBuilder> by making a delegate out of Startup type, and a method called “Configuration”. The delegate is made in DefaultLoader.cs, in case you are curious.

return builder => methodInfo.Invoke(instance, new[] { builder })

Here methodInfo is “Configuration” function which is taking an IAppBuilder as a parameter. This answer my another question, Configuration is a hardcoded string in Katana, so I must have a method name called “configuration”. This is using the naming convention. Katana looks for a class name Startup in namespace matching the assembly name or the global namespace and then look for a method called “Configuration”.  You can use appSetting element to override the naming convention. To use the some other friendly name you have to define an appSetting element in the configuration file.


 <add key="appStartup" value="type" />

Look here, to see an example of configuration file use.

Now, looking back up, you can see that startup is defined as follows.

Action startup = GetAppStartup();

This means startup is an Action which is pointing to my “Configuration” method, and ready to take a IAppBuilder parameter. The next line

return Build(startup)

builds a AppBuilder object, builds a dictionary of name-value pair and calls the startup by passing AppBuilder.

var builder = new AppBuilder();
 builder.Properties[Constants.OwinVersionKey] = Constants.OwinVersion;
 builder.Properties[Constants.HostTraceOutputKey] = TraceTextWriter.Instance;
 builder.Properties[Constants.HostAppNameKey] = HostingEnvironment.SiteName;
 builder.Properties[Constants.HostOnAppDisposingKey] = OwinApplication.ShutdownToken;
 builder.Properties[Constants.HostReferencedAssemblies] = new ReferencedAssembliesWrapper();
 builder.Properties[Constants.ServerCapabilitiesKey] = Capabilities;
 builder.Properties[Constants.SecurityDataProtectionProvider] = new MachineKeyDataProtectionProvider().ToOwinFunction();
 builder.SetLoggerFactory(new DiagnosticsLoggerFactory());
 startup(builder);

You can find the complete code snippet in OwinAppContext.cs file. So what is happening here exactly, let me explain again:

Startup(builder)

Startup is a delegate pointing to our configuration code, which is taking the AppBuilder as parameter. Call to Configure  setup up all the middleware we have defined in our ConfigureAuth.

After executing our “Configuration” function,  AppBuilder’s Build function is called and a pipeline entry point is set as follows:

AppFunc = (AppFunc)builder.Build(typeof(AppFunc));

Remember AppFunc is defined as follows:

using AppFunc = Func<idictionary<string, object="">, Task>;

By now, we have a OwinAppContext fully cooked, with all the middleware set and a AppFunc set to get things rolling. This nice OwinAppContext is given to OwinHttpHandler, which uses it in his BeginProcessRequest to get hold of AppFunc and call all the middlewares.

The Above startup(builder) actually kickstart things in our application. Now coming back to our code, we see Configuration is calling ConfigureAuth method.

public void ConfigureAuth(IAppBuilder app)
 {
 --snip --
 app.UseFacebookAuthentication(
 appId: "23423443",
 appSecret: "234232343212212434a02");

app.UseGoogleAuthentication();
 }

Remember, above code had another confusion for me, where is app.UseGoogleAuthentication comes from? I don’t see this code anywhere and app also does not have any method of this name. Ok, let’s go back to Katana, and there you will find that these are Extension methods on IAppBuilder. These extension methods internally calls “Use” method to populate the middleware.

Now once you understand all this, Looked at the code and seen how all this is wired together you should forget all about it. What you have to remember is that you need to have a class which is called Startup and should have a configuration method on it and takes an IAppBuilder as a parameter.

In my next post I will write how login information is getting saved in tables.

I hope, I am leaving you with some pointers to deepen your understanding of all the actors and how all this is connected together.  Please feel free to let me know if I missed something or how to improve it further.

________________________________________________________

Side note

You can run just Katana without IIS. For that Get Chocolotey. Chocolatey NuGet is a Machine Package Manager, somewhat like apt-get, but built with Windows in mind. After install Chocolotey, run the following from a command line

Cinst owinhost

Change your  Web, Start Action properties of project and give Katana as Start external program.

Start external program, specifies the full path of an alternative program that Visual Studio will run instead of starting the browser. The alternative program must have an .exe file-name extension. owinhost.exe, loads the HTTP listener upon launch and then begin listening on port 8080. The port is configurable on the command line. To invoke the application and send requests all you do is calling http://localhost:8080.

Check Glavs post (another) on this to know more and how to write a plain vanila Owin application.

_____________________________________________________________________________________

More reading :

Scott Allen blogs. Comment on Scotts Allen blog was inspiration for this post.

Howard Dierking articles on msdn. 

Dino Esposito article on MSDN

ASP.NET MVC Pipeline

Request handling pipeline poster