Rinat Abdullin on Lokad Shared Libraries

Microsoft Feedback 2010

2009-12-10T07:56:34Z

There is usually a lot to learn from large companies like Microsoft, or less large ones.

However, it takes a bit of learning on your own before you could understand and appreciate details and partially hidden interactions behind what is revealed.

Fore example, that’s how Jetbrains ReSharper feedback looks like:

Here’s the one currently employed by us at Lokad.

And that’s how Microsoft Office 2010 feedback looks like:

Each of these three has it’s own benefits, including but not limited to:

UI simplicity;
Level of complexity of cliend-side and server-side infrastructure behind the feature;
Support for multiple software applications within the same product line (all the way through various versions, deployment options);
Ability to offer user to provide additional data, essential for the problem resolution;
Level and quality of sensible automation behind the interaction.

There is a lot to learn from large companies for Lokad.

Infrastructure Shards and Optional Components

2009-10-21T05:56:05Z

Component-driven development really helps to deliver multiple applications and systems efficiently. It happens because:

important functionality is abstracted in components;
components are coded and unit-tested only once;
every component has multiple use cases that provide additional feedback and help to find problems or limitations, if there are any;
whenever a component is fixed or improved, all its consumers would benefit from that automatically.

As we go up in the complexity of the development, it becomes too cumbersome to manage components on the individual basis. That's where infrastructure shards come into the play.

Infrastructure Shards

Infrastructure shard is a group of components that work together to carry out some specific job in the application or system. They are joined to simplify reuse in multiple applications and contexts.

Normally all these components are developed to support Inversion of Control, but if needed they could be wired together manually. In the IoC scenario, components are fit together using registration modules (or xml configuration blocks for the legacy containers). In the rare cases, when IoC context is not available (i.e.: we need to offer minimal feedback reporting to deal with possible unhandled exceptions on startup), a simple factory method would do the job.

A single infrastructure shard could join components coming from the different libraries and application blocks.

Feedback infrastructure shard (sources), for example, would include:

Model-View-Controller elements:
- User control view to be shown in the currently available IViewspace;
- Immutable models used to pass feedback reports and information around;
- Controller responsible for managing the view and user interactions;
- Validation rules injected into the view in order to check and enforce user input.
Feedback helper components, aggregating system information to be attached to the report.

However, if we attempt to start our feedback reporting window, just with these few components, we would fail. This would happen because usually in the IoC environment an infrastructure shard is not self-sufficient. It has to interact with the other components and services as well. The view, for instance, does not even have a window to present itself in; it is merely a user control:

So in order for the shard to work, we need to provide some external services. These are really easy to spot in the code if we consistently stick to the guidelines of:

only constructor injection is used (no property injection);
every component has only a single constructor;
components can inherit only from the interfaces (except for the views that have to derive from some user control).

Given that we could find out that core feedback service components use these components:

IViewspace - responsible for displaying view properly in the UI environment available;
IReportService - responsible for establishing contact with the communication service shard (which will handle all the exception handling and reliability on its own) and sending the feedback report;
IClientInteractions - provides UI-specific methods that allow to interact with user;
Optional{ServiceConnection}.

The last item is the most interesting one here. Here's why and how it works.

Optional Components

When we show feedback report window - we want to suggest user to use his existing email address and connection information. This way the feedback could be routed to the appropriate server and associated with the user's account.

And we want to have code working in situations, when user context is not available (i.e.: user logged off or context is not even known).

That's what the Optional{ServiceConnection} does. It allows to pass some information via IoC container, while indicating that the reference could be empty at the moment of retrieval. It's declaration is extremely simple:

/// <summary> Simple delegate that returns optional result </summary>
public delegate Maybe<TResult> Optional<TResult>();

That's it. Yes, that resembles Lazy of MEF, but is a bit simpler, does not require MEF libraries and can benefit from the synergy with Maybe Monad.

For example, if we want to get current user name in one of the views (if the user name is available), the code might look like:

// somewhere in the class
readonly Optional<ServiceConnection> _contextProvider;

// somewhere in the code
var sender = _contextProvider()
  .Convert(sc => sc.Username)
  .GetValue(AnonymousUserName);

While the registration of the optional might look like:

// extension method for Autofac ContainerBuilder
public static void RegisterExport<TComponent, TExported>(
  this ContainerBuilder builder,
  Func<TComponent, Maybe<TExported>> func)
{
  builder.Register<Optional<TExported>>(c => 
    () => func(c.Resolve<TComponent>()));
}

// actual registration
builder.RegisterExport<IApplicationController, ServiceConnection>(c => 
  c.Context.Convert(ec => ec.Connection));

With this registration at hand, all trusted components that need to have access to the current connection context, can do that by requesting an instance of Optional{ServiceContext}.

This technique is really useful when defining boundaries of infrastructure shards, required and optional dependencies that they might have.

Unit Testing

We can even easily isolate the shard in unit test in order to allow manual testing of feedback reporting:

[Test, Explicit]
public void Show_synthetic_feedback()
{
  var data = RandFeedbackModels.NextTextDatas(0, 3);
  CreateService().ReportFeedback(data);
}

Where CreateService explicitly establishes all dependencies in the MockContainer and grabs the service:

IFeedbackService CreateService()
{
  Build(cb =>
  {
    // factories
    cb.Register<Func<ServiceConnection, ILokadService>>(ServiceFactory.GetConnector);
    cb.Register<Optional<ServiceConnection>>(() => Maybe<ServiceConnection>.Empty);

    // services
    cb.Register<FeedbackService>().As<IFeedbackService>();
    cb.Register<ReportService>().As<IReportService>();

    cb.Register<FeedbackSenderController>().As<IFeedbackSenderState>();
  });

  WhenViewIsShown.Do(f => f.ShowDialog());

  return Resolve<IFeedbackService>();
}

As you can see for the service connection provider we are passing a lambda expression that returns an empty connection context.

Note that we are not establishing any view-related components, since ViewFixture (this test fixture derives from it) already does this:

cb.Register<TView>().As<TView, TInterface>();
cb.Register<TestViewspace>().As<IViewspace, TestViewspace>();
cb.Register<TestInteractions>().As<IClientInteractions, TestInteractions>();
cb.Register(Specifics.Empty);
OnBuild(cb);

Result looks like this:

Filling in the information and clicking Send would create a ticket in Lokad support system. By the way, you can use this opportunity to say what you think about the company.

Shard Synergies

Here are some additional synergy effects that come from using infrastructure shards to reuse similar components between multiple applications:

Business functionality could be used to extend multiple applications. Since UI is shared, we could use shared documentation, tutorials and screenshots as well.
Sometimes context requires infrastructure shard to be evolved. This brings potential improvements in all existing and new applications.
When a group of components is developed to be used in multiple scenarios from the start, this polishes the overall design even further than TDD or CDD would alone.
Localization or UI changes across the software product line become easier, since the effort does not have to be duplicated and tested in multiple codebases.

What do you think about all that?

Notes

I understand that this looks really similar to what Microsoft Extensibility Framework does with Lazy and Export . However, my belief is that:

extensibility discovery and management framework should stay completely detached from the components;
inversion of control container should stay completely detached from the framework as well;
attribute-based declarations on the components are evil;
all component dependencies should be explicitly declared in the orchestrating code in strongly-typed manner.

This means that the core components should not use extensibility framework. Infrastructure shard boundaries might do that, while acting as a simple gateways. But that's another story.

You can subscribe to this journal to get all the updates. Voting for the next article to be written is also possible.

Efficient Development, Deployment and Customer Feedback at Lokad

2009-10-19T07:25:27Z

A while ago I wrote about deployment and updates of the desktop applications and outlined the technology we use at Lokad for rapid and efficient delivery of various updates to the customers.

Let's expand on the topic a little bit more, showing how a small company could create quite a bit of business value via some efficient development practices.

There will be a small questionnaire at the end of this article as well.

Development and Deployment Experience

Current application deployment and publication loop for Lokad Client Applications works like this: when developers commit new features or fixes to version control repository and hit a special build button on integration server, following happens automatically:

All unit tests, integration and code quality tests are executed against the latest codebase (build breaks if these fail).
New version of install package (and optional downloads) is deployed to publicly available location.
Download page is updated with the links to the new version.
Existing users of an application get a nice "Update Available!" notification in the corner of their toolbar. Clicking on it launches semi-automatic download and upgrade process.

Note, that we are not using ClickOnce technology here, since it has important limitations we couldn't live with. Everything took a bit of time to setup once and then it is just started flowing.

Customer Feedback Experience

Recently, in order to enhance customer experience, yet another simple feature had been added to the client applications: integrated feedback reporting. Simply put, customer could click a button and send a message to the company. It will immediately show up in the customer support system. Additionally, all unhandled exceptions (should they happen) could be reported, too.

Feedback reports (if customers decide to) could include following anonymous information:

system descriptor of the software (version, OS version);
versions of the assemblies loaded into the AppDomain;
latest portion of application log;
statistics of some performance counters showing client-side information about interactions with our servers (number of communication failures, retries, amount of data transferred);
exception counter statistics (information about unique exceptions handled by the application along with their counts).

Note, that sources for the SystemDescriptor, ExecutionCounter and ExceptionCounter are available in Lokad Shared Libraries. Actual feedback reporting shard is shared with the community in the Lokad SDK

Feedback system had been implemented as an infrastructure shard within the shared codebase. This implied IoC-friendly component-driven design and allowed to efficiently reuse all components in multiple applications (even in these that didn't have any IoC infrastructure around). All improvements and fixes to the shared components, in such scenario, automatically benefit all applications that use them.

Additionally, since the feedback system is implemented as an independent infrastructure shard, it can be used to trap and report possible exceptions that take place on the application startup (even before the Inversion of Control Container is setup). Later, when the application and composite UI elements are ready, we switch stand-alone feedback handler for integrated handler (that uses, application's Viewspace and action policies, for instance)

This reduced feedback friction for the customers and made issue reports a lot more useful and helpful for the development team. Since all feedback reports get routed to the internal customer support system, we could feel the change really fast and resolve problems and provide solutions more efficiently.

New Challenge - Update Flood

This kind of automatic and tight integration between development, deployment and customer support spawns new possibilities and brings forth new challenges. First of all, it definitely affects the way we think about the development and plan future changes.

Second, since it is too easy to deploy an update, we've got to start thinking about protecting customers from being flooded with a number of updates (software should solve the problems, not create new ones), since theoretically we could fire the deployment update after every single verified fix that is landed in the trunk.

Here's how one of the implementation scenarios looks like right now.

All software updates (packaged as a complete version, as usually) could be described with a:

version;
download url;
tags (Critical, RC, Test, Major etc)
optional description.

Primary download page is automatically updated with the links only when "Critical" and "Major" versions are released.

Customers are unformed about the Major updates to the installed software with a usual manner (i.e.: toolbar notification). Less-important updates are not shown to them explicitly but could be pulled (i.e.: from the menu), if customer needs that.

This scenario should work if we are facing scenario, when there is a minor fix affecting only a single customer. We could deploy an update via the normal procedure, but it does not make a lot of sense to push updates to every single customer.

Implementation should be rather straightforward:

Instead of updating simple txt on the server per every update, we could update an XML file in the RSS/Atom format with the build version, url, description and tags.
By default every application filters out all non-Primary updates, displaying the rest on the toolbar. This way we deliver important functionality to customers, while saving them from the barrage of less important builds.
Customers might explicitly look into the update stream, picking and firing the specific update they need (i.e. when informed about the fix by the customer support).
Beta testers and partners might update application settings to be notified about RC and Minor deployments
Developers and Testers might switch their filtering settings to include Beta and Minor updates.

Potential synergy effects:

Updates could be subscribed to via a mere RSS reader and mashed with a company news (automagically).
Since we are already tracking Delivery-Build labels for issues, this information could be pasted to the description dialog, providing customers and testers with more context (could be available from the application and from the web/RSS).
It is possible to push the idea even further and let customers set simple filter in their application ("inform me when ticket #X is fixed"). Then, whenever the next deployment is detected, a simple regex could scan the description for the ticket number, raising friendly alert, whenever it is mentioned there.
If we have a critical update at hand (i.e.: breaking API change or an important security vulnerability) we can block the entire app and insist on updating.

Everything might get even more interesting as extensible and composable application architectures (with extensions being developed and delivered concurrently) get into the picture, allowing fine-grained and yet automated customer-company interactions.

Summary

In this short article we've walked over some development practices adopted in Lokad. These practices help the company to resolve customer problems and provide new solutions to their business challenges.

In short the outlined practices include:

efficient software deployment and updates;
efficient customer support and feedback collection;
considering synergy effects and automation, whenever possible and feasible.

Of course, there's a lot more in efficient development, than these few practices. I'll address them eventually. You can subscribe to this journal to get all the updates. Voting for the next article to be written is also possible.

As always, all feedback to the article is welcome and appreciated. Here are also a few questions, if you are willing to share your experience with the community around this Journal:

How much time does it takes for the customer to report a problem and get an update in your development environment?
Does your company share the code with the community?
Are you a customer of Lokad? What do you think about this development approach? How could it be improved?
Are you a competitor of Lokad? What do you think? ))

Zen Development Practices: C# Maybe Monad

2009-10-05T19:25:10Z

One of the things I like about software development is a simple fact, that efficiently developed code, block or software, takes much more time to document, than to deliver.

This efficiency could be based on certain practices, constraints and principles, followed by discipline. These items allow to take away small bits of complexity and development friction, allowing us to concentrate on the things that really matter and generate business value.

Let's talk about one of this small things - a really simple construct in C# called Maybe (of the monad fame) that had completely freed me from all cases of NullReferenceException in my code, while making it cleaner.

Sounds interesting? Let's have a look at the C# code and .NET usage patterns.

Introduction

Maybe<T>, as the simplest monad implementation in .NET, is a generic class that can either hold value of type T or be empty. There is a little bit of helper syntax and some usage guidelines and patterns.

In this article we'll cover all of these; links for the sources in C# and binaries would be provided, too.

Here's how the declaration of the Maybe class starts in C#:

[Serializable, Immutable]
public sealed class Maybe<T> : IEquatable<Maybe<T>>
{
  readonly T _value;
  readonly bool _hasValue;

  Maybe(T item, bool hasValue)
  {
    _value = item;
    _hasValue = hasValue;
  }

  /// <summary> Gets the underlying value, if it is available </summary>
  /// <value>The value.</value>
  public T Value
  {
    get
    {
      if (!_hasValue)
        throw Errors.InvalidOperation(
          ResultResources.Dont_access_value_when_maybe_is_empty);

      return _value;
    }
  }

  internal Maybe(T value)
    : this(value, true)
  {
    // ReSharper disable CompareNonConstrainedGenericWithNull
    if (value == null) throw new ArgumentNullException("value");
    // ReSharper restore CompareNonConstrainedGenericWithNull
  }

  /// <summary> Gets a value indicating whether this instance 
  /// has value. </summary>
  /// <value><c>true</c> if this instance has value; otherwise, 
  /// <c>false</c>.</value>
  public bool HasValue
  {
    get { return _hasValue; }
  }

  /// <summary>
  /// Default empty instance.
  /// </summary>
  public static readonly Maybe<T> Empty = new Maybe<T>(default(T), false);

There are a few implicit operators and helpers methods that improve the usage experience (we'll talk about them later), but the simple code above is the core of the approach. Primary monad operations could be expressed in this simple snippet:

// function that MIGHT return a number
Maybe<int> DetectNumber(string number)
{
  switch (number)
  {
    case "Zero":
      // we are allowed an implicit conversion
      // so here we return a number directly
      return 0;
    case "One":
      return 1;
    case "Two":
      return 2;
    default:
      // empty singleton for missing value
      return Maybe<int>.Empty;
  }
}


// Actually getting a Monad in C#
var number = DetectNumber("Zero");

// prints "True"
Console.WriteLine(number.HasValue);
// prints "0"
Console.WriteLine(number.Value);


var number2 = DetectNumber("Hm..");
// prints "False"
Console.WriteLine(number2.HasValue);
// throws InvalidOperationException
Console.WriteLine(number2.Value);

So basically this Maybe monad is extremely simple class that can either be empty or have value. If it is empty, and we attempt to access value, then the exception is thrown. In other words, that's a strongly-typed reference to an object that acts like null with some syntactic flavor.

How is it even better than using nullable references and getting NullReferenceException when you forget to check for null?

Here are the reasons justifying the usage of Maybe{T} for me:

Reason 1: Good Citizenship

By using Maybe{T} in my code I promise that all the code will be following good citizenship principles and will keep all object references non-null (initialized to some value from the default). This promise is to be uphold by a self-discipline and unit tests.

This helps to avoid all null references completely.

Reason 2: Explicit behavior and clean code

If there is a potentially nullable reference, parameter or a function return result, then it should be explicitly marked with the Maybe{T}, exposing its behaviour to the reader and forcing him to explicitly handle the states.

Additionally, using Maybe{T} allows us to avoid throwing weird exceptions or returning nulls in situations, where result could be undefined.

Consider declaration of the method like this:

/// <summary> Parses an encoded string into
/// authentication information. </summary>
/// <param name="encodedString">Encoded string.</param>
/// <returns>authentication information</returns>
/// <exception cref="ArgumentNullException">when string is null</exception>
/// <exception cref="InvalidOperationException">when string is invalid</exception>
AuthInfo ParseStringToAuthInfo(string encodedString);

This method declaration is really similar to a lot of existing methods from the .NET BCL (i.e.: int.Parse as the simplest one) and it shares a lot of excessive noise and inherent problems. Most importantly we are throwing some exceptions, when the input is not expected and could not be handled gracefully. This:

blows the code execution and must be handled by a separate try-catch;
requires code consumer to read the documentation instead of reading the method signature;
does not prevent the code from potentially breaking in every single place, should we refactor and replace InvalidOperationException by InvalidAuthDataException.

Let's rewrite the method signature using the Maybe monad style:

/// <summary> Attempts to parse an encoded string into 
/// authentication information. </summary>
/// <param name="encodedString">Encoded string.</param>
/// <returns>authentication information</returns>
static Maybe<AuthInfo> ParseStringToAuthInfo(string encodedString)

With this refactoring we:

decoupled ourselves from the ArgumentNullException, since we believe that input will never be null. Method body would live without the appropriate null check as well;
decoupled ourselves from the InvalidOperationException and use optional value, that would be valid only if the parsing succeeded;
no longer require the developer using the method to look in the code documentation in order to understand what exactly the method works;
do not need defensive and noisy try-catch programming around the calls to this method (or anywhere in the call stack).

Of course, there are other refactoring alternatives to the signature:

// Option1 : use bool
static bool TryParseString(string encodedString, out AuthInfo);   
// Option 2: return value that could be null
static AuthInfo ParseString(string encodedString);

First option uses the TryGetValue approach you can see on the IDictionary interface. This approach resorts to the out keyword (which I always avoid), breaks the functional style of the programming (method should always have a single value being returned) and adds some noise to the using code.

Also AuthInfo is returned as undefined, if the parsing fails, violating the good citizenship.

Second option returns value that would be null in case the parsing fails. Developer, in order to discover this, has to read the documentation. And he has to protect himself from the possible problems with null checks against the result.

In my opinion, method using the Maybe monad is the most clean approach of them all.

Reason 3: Chaining and pipeline syntax

Ok, so we have our Maybe-powered method signature:

static Maybe<AuthInfo> ParseStringToAuthInfo(string encodedString);

Let's actually see the full power of the concept in C# on a sample taken fresh from the production code. Consider the method:

// simple pipeline sequence
Maybe<AuthPrincipal> LoadPrincipal(string key)
{
  return ParseStringToAuthInfo(key)
    .Combine(u => _service.BuildAccountSession(u))
    .Convert(sa => new AuthPrincipal(sa));
}

In this LINQ-style and purely functional sequence of 3 lines, we:

Attempt to parse the key into AuthInfo.
If the attempt was successful, we use some service to try to build an account session out of the parsed AuthInfo. BuildAccountSession operation might also fail, by the way. This is indicated in the method signature (by using Maybe) and would happen if the provided AuthInfo didn't have a match in the repository.
If we were successful in parsing the original string and in building the account session, then we create a new AuthPrincipal class using this session; otherwise an empty Maybe{AuthPrincipal} is returned to indicate the composite failure.

As you can see, detailed method description takes a bit more space, than the actual implementation. And the implementation itself is less fragile and smaller compared to traditional approach with nulls, throwing and handling various exceptions.

After getting used to this benefit of Maybe, dealing with the code that has exceptions and nulls feels like working in Visual Studio without ReSharper installed.

All the benefits listed above come from two classes (that contain less code, than this article) and some discipline. That's the way of Zen.

If you want to try Maybe{T}, the code is available in Lokad.Shared.dll from the Lokad Shared Libraries. You can either copy this class to your solution (while keeping an eye on the project for any improvements and changes in the guidelines) or grab the latest download.

Let's continue our article by outlining common operations available for Maybe{T}.

Creating Maybe

// implicit conversion is the most common way to create Maybe<T>
// mostly it happens when we return actual value from within a
// method that returns maybe.
// Or, when we pass value into the optional function parameter
Maybe<int> maybeInt = 10;

// creates a maybe object when implicit casting is not available 
// for some reason (i.e.: anonymous types or failing type inferrence)
var nonEmptyMaybe = Maybe.From(value);

// each type has only a single empty maybe instance that is
// cached via the type-caching
var emptyAuthInfo = Maybe<AuthInfo>.Empty;

Getting Value

// tests if the Maybe has value
var hasValue = maybeInt.HasValue;

// returns value behind the Maybe, throwing exception if it is empty
// this approach is rarely used (because of the pipeline operators)
var value = maybeInt.Value

// get's value from maybe, using some default, if it is empty
var value = maybeUsername.GetValue("guest@abdullin.com");

// get's value from maybe, executing default generation if it is empty
// handy for scenarios, when generating default values is CPU expensive
var value = maybeUsername.GetValue(() => ComposeName());

Pipeline Operations

// get Maybe that either has value derived from the parent Maybe
// or is empty, if the parent is empty
var maybeUsername = maybeIdentity.Convert(i => i.Username);

// gets actual value that is derived from the parent Maybe, if it is not
// empty, or uses a predefined default 
// equivalent of Convert.GetValue
var username = maybeIdentity.Convert(i => i.Username,"guest@abdullin.com");
var username = maybeIdentity.Convert(i => i.Username,() => ComposeName());

// combines result of the two Maybe's, either of which could be empty
var maybeFullName = maybeUsername.Combine(k => LookupFullName(k));

// executes the action against the value, if Maybe is not empty,
// returns the original Maybe to continue pipelining 
maybeFullName.Apply(fn => Console.WriteLine(fn))

// executes the action, if maybe is Empty
// returns the original Maybe to continue pipelining
maybeFullName.Handle(() => Application.Terminate());

In addition to the operators above, Maybe{T} class also defines proper equality and hashing operations. It is debugger-friendly, too.

However, this does not end the list of reasons of using Maybe for the efficient development.

Reason 4: Simplified unit testing

Using Maybe monad in .NET also has the benefit of allowing to introduce simplified DSL syntax for unit-testing code leveraging the approach.

Here are the core extensions you need (they are pipelined together for the brevity)

// extensions checking different aspects of valid Maybe<T> monad
maybeValue
  .ShouldPass()
  .ShouldPassCheck(i => i == 10)
  .ShouldPassWith(10)
  .ShouldBe(10)
  .ShouldBe(true);

// checking empty Maybe Moned
MaybeNot
  .ShouldFail()
  .ShouldBe(false);

Each extension, basically throws a descriptive assertion exception, if the condition is not met.

Here's how the unit test might look like with one of these extensions:

[Test]
public void System_info_is_disabled()
{
  WhenViewIsShown.SetResult(DialogResult.OK);
  Subject.BindModel(RandClientModels.NextFeedbackView());
  Implementation.CheckSystemInfo(false);
  Subject
    .GetModel()
    .ShouldPassCheck(m => m.SystemInformation == "");
}

If the check fails, because the maybe has a value but this value is invalid, then the failure would look like:

FailedAssertException: Expression should be true: '(m.SystemInformation = "")'.

These test extensions are located within Lokad.Testing.dll, which is also a part of Lokad Shared Libraries within a Lokad.Testing namespace.

This separation is done in order to prevent IntelliSense from being polluted with all the Should statements, while we are working in the production code. Testing code, on the contrary can have access to these routines (which is done by referencing the testing assembly and using the namespace).

Reason 5: Initialization of Immutable classes

All we know that in F# it is extremely easy to create an immutable object from another record by providing a few override values in the cloning process:

let conn2 = { conn1 with Service = MyService }

If we are using only C#-style immutable classes as models in our application (which is beneficial for a number of reasons, but is a large topic on its own), then we are limited to the constructor initialization only, which could be rather messy:

// model definition
[Immutable, Serializable]
public sealed class ServiceConnection
{
  public readonly string Username;
  public readonly string Password;
  public readonly string AuthMode;
  public readonly Uri Service;

  public ServiceConnection(string username, string password, 
    string authMode, Uri service)
  {
    Username = username;
    Password = password;
    AuthMode = authMode;
    Service = service;
  }
}

// cloning with a custom service reference
var conn2 = new ServiceConnection(conn1.Username, conn2.Password, 
  conn2.AuthMode, MyService);

More fields the model has, more messy cloning the process becomes. Fortunately, in the upcoming C# 4.0 we will be able to do everything more efficiently and with different combinations:

var conn2 = conn1.With(service: MyService);
var conn3 = conn1.With(username: Anonymous, AuthType: Plain);

This could be achieved with a single method by using C# 4.0 Optional Parameters and Maybe{T}:

  public ServiceConnection With(
    string username = Maybe.String,
    string password = Maybe.String,
    string authType = Maybe.String,
    Uri service = Maybe.Uri)
  {
    return new ServiceConnection(
      username.GetValue(Username), 
      password.GetValue(Password),
      authType.GetValue(AuthType),
      service.GetValue(Service);
  }

where Maybe.String (and its Uri analogue) is just a short-cut for Maybe{string}.Empty that is already declared on the Maybe non-generic helper class in Lokad.Shared.dll.

Caveats

This approach, as any other piece of knowledge from the xLim body of knowledge, might be controversial and not applicable for you projects, development practices and beliefs.

All that I can say - it works for me, allowing slightly more efficient delivery, evolution and maintenance of .NET development projects ranging from business analytics servers, RESTful NoSql automation engines and up to Smart Client applications with reusable MVC infrastructure shards.

This limited improvement in development efficiency sometimes requires using approaches and principles that may be somewhat incompatible with the traditional ones (MS .NET or Alt.NET), while continuously enforcing them across the codebases. But in the end, I think, it's worth it, just like Continuous Integration or Inversion of Control.

But again, that's the way of Zen - everybody has his own way to satori.

Questions and Answers

Question: Why add another needless layer of complexity for such a simple task? Just learn how to use the null coalescing operator (??) and/or inline if-thens.

Console.WriteLine(number != null ? "True" : "False");
Console.WriteLine(number ?? "Null Value");

Imagine a large real-world project that spawns multiple components and tiers, while facing problems slightly more challenging, than writing output to the console. If developers know that this project uses Maybe to declare potentially empty variables, then they are completely freed from checking for nulls and even thinking about that. That's one less thing to bother, making quite a difference in complex scenarios (and human being can simultaneously bother only about 7 things max, anyway).

This actual usage of Maybe{T} might happen in just one or two methods of the project. However, when developers use them, they will know immediately (and not from the documentation) and will be forced to handle them because of the syntax.

Things like that reduce development friction and allow complex project to be delivered efficiently and with really small teams.

Question: How is this different from Nullable{T} in C#?

Only value types are supported by Nullable generic (or its shorthand syntax). So you can't use a class variable in a nullable type (which makes sense, since the reference itself can be null).

Question: Why do Lokad Shared Libraries feature null checks, although Maybe{T} is declared in the code?

Because Lokad.Shared.dll, as a really lightweight library, might be used in various projects. Some of these projects might not have "no nulls returned and expected" policy. So it is logical to protect shared methods from the nulls explicitly. in order to avoid the unpredictable behavior.

Question: How do I use Maybe{T} if method can fail because of the multiple reasons and I want to know them?

Maybe{T} on its own is not designed to handle such situations. These are the primary logically-complete solutions for this situation:

You can return Maybe{T} while printing multiple failure details to the IScope passed as an argument. That's how Lokad Rules are working. It also works well in long-running complex (especially asynchronous) operations that require logging and detailed failure control.
You can use Result{TValue,TError} monad returning strongly-typed error result (i.e.: enumeration value) or it's generic counterpart Result{TValue} (if the strong-typing is not possible for some reason).
You can always use good old exceptions, if the above options do not suite you for some reason and you are OK with try-cath and breaking the functional code flow.

Question: Does Maybe work with validation rules?

Yes, Maybe{T} works with Lokad validation and business rules. You can also use MaybeIs helper class to compose strongly-typed rules on top of the Maybe{T} monad. MaybeIs has two static methods:

MaybeIs.EmptyOr{T}(params Rule{T}[] rules) - composes validation rule that succeeds only if the Maybe{T} is empty or the underlying value passes additional rules.
MaybeIs.ValidAnd{T}(params Rule{T}[] rules) - composes validation rule that succeeds if the Maybe{T} is not empty and the underlying value passes additional rules.

Sample usage in composing more complex rule:

public static void ModelIsValid(FeedbackModel model, IScope scope)
{
  scope.Validate(() => model.Sender, 
    MaybeIs.EmptyOr<string>(StringIs.ValidEmail));

  scope.Validate(() => model.Model, ModelIsValid);
}

Question: So essentially you are replacing "optional != null" with "optional.HasValue".

Not exactly. HasValue is rarely checked against directly. Take a look at the piece of authentication code below. There are two possibly failing functions in it, that return Maybe{T}:

Maybe<AuthPrincipal> LoadPrincipal(string key)
{
  return ParseStringToAuthInfo(key)
    .Combine(u => _service.BuildAccountSession(u))
    .Convert(sa => new AuthPrincipal(sa));
}

Signatures are like:

static Maybe<AuthInfo> ParseStringToAuthInfo(string encodedString);
Maybe<AccountSession> BuildAccountSession(AuthInfo authInformation);

HasValue and Value aren't mentioned in this code. That's how it usually works.

Question: What about operator overloading:

public static implicit operator T(Maybe<T> mayBe)
{
  return mayBe.Value; //or mayBe._value;
}

public static implicit operator bool(Maybe<T> mayBe)
{
  return mayBe.HasValue;
}

This kind of implicit conversion from Maybe directly to value/state is not advised for two reasons:

It looses the intent of using Maybe{T} to force explicit handling of nullable situations.
Implicit conversion from Maybe to value is logically incorrect as it might return default(T) value or result in exception (depending on implementation).

Basically such an implicit operation would feel somewhat similar to the old C++ joke from bash.org:

#define TRUE false
#define FALSE true
// and good luck with debugging))

Side note: Implicit conversion from value to Maybe{T} or from error/value to Result{TValue,TError}, as opposed to the case above, does not violate this logic. This is because we are not forcing collapse of possibility of multiple states into one known state (while have side effects if the state is not what we expect).

This is why conversion from value to maybe is implicit, while the opposite has to be done either via the Value property or via the explicit conversion.

Summary

Let's wrap the things up.

In this article we've talked about Maybe{T} generic class that, as a simple monad concept, allows in .NET to:

promote Good citizenship in the code avoiding nulls and exceptions;
write clean code with explicit behavior;
use expressive LINQ-style syntax with chaining and pipeline operators;
benefit from the simplified unit testing syntax;
initialize immutable classes efficiently in C# 4.0.

C# source files and compiled binaries featuring Maybe monad and testing extensions could be downloaded from the Lokad Shared Libraries Open Source project.

It is important to note, that the current design of Maybe{T} and development practices around it are based on the ongoing R&D process and production usage cases. As such, they might gradually evolve and improve further (this being reflected in Lokad Shared Libraries).

This article is also considered to be an essential part of xLim 3 development body of knowledge.

If you are interested in more articles on Zen Development practices, you can stay tuned by subscribing to this blog via RSS.

Next article I'm considering for these series is about Result variations of the monads in C#, that allow handling more complex failure scenarios, than a simple Maybe (BTW, the previous Zen article was about Method-level IoC).

All comments, thoughts and any other feedback are welcome and appreciated.

Zen Development Practices: Method-level IoC

2009-07-31T08:58:12Z

One of the things I really like about the software development is a simple fact that having the right idea, tool or even just a proper state of mind could help you to avoid writing a lot of unnecessary code. As we all know, unnecessary code results in extra development friction and increased maintenance burden which come down to a higher TOC. This could scale from a few methods and up to the classes, micro-frameworks and even sub-systems.

All that matters in the end, is about the delivery of the unique business value within the budget, quality and time constraints.

In this article I'll try to give you a brief overview overview of a few concepts (and a synergy between them) that have worked for me like this before. Most interesting of them I would refer to as a Method-level Inversion of Control.

Let's have a closer look at a really short extension method that simplifies Autofac usage for me in some specific scenarios:

public static void Build(
  [NotNull] this IContainer container,
  [NotNull] Action<ContainerBuilder> registration)
{
  if (container == null) throw new ArgumentNullException("container");
  if (registration == null) throw new ArgumentNullException("registration");

  var builder = new ContainerBuilder();
  registration(builder);
  builder.Build(container);
}

As you can see, there are just a few lines of code here. Yet the amount of ideas and concepts related to them is slightly more diverse. Let's start walking over them.

Basically this extension simplifies some in-line registrations for the existing container. You might need them from time to time, when defining some environment-based registrations, using MockContainer for unit testing or simply starting a new prototype project.

Here's how the code looks with and without this extension method:

// old style registration
var builder = new ContainerBuilder();
builder.Register<MyComponent>().As<IMyService>();
builder.Build(container);

// Equivalent registration with the extension method
container.Build(b => b.Register<MyComponent>().As<IMyService>());

Obviously, you could have multiple registrations and anything else that could be done with a ContainerBuilder.

By the way, this simple extension method is currently in the Lokad.Stack.dll. If anybody actually wants to see it in Autofac.dll, just drop a comment and I'll push it up to the Autofac codebase.

The statement above might seem to be an overkill for "just a mere extension method", yet it highlights (once more) an extremely important rule of thumb that has helped me to develop and keep stable a few shared libraries so far. Here it is:

You should never put some helper class or method into the shared codebase, just because it looks cool or useful. It should stay in the original solution where it is used until two or more external solutions show distinct need to reuse it and it is obvious that this code could be reused efficiently (sometimes it is better not to reuse). Only then, we'll move that reusable code upstream (into the common shared project), while making sure that it fits perfectly all the use-cases.

By the way, it is a good practice to have an automated continuous integration project (or a couple of them) that regularly pulls together all the different solutions used in some projects (this includes 3rd party libraries available as open source), compiles them all and then runs tests. This kind of validation helps to detect possible dormant issues (i.e.: breaking API changes) as soon as possible, simplifying their resolution.

What are these NotNull attributes? These are simple code hints for the ReSharper that are declared in Lokad.Quality.dll. They indicate that the method does not expect null values and explicitly enforces this principle of good citizenship by throwing ArgumentNullException. ReSharper will keep this in mind, while performing solution-wide analysis and highlighting warnings and suggestions (I think that's a decent benefit for just a few short attributes).

Let's get back to the idea behind that extension method for Autofac IoC Container. You could consider it to be an example of method-level Inversion of Control. This pattern is really useful, when we want to capture or perform some operations against the underlying object, while enforcing some context and keeping the complex logic - clear of some implementation details.

In the case of the Autofac builder extension we were capturing the component registrations, while enforcing their binding to the current IContainer in the end (that's yet another solution to the builder syntax problem, by the way).

Here is another usage of this pattern, coming from a different domain - my sandbox prototype for working with CouchDB. Check out the snippet bellow, paying attention to the lambda expressions with the stream parameter:

public DocumentInfo SaveDocument<T>(T item, Func<T, Guid> id)
{
  using (var r = _server.Do(id(item).ToString(), "PUT",
    stream => Serializer.Serialize(stream, item)))
  {
    FailsUnless(r, CouchStatus.Code201);

    return r.ReadObject(stream =>
      Serializer.Deserialize<DocumentInfo>(stream));
  }
}

This snippet simply implements a wrapper for the RESTful document management API of CouchDB.

As you can see, there are two places, where we need to access request and response streams. Yet, there is no explicit stream management and disposal. That's because we've implemented this logic already in the code that is actually responsible for that. This results in more compact and reliable code that frees the developer from remembering about stream management and other technical details that are not important at this layer. We also know that all the required extensibility points are already considered and enforced in the design (see previous CouchDB article for details).

Given that, implementing some sort of wrapper for a specific RESTful API becomes more peaceful and enjoyable experience. That's the way of Zen.

As you can guess, this pattern could be applied to other resource-management scenarios or situations as well.

Another usage scenario of this pattern involved developing scheduling logic for a piece of concurrent data processing engine. We wanted to write and run complex queries against the complex domain model which was updated by a few asynchronous processes. Sometimes we even wanted to modify this model from within the query. Another obvious requirement was: query code (already complex) had to be atomic and without any code for managing transactions. All this resulted in a simple interfaces like the ones below (I'm extremely oversimplifying the domain, while keeping the primary idea):

interface IQueryableDomainModel
{
  void RunQuery(Action<IQueryTarget> query);
}

interface IQueryTarget
{
  int NumberOfTasks { get; }
  int ScheduleSize { get; }
  Task[] GetTasks(int count);
  void EnqueueTasks(IEnumerable<Task> tasks);
}

while the query was able to be declared in a manner:

static class SchedulingQueries
{
  void OptimisticScheduling(IQueryTarget target)
  {
    var tasks = target.GetTasks(target.NumberOfTasks);
    if (tasks.Length > 0)
    {
      target.EnqueueTasks(tasks);
    }
  }

  void SchedulingApproach2(IQueryTarget target)
  {
     if (target.ScheduleSize < 10)
     {
       OptimisticScheduling(target);
       return;
     }
     HistoricalScheduling(target); 
  }
}

In order to execute the query you just had to use the code like the one below:

IQueryableDomainModel model = ...
model.RunQuery(OptimisticScheduling.SchedulingApproach2);

IQueryableDomainModel model implementation takes the responsibility of ensuring concurrency by calling locks before executing the captured lambda argument and then releasing them after (similar to how we created ContainerBuilder before running lambda against it and then applied it to the container after).

If we were in need for some serious performance optimization, we could even start by inspecting the captured query statement and using fine-tuned locking scenarios (without even changing a single line in the original query).

You may have already noticed that method-level IoC basically allows to create micro DSL in C#. That's precisely how this pattern has worked out in Lokad.Rules (yet another sample of the pattern), where each business rule is some compact code running against the IScope interface. Core logic is encapsulated in the rules, but it is the IScope (and the implementatios) that is to control the context and determine what to do with the rules.

This results in rules that could be expressed and combined in a code like:

/// <summary>
/// User name should have length within 6 and 256 characters 
/// and should be a valid email.
/// </summary>
internal static readonly Rule<string>[] UserName = new[]
  {
    StringIs.Limited(6, 256),
    StringIs.ValidEmail
  };

You can check out Lokad.Rules for more details, if interested. One thing worth of mentioning (if you decide to dive into the source code) is that the entire framework for business rules and validation is really small. We do not have anything classes like IntGreaterThanValidator or CompositeValidator simply because they are not really needed for this scenario.

Well, this turned out to be quite some text about an extremely simple extension method. Yet, hopefully, the journal post hints that software development is not about coding or size of the codebase. It is about the ideas and concepts that help to leverage the technology in order to achieve some business goals. If used efficiently, they can result in a small codebase. There could even be no code at all (but that's a pure Zen).

I know a few other interesting development concepts that are not so popular for some reason and yet helped a lot in complex projects by reducing the codebase, while making everything more simple and flexible. Eventually they might crystallize into more articles (like this one) with patterns, practices and theory. Although this is not going to happen any time soon, you might subscribe to this journal to get the updates.

Meanwhile, I'd love to hear your thoughts and feedback on this article.

Lokad Shared Libraries 1.5 and Autofac for Silverlight 3.0

2009-07-17T13:16:58Z

Just a few announcements.

Lokad Shared Libraries 1.5 Release

There have not been any major changes since the last official release. Some highlights include:

Various tweaks and fixes coming from projects actively using Lokad Shared in production
MockContainer implementation to simplify testing in component-driven development scenarios such as MVC (described here and here)
WaitFor construct for executing fragile code with timeout options.

Download options include:

Merged libraries as they are used in projects of Lokad.com.
Separate assemblies for people that want to use only some bits.

Autofac 1.4 for Silverlight 3.0

Autofac IoC Container for .NET is now checked for compatibility with Silverlight 3.0 in a continuous integration manner. Version 1.4 compiled for Silverlight 3.0 runtime is available within the download page.

People interested in checking out how the same code-base could be used to target various .NET runtime versions are welcome to check out the latest source code for the container.

Testing MVC Elements and Interactions with Mock Container

2009-06-24T21:38:38Z

Lokad Shared Libraries project includes implementation of the MockContainer that significantly simplifies testing of Model-View-Controller elements in separation. It does this by automatically generating and injecting mock objects, should the tested class ask for them in its constructor.

These mock objects are persisted in the local container instance as singleton, so that additional expectations could be recorded against them. Expectations are verified when the container is disposed.

There is a little overhead of creating and disposing container and instances every test, since we are using Autofac IoC Container internally here, which has a really good performance.

Interface and internals of this MockContainer have been polished heavily since its introduction a few months ago. This (with the help from a base fixture class providing a nice syntax) has allowed to write tests like this one:

[Test]
public void Display()
{
  View.SetTitle("Some title");

  // we expect the view to ask IViewspace to display itself
  WhenViewIsShown
     // you always set Form.CancelButton  for user's pleasure
    .CancelButtonShouldBeSet()
     // assert that title as as expected
    .TitleShouldBe("Some title");

    // create 0 to 20 random models and display them in view
    View.BindModel(RandClientModels.NextEvents(0, 20));
}

This is an actual unit test against actual Windows.Forms.UserControl component. It does what it says. Ability to write unit tests like this brings following benefits for free:

In this unit test all calls are executed against the interface. So should we need add Silverlight or WPF view implementations to our library, we would already have tests for the first step of Test Driven Development.
Ability to write simple unit tests really pays off in scenarios, where a single component is reused in multiple projects. Finding a bug in one of these projects, expressing it in a unit test and fixing, immediately makes all projects downstream more stable.
Using randomly-generated Models allows to cover a wider range of the possible failure scenarios. Should some case go wrong, we'll be able to reproduce it by checking out rand seed used in the integration run (Nondeterministic reproducible testing will be the subject of another article).

Here's another type of unit test. It could be invoked explicitly just to see how our view looks alone (without launching an entire application and clicking our way to this View):

[Test, Explicit]
public void Show_view_for_debugging()
{
  // when view asks to show itself, actually display it
  WhenViewIsShown.ShowAsDialog();
  // load random values and display
  View.BindModel(RandClientModels.NextEvent());
  // display view, while using ValidEvent rule 
  // to validate all input
  View.GetModel(EditEventController.ValidEvent);
}

ExplicitAttribute in NUnit tells us that unit test is excluded from the usual unit testing run and has to be launched manually.

This kind of debugging unit test for the reusable View components speeds up all the testing and UI tweaking process. Do you need to check out how View validates data, scales or displays that recent UI tweak? This is just one click away:

Sometimes we may want to go deeper and check out how various components integrate together. This is not a normal unit test (in the sense of Unit Testing), so it is marked with ExplicitAttribute as well.

[Test, Explicit]
public void Test_for_debugging_with_controller()
{
  // view is registered by test fixture
  WhenViewIsShown.ShowAsDialog();

  // simplified syntax for registering additional components
  // that we don't want to be replaced with mock objects.
  Container.Build(builder =>
  {
    builder.Register<ConnectionEditController>();
    builder.Register<WorkScopeView>().As<IWorkScopeView>();
  });

  // resolving controller and launching it with a random connection
  var controller = Container.Resolve<ConnectionEditController>();
  controller.Startup();
  controller.Edit(RandApiModels.NextServiceConnection());
}

Although code like this does not participate in the Continuous Integration process, having it around speeds up the development and simplifies debugging, should something go wrong.

This specific test creates UI elements like this:

Unit tests samples come from open source project Lokad SDK that allows developers to introduce forecasting capabilities of Lokad.com into their applications.

Testing MVC Controllers with Mock Container

2009-04-11T14:57:03Z

While developing components and services for the IoC environment, we end up with highly-specialized classes (which is good) that tend to consume a number of other lower-level classes, abstracted behind interfaces.

While this increases flexibility and stability of the system, testing could become slightly more complicated.

Let us consider following .NET controller class (of the Model-View-Controller pattern):

[UsedImplicitly]
[Guidelines.Controller]
public sealed class ExcelTaskEditController
{
  public ExcelTaskEditController(IExcelTaskEditView view,
                                 IExcelWorkbook workbook)
  {
    Enforce.Arguments(() => view, () => workbook);

    _view = view;
    _workbook = workbook;
  }

  public void Startup()
  {
    _view.EditRange += (range, message, action) =>
      _workbook.GetRange(range, message).Apply(action);
  }

  public Result<ExcelTask> Edit(Maybe<ExcelTask> request)
  {
    // Logic of binding Model to View is skipped here
    // for brevity
    return _view.GetModel(ExcelTaskIs.Valid);
  }
}

If you're interested in the logic behind view.GetModel - check out the article on DDD and Rule-driven UI Validation in MVC.

Participation of this controller in the system composition is limited to a single line:

builder.RegisterEditor<ExcelTaskEditController, ExcelTask>(
  c => c.Startup(), c => c.Edit);

In this line we simply tell the Autofac: "When some view requests a capability to present user with UI to edit/create ExcelTask, pass it an edit delegate of the pre-configured controller". This does resemble MEF slightly.

That's nice so far, but how do we unit test the actual controller? Here are some options:

manually create mock classes for the View and Workbook interfaces it consumes and pass them to the constructor;
be smart and use some mocking library to create each of these mocks/stubs for us.

However, there is an easier approach:

Wire IoC Container of our choice directly to mocking library of our choice and let them create mocks whenever needed by dependency injection.

With this approach unit test to check editing of a task could look like this:

[Test]
public void Editing_task()
{
  // action to test
  var result = Controller.Edit(Sample.ValidTask);
  // when task is edited, we should
  // bind it to a view
  // hide "Delete" button
  _container
    .AssertWasCalled<IExcelTaskEditView>(v => v.BindModel(Sample.ValidTask))
    .AssertWasCalled<IExcelTaskEditView>(v => v.SetDeleteVisible(true));
  // expected result
  Assert.AreEqual("my result", result.ErrorMessage);
}

And the setup code for the NUnit test fixture looks like this in C#:

[TestFixture]
public sealed class ExcelTaskEditControllerTests
{
  MockContainer<ExcelTaskEditController> _container;

  ExcelTaskEditController Controller
  {
    get { return _container.Subject; }
  }

  [SetUp]
  public void Setup()
  {
    // create new container, subject is registered automatically
    _container = MockContainer.For<ExcelTaskEditController>();
    // initialize the controller
    Controller.Startup();
    // tell mocking library:
    // when there is a specific call to a view interface, 
    // return predefined result
    _container
      .Resolve<IExcelTaskEditView>()
      .Stub(v => v.GetModel(ExcelTaskIs.Valid))
      .Return(Result<ExcelTask>.Error("my result"));
  }

Implementation of MockContainer class is rather straightforward in .NET. All it does is:

whenever an unknown service/component is requested - create a new stub for it with Rhino.Mocks library and register in the container as Singleton;
provide a few shortcuts for frequently used mocking/assertion methods.

MockContainer class could be found in Lokad.Testing.dll assembly that has been introduced to the Lokad Shared Libraries. This new assembly includes:

Rhino.Mocks.dll merged in for mocking purposes;
Mocking Container implementation on top of Autofac IoC and Rhino Mocks.

Lokad.Testing.dll depends on Lokad.Shared.dll and Lokad.Stack.dll.

You can check out the project page for more details or simply download the latest binaries.

MVC Controllers from this example are a specific case of using Component-Driven Development approach, that helps to build reliable software efficiently.

There is also another article on this topic: Testing MVC Elements and Interactions with Mock Container that you might like.

Some OSS News on Lokad and Autofac

2009-03-10T06:43:46Z

Last weeks have been quite intense. So here are just some news and links.

Lokad Shared Libraries

SVN for repository for Lokad Shared Libraries has been moved away from the Source Forge and into the Google Projects. That's where all documentation would eventually be migrated.

Version of the library has been updated to 1.2 and there was a major release (available for download at Google). Among other things it includes following changes:

Rule messages have been cleaned up and moved into the resources. Thus, they are localizable now.
Rule scopes have been got new extensions Lower() and Raise(). They create new child scopes (with the same path) that lower or boost the importance of rule messages being passed. This is useful for situations, when you want to reuse your existing rules in a slightly different context.
There are some more predefined rules.
Added a number of missing method overloads for composing and enforcing rules.
Scope.Validate (which uses fast IL reflection) now also works on fields. This is for DDD/MVC scenarios where models are implemented as immutable classes.
ILMerge process has been added to the integration. So Lokad.Stack.dll (in its current setup) now includes Autofac.dll and log4net.dll.
Licenses for all 3rd party libraries are included in the ReadMe.txt, JIC.
Library includes ReSharper 4.5 attributes for the code analysis (used in solution-wide analysis).
More tests and a number of fixes.

Autofac

Autofac.Contrib is being merged with the Autofac (projects and solutions are still separate). This should simplify development of contributions (and has already simplified the integration process).
Integration scripts (MSBuild now) and the solution structure have been upgraded to the latest version of the xLim template.
Discussion groups of Autofac have picked up quite a momentum recently. There are a few really interesting topics out there. If everything goes as it is, we might eventually see this kind of command-line:
```
msbuild Autofac.stack  /P:Include="mef,startable,nhibernate,log4net,rules"
```
The implementation sounds like an interesting challenge, but it should not be that hard with Mono.Cecil, ILMerge and some well-laid solution structures.

Lokad SDK

This new project might might be interesting, if you:

are interested in a different and efficient approach on building composite desktop applications with Autofac and Lokad Shared Libraries;
want to learn about shared codebases, where MVC elements are reused in different application hosts;
are potentially interested in integrating some business intelligence services (proprietary but smart, friendly and revenue sharing) in your projects;
agree that SmartClient and CAB are too heavy and Autofac is better than Unity.

Lokad SDK has been established at Google Code projects (moving away from SourceForge). It already includes an Add-in for Excel in beta stage and a foundation for composite UI library on top of Lokad Shared Libraries.

Among the features it currently contains:

functional-style MVC used for UI composition (models are immutable for the simplicity and better async in UI);
UI-level validation with Lokad Rules;
good citizenship code (supported by Result{T} and Maybe{T} classes);
ClickOnce VSTO deployment in the build scripts (same xLim template);
code quality checks (on top of Lokad.Quality) for enforcing design-level decisions (i.e. MVC models must be immutable or controller classes must have only 1 constructor);
Autofac wiring in an add-in hosted in Excel 2007.

What do you think about all this?

Logging with Lokad Shared Libraries for .NET

2009-03-03T18:38:41Z

Let's get back to the topic of using Lokad Shared Libraries and Autofac .NET IoC Container to structure and configure your applications.

In the first article we've talked about Structuring .NET Applications with Autofac. There was a stub for sample Module class for strongly-typed configuration.

Let's go on to explore the contents of the Module.Configure method that performs the actual work. We'll focus on logging in this article.

public sealed class Module : IModule
{
  public string ConnectionOptions { get; set; }
  public bool UseMockDataLayer { get; set; }
  public Mode Mode { get; set; }

  public Module()
  {
    Mode = Mode.Release;
  }

  public void Configure(IContainer container)
  {
    // if module is reused in Windows Azure:
    // if (RoleManager.IsRoleManagerRunning)
    //   ApplyOverridesFromRuntime();    

    var builder = new ContainerBuilder();

    // configure logging
    var logger = GetLoggerForWindows(Mode);
    builder.Register(logger);
    builder.Register(logger.Get("DefaultLog"));

    // configure exception capturing
    builder.Register(exceptionCounter);
    var exceptionCounter = ExceptionCounters.Default;   

    RegisterPolicy(builder);
    RegisterDal(builder);
    RegisterRuleBehavior(builder);
  }
  // more
}

As you can see, the first step is about configuring logging and making it available for any component resolved through the Autofac IoC.

GetLoggerForWindows method (we'll look into the implementation later) returns an instance of generic interface INamedProvider{ILog}. This interface essentially allows us to get a named logger (name of a logger is a category that could be used to filter messages later on):

INamedProvider<ILog> logger = ...;
ILog namedLog = logger.Get("DAL Log");

Both ILog and INamedProvider{T} interfaces are defined in the Lokad.Shared.dll and, thus, are not bound to any logging framework. Any component, that is resolved via the IoC Container, could get an instance of either of these to do its logging chores.

Here's how the ILog interface is defined in C#:

public interface ILog
{
  void Log(LogLevel level, object message);
  void Log(LogLevel level, Exception ex, object message);
  bool IsEnabled(LogLevel level);
}

As you can see, it is extremely easy to write your own implementation of this interface. Here's, actually, how the implementation of DebugLog could look like in C#:

public void Log(LogLevel level, object message)
{
  Debug.WriteLine(message, level.ToString());
}

public void Log(LogLevel level, Exception ex, object message)
{
  Debug.WriteLine(message, level.ToString());
  Debug.WriteLine(ex, level.ToString());
}

public bool IsEnabled(LogLevel level)
{
  return true;
}

And any such implementation will (thanks to the extension methods defined in Lokad.Shared.dll) provide out-of-the box rich functionality like:

log.Debug("Message");
log.Debug(ex, "Message with exception");
log.DebugFormat("Message #{0}", id);
log.DebugFormat(ex, "Message #{0}", id);

if (log.IsDebugEnabled())
{
    // some extensive logging
}

These helper methods are defined for following logging levels:

Debug - message is intended for debugging;
Warn - informatory message;
Info - the message is about potential problem in the system;
Error - some error has occurred;
Fatal - message is associated with the critical problem.

Additionally, Lokad.Shared.dll provides simple implementations of these simple loggers (in System.Diagnostics namespace):

TraceLog - prints messages to the Trace.Listeners.
DebugLog - prints messages to the Debug.Listeners.
NullLog - does not do anything.

Obviously, a production system would need more diverse logging capabilities, than these three interfaces. That's why Logging.Stack.dll allows to seamlessly plug powerful Apache log4net logging library into these interfaces.

Note, that this plugging will happen only in the configuration sections. So your business code would stay completely detached from the logging implementation details.

Apache log4net, is quite powerful, but configuring it could be quite complex. That's why Lokad.Stack.dll also provides a simplified fluent API to hide the complexity of configuring common usage scenarios.

Given all these details, here's finally how our GetLoggerForWindows implementation might look like:

static INamedProvider<ILog> GetLoggerForWindows(Mode mode)
{
  // configuring different logging based on our mode
  switch (mode)
  {
    case Mode.Release:
      // write all informational and higher events to
      // windows event log
      LoggingStack.UseEventLog(EventLogName, EventLogSource)
        .Filter(LogLevel.Info, LogLevel.Max);

      // dump all warning and higher messages to rolling text log
      LoggingStack.UseRollingLog("logs/errorlog.txt", 100.Kb(), 10)
        .Filter(LogLevel.Warn, LogLevel.Fatal);
      break;
    case Mode.Diagnostics:
      // dump all messages to daily log
      LoggingStack.UseDailyLog("logs/log.txt");
      break;
    case Mode.Debug:
      // Visual studio would get these messages
      return TraceLog.Provider;
    default:
      throw new ArgumentOutOfRangeException("mode");
  }
  return LoggingStack.GetLogProvider();
}

In the sample above we configure our logging infrastructure to write to (based on the configuration):

Windows Event log
Rolling textual log
Daily log
Trace

If that's not enough for you, you can load raw log4net settings from your config:

LoggingStack.UseConfig();
return LoggingStack.GetLogProvider();

By the way, thanks to the power of ILMerge and for your convenience, Lokad.Stack.dll already contains a version of log4net.dll inside. So you don't have to bother about getting it (neither you have to bother about looking for its open-source license for redistribution purposes, since it is already included in common ReadMe.txt distributed with the libraries).

Latest Autofac is packaged in there also.

That's it for the second article about configuring logging in your .NET applications that use Lokad Shared Libraries.

In the third article in the series we'll talk about configuring lightweight exception and performance counters to capture essential execution information about our application.

Meanwhile you can:

stay tuned to RSS feed for the updates;
explore Lokad Shared Libraries;
Share you thoughts about the logging integration capabilities provided by the libraries. Are they simple and powerful enough for you to use them (or pieces of the code) in your projects?