Shimming and Wrapping OWIN Middleware (Katana Part 5)

Wednesday, November 13, 2013 by K. Scott Allen
6 comments

Sometimes I’m not interested in what the OWIN pipeline is doing as a whole, but I’m trying to figure out what each piece of middleware is doing in the pipeline configured by someone else. This is useful, for example, when debugging which piece of middleware is grabbing a request and short-circuiting the pipeline by sending an immediate response.

What the following IAppBuilder can do is wrap a real IAppBuilder and add a middleware wrapper for every piece of middleware added to the real IAppBuilder.

It’s middleware-middleware mania!

public class WrappingAppBuilder<TWrapper> : IAppBuilder
{
    private readonly IAppBuilder _inner;
    private readonly object _wrappingOptions;

    public WrappingAppBuilder(IAppBuilder inner, object wrappingOptions)
    {
        _inner = inner;
        _wrappingOptions = wrappingOptions;
    }

    public IAppBuilder Use(object middleware, params object[] args)
    {
        _inner.Use(typeof (TWrapper), _wrappingOptions, GetDescription(middleware));
        return _inner.Use(middleware, args);
    }

    private string GetDescription(object middleware)
    {
        var type = middleware as Type ?? middleware.GetType();
        return type.Name;
    }

    public object Build(Type returnType)
    {
        return _inner.Build(returnType);
    }

    public IAppBuilder New()
    {
        return _inner.New();
    }

    public IDictionary<string, object> Properties
    {
        get
        {
            return _inner.Properties;
        }
    }
}

The wrapper is specified as a generic type parameter. The following wrapper will allow an external observer to inspect the environment dictionary before it goes into the next piece of middleware, and then again during the return.

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

public class WrappingLogger
{
    private readonly AppFunc _next;
    private readonly WrappingOptions _options;
    private readonly string _middlewareDescription;

    public WrappingLogger(
        AppFunc next, 
        WrappingOptions options, 
        string middlewareDescription)
    {
        _next = next;
        _options = options;
        _middlewareDescription = middlewareDescription;
    }

    public async Task Invoke(IDictionary<string, object> environment)
    {
        _options.BeforeNext(_middlewareDescription, environment);
        await _next(environment);
        _options.AfterNext(_middlewareDescription, environment);
    }
}

The above class is using the following options.

using LogFunc = Action<object, IDictionary<string, object>>;

public class WrappingOptions
{ 
    public LogFunc BeforeNext { get; set; }
    public LogFunc AfterNext { get; set; }
}

And configuration is as easy as:

public void Configuration(IAppBuilder app)
{
    var options = new WrappingOptions()
    {
        BeforeNext = (middleware, environment) =>
            Debug.WriteLine("Calling into: " + middleware),
        AfterNext = (middleware, environment) =>
            Debug.WriteLine("Coming back from: " + middleware),
    };

    app = new WrappingAppBuilder<WrappingLogger>(app, options);

    // ...
    // the rest of the middleware
}

The above options provide some very crude request logging, but with a little work you can watch for dictionary changes and add timing information.

Coming up soon: the new identity bits.

Previous posts in this series.

Simple Logging Middleware (Katana Part 4)

Tuesday, November 12, 2013 by K. Scott Allen
0 comments

Perhaps all you want to do with middleware is perform some simple logging for an HTTP request and response.

Here’s a class that can hold the options for which keys the application needs to log, and and an Action to encapsulate the logging logic.

public class SimpleLoggerOptions
{
    public IList<string> RequestKeys { get; set; }
    public IList<string> ResponseKeys { get; set; }
    public Action<string, object> Log { get; set; }
}

The logging middleware itself just needs to invoke the Action delegate at the appropriate time, and with the appropriate values, all the while letting each request pass through into the rest of the pipeline by calling into the next AppFunc.

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

public class SimpleLogger
{
    private readonly AppFunc _next;
    private readonly SimpleLoggerOptions _options;

    public SimpleLogger(AppFunc next, SimpleLoggerOptions options)
    {
        _next = next;
        _options = options;
    }

    public async Task Invoke(IDictionary<string, object> environment)
    {
        foreach (var key in _options.RequestKeys)
          {
            _options.Log(key, environment[key]);            
        }   

        await _next(environment);

        foreach (var key in _options.ResponseKeys)
        {
            _options.Log(key, environment[key]);
        }   
    }
    
}

Of course there could be some additional code inside the middleware to validate parameters and make sure a key exists before indexing into the environment dictionary, but given a simple extension method to help with registration …...

public static class AppBuilderExtensions
{
    public static IAppBuilder UseSimpleLogger(
        this IAppBuilder app, 
        SimpleLoggerOptions options)
    {
        return app.Use<SimpleLogger>(options);
    }
}

… it is now easy to add logging to any application by registering the simple logger as the first piece of middleware. The keys specified below are all keys required by the OWIN specification

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
        var options = new SimpleLoggerOptions
        {
            Log = (key, value) => Debug.WriteLine("{0}:{1}", key, value),
            RequestKeys = new[] {"owin.RequestPath", "owin.RequestMethod"},
            ResponseKeys = new[] {"owin.ResponseStatusCode"}
        };
        app.UseSimpleLogger(options);


        // ... and more ...
    }
}

Next up: how to shim and log every other piece of middleware.

Previous posts in this series.

Writing OWIN Middleware

Monday, November 11, 2013 by K. Scott Allen
5 comments

Months ago I kicked off a series a posts about working with Katana and OWIN.

 

In those posts I mostly used helper methods provided by Katana packages to add functionality to the OWIN pipeline using simple Funcs.

public class Startup
{
    public void Configuration(IAppBuilder app)
    {         
        app.UseHandlerAsync((request, response) =>
        {
            res.ContentType = "text/plain";
            return res.WriteAsync("Hello, World!");
        });
    }
}

The helper method here is UseHandlerAsync, which is an extension method from Owin.Extensions that allows me to register a delegate that takes an OwinRequest and an OwinResponse and returns a Task. Behind the scenes, UseHandlerAsync transforms the OWIN environment of IDictionary<string, object> for each request into parameters that are easier to use (OwinRequest and OwinResponse) then calls into my code.  The end result is a pipeline that responds to every request with “Hello!”.

Once More, But A Little Bit Lower

You can work with Katana at a lower level and for more complex middleware, you typically will need more than just a delegate.

The basic pattern followed by most middleware components is to first provide an options object that someone can use to configure the middleware and customize the behavior for a specific application.

For example, let’s imagine we still want middleware to write a greeting like “Hello, World!”, but provide options to change the text and also include a timestamp.

public class HelloWorldOptions
{
    public HelloWorldOptions()
    {
        IncludeTimestamp = true;
        Name = "World";
    }

    public bool IncludeTimestamp { get; set; }
    public string Name { get; set; }
}

Now we can write a full middleware component that uses these options and the basic OWIN environment to respond to requests.

public class HelloWorldComponent
{
    readonly AppFunc _next;
    readonly HelloWorldOptions _options;

    public HelloWorldComponent(AppFunc next, HelloWorldOptions options)
    {
        _next = next;
        _options = options;
    }

    public async Task Invoke(IDictionary<string, object> environment)
    {
        var response = environment["owin.ResponseBody"] as Stream;
        using (var writer = new StreamWriter(response))
        {
            if (_options.IncludeTimestamp)
            {
                await writer.WriteAsync(DateTime.Now.ToLongTimeString());
            }
            await writer.WriteAsync("Hello, " + _options.Name + "!");
        }
    }
}

The class needs to have a constructor that takes an AppFunc and an options object. The AppFunc represents the next middleware component in the pipeline, and we’ll see an example in a later post where we will use the next AppFunc, but here we are ignoring any other middleware and taking control of every response.

The class also needs an Invoke method that matches the AppFunc delegate (Func<IDictionary<string, object>, Task>).

Finally, most middleware will provide extension methods for IAppBuilder that make it easy to configure themselves into the pipeline.

public static class AppBuilderExtensions
{
    public static void UseHelloWorld(
        this IAppBuilder app, HelloWorldOptions options = null)
    {
        options = options ?? new HelloWorldOptions();
        app.Use<HelloWorldComponent>(options);
    }
}

Now spinning up a web service that will greet the earth looks like this:

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
        app.UseHelloWorld(new HelloWorldOptions
        {
            IncludeTimestamp = false,
            Name = "Earth"
        });
    }
}

The above code represents the same functionality we had before, but with a lot more flexibility.

Coming up next: logging middleware.

New C# Generics Course

Tuesday, October 1, 2013 by K. Scott Allen
11 comments

csharp genericsMy new C# Generics course on Pluralsight includes topics for everyone.

For beginners:

- Why generic types are useful.

- A demonstration of all  the concrete collection types in System.Collections.Generic

- How to build basic generic types (generic classes, generic interfaces, and generic delegates).

For intermediates:

- How to apply generic constraints (including what you can and can’t do with constraints).

- How to cleanup generic code (remove those ugly type parameters from business logic).

- How to use built-in generic delegates like Func, Action, Predicate, Converter, and EventHandler.

On the advanced side:

- How to refactor covariant and contravariant interfaces out of an invariant generic IRepository interface that works against the Entity Framework.

- How to use reflection to discover generic parameters and generic type definitions, as well as build generic types and invoke generic methods in late bound fashion.

- How to build an IoC container with a fluent-ish API that supports nested dependencies and unbound generics.

Custom Serialization with JSON.NET, WebAPI, and BsonDocument

Monday, September 30, 2013 by K. Scott Allen
7 comments

JSON.NET has a simple and easy extensibility model, which is fortunate because I recently ran into problems serializing a collection of BsonDocument.

The first problem with serializing a BsonDocument is how each document exposes public conversion properties like AsInt32, AsBoolean, and AsDateTime. Trying to serialize all public properties  is guaranteed to throw an exception on at least one of these conversion properties.

Fortunately, the MongoDB C# driver includes a ToJson extension method which doesn’t try to serialize the conversion properties. But, ToJson can also create problems because ToJson doesn’t produce conforming JSON by default. For example, ObjectId is represented in the output as ObjectId("… id …"), which causes JSON.parse to fail in a browser.

The solution is to provide a custom JSON.NET converter which uses the ToJson method with some custom settings. In the following code, IMongoDbCursor is a custom abstraction I have to wrap server cursors in Mongo, and is essentially an IEnumerable<BsonDocument>.

public class MongoCursorJsonConverter : JsonConverter
{
    public override void WriteJson(
        JsonWriter writer, object value, JsonSerializer serializer)
    {
        var cursor = (IMongoDbCursor) value;
        var settings = new JsonWriterSettings
            {
                OutputMode = JsonOutputMode.Strict
            };

        writer.WriteStartArray();

        foreach (BsonDocument document in cursor)
        {
            writer.WriteRawValue(document.ToJson(settings));            
        }

        writer.WriteEndArray();
    }

    public override object ReadJson(
        JsonReader reader, Type objectType, 
        object existingValue, JsonSerializer serializer)
    {
        throw new NotImplementedException();
    }

    public override bool CanConvert(Type objectType)
    {
        var types = new[] {typeof (MongoDbCursor)};
        return types.Any(t => t == objectType);
    }
}

The whole key is the foreach statement inside of WriteJson, which uses WriteRawValue to put strictly conforming JSON in place. Another option is to treat a BsonDocument as an IDictionary, which breaks down complex values into primitives.

writer.WriteStartArray();

foreach (BsonDocument document in cursor)
{   
    serializer.Serialize(writer, document.ToDictionary());
}

writer.WriteEndArray();

The last piece is to plugin the converter during WebApi configuration.

var formatters = GlobalConfiguration.Configuration.Formatters;
var jsonFormatter = formatters.JsonFormatter;
var settings = jsonFormatter.SerializerSettings;
jsonFormatter.SerializerSettings.Converters.Add(new MongoCursorJsonConverter());

.

Moving Data In An AngularJS Directive

Wednesday, September 11, 2013 by K. Scott Allen
12 comments

This plunkr demonstrates a few different scenarios and capabilities when moving data between a model and a directive. Like other places in Angular JS there are quite a number of different approaches that work, which grants a lot of flexibility but also leads to some confusion.

The example uses a simple controller.

module.controller("TestController", function($scope){
    
    $scope.magicValue = 1; 
     
    $scope.increment = function(){
      $scope.magicValue += 1;
    };
    
});

The markup for the sample displays the controller’s magicValue, and provides a button to change the value. There are also 5 versions of a valueDisplay directive.

<div ng-controller="TestController">
  Controller: {{magicValue}}
  <button ng-click="increment()">Click</button>

  <ol>
    <li><value-display1 value="magicValue"></value-display1></li>

    <li><value-display2 value="magicValue"></value-display2></li>

    <li><value-display3 value="{{magicValue}}"></value-display3></li>

    <li><value-display4 value="magicValue"></value-display4></li>
       
    <li><value-display5 value="{{magicValue}}"></value-display5></li>
  </ol>
</div>

The first version of valueDisplay will put the value on the screen, but will never update the screen if the magic value changes. This approach is only reasonable for static data since the directive reads the value directly from the controller’s scope (using the name specified in the attribute), places the value in the element, then never looks back.

module.directive("valueDisplay1", function () {
    return {
    restrict: "E",
       link: function (scope, element, attrs) {
           element.text(scope[attrs.value]);
       }
   };
});

The second version of valueDisplay uses a $watch to update the screen as the model value changes. Notice the attribute value (value="magicString")  is still working like an expression to retrieve and watch data directly from the controller’s scope.

module.directive("valueDisplay2", function () {

     return {
        restrict: "E",
        link: function (scope, element, attrs) {
            scope.$watch(attrs.value, function(newValue) {
                element.text(newValue);
            });
        }
    };

});

The third version is a slight variation that will read and observe data in the value attribute itself instead of going to the controller. There are a few differences to note. First, the directive will always retrieve the value as a string. Secondly, the view has to use interpolation to place the proper value into the attribute (i.e. value="{{magicValue}}"). Finally, $observe is used instead of a scope watch since the directive wants to watch changes on the attribute, not the controller scope.

module.directive("valueDisplay3", function () {
 return {
    restrict: "E",
    link: function (scope, element, attrs) {
        attrs.$observe("value", function (newValue) {
            element.text(newValue);
        });
    }
  };
});

The fourth version moves to using an isolate scope to detach itself from the parent scope. Two-way data binding is setup between the directive's isloated scope and the parent model using using "=", so the framework will take care of pushing and pulling data between the directive’s scope and the parent scope. The view still chooses the model property to use with the value attribute in the markup (value="magicValue"), and displays the value using a template (which will automatically watch for changes).

module.directive("valueDisplay4", function () {
     return {
        restrict: "E",
        scope: {
            value: "="
        },
        template: '{{value}}',
    };
});

The final version of valueDisplay uses attribute binding ("@"), which also works in both directions and will update the view as the model value changes (and vice-versa, if we had an input). 

module.directive("valueDisplay5", function () {
    return {
        restrict: "E",
        scope: {
              value: "@"
        },
        template: '{{value}}',
    };
});

In the end, there are even more options available (we didn’t even look at executing expressions to move data), but that can be a topic for a future post. I currently tend to use option 4 for binding complex objects from the model to a directive, and option 5 for moving simple customization values like headings, labels, and titles.

Hosting A JavaScript Engine In .NET

Tuesday, September 10, 2013 by K. Scott Allen
10 comments

ClearScript is simple to use and allows me to host either V8 or Chakra. The samples on the home page show just how easy is the interop from C# to JavaScript and vice versa.

I use a simple wrapper because the only API I need is one to Evaluate small script expressions.

public interface IJavaScriptMachine : IDisposable
{
    dynamic Evaluate(string expression);
}

The following implementation sets up a default environment for script execution by loading up some required scripts, like underscore.js. The scripts are embedded resources in the current assembly.

public class JavaScriptMachine : JScriptEngine, 
                                 IJavaScriptMachine
{      
    public JavaScriptMachine()
    {
        LoadDefaultScripts();                
    }
    
    void LoadDefaultScripts()
    {
        var assembly = Assembly.GetExecutingAssembly();
        foreach (var baseName in _scripts)
        {
            var fullName = _scriptNamePrefix + baseName;
            using (var stream = assembly.GetManifestResourceStream(fullName))
            using(var reader = new StreamReader(stream))
            {
                var contents = reader.ReadToEnd();
                Execute(contents);
            }
        }
    }

    const string _scriptNamePrefix = "Foo.Namespace.";
    readonly string[] _scripts = new[]
        {
            "underscore.js", "other.js"
        };       
}

For examples, check out the ClearScript documentation.

by K. Scott Allen K.Scott Allen
My Pluralsight Courses
The Podcast!