Rx: Bing Translate Example

In his Rx session at PDC09 Eric Meijer gave a nice example named Bing Translate. It was connecting to Bing via the Bing Web Service API and translated some term given by the user. It was quite interesting because Eric used the Reactive Framework for handling the translation and did some composition of the incoming results. He took just the first 2 translations and discarded the others. This didn’t make much sense, but it was ok for demonstration purposes. As followup Somasegar described the example in his blog.

But there was a lack of the whole sourcecode (btw: Eric Meijer posted it now on the Rx forum, but not as VS solution) and so I implemented it on my own with some modifications and now I want to share the whole Visual Studio solution with you.

Live demo

I’ve put my Bing Translate example as SL3 application on Windows Azure at http://bingtranslate.cloudapp.net, where you can directly test it:

Rx Bing Translate Example - Reactive Extensions - Reactive Framework

Sourcecode requirements

Since the Bing Translate example uses the Bing Web Service API, you need to get a free AppId here. Additional information on the Bing API can be found on the Bing Developer Center. When you’ve obtained your AppId, insert it into the BingService.cs file (field AppId of class BingService) of the sourcecode below. Now you should be able to run the solution.

What you furthermore need to open and run the solution:

  • Visual Studio 2008
  • Silverlight 3 SDK
  • Reactive Extensions for SL3 (latest release)

Now give me the code!

Ok, you want it, you get it 😉

[Visual Studio Solution for Silverlight 3 (ZIP)]

Notes on the code:

  • Contrary to Eric’s solution, mine will not synchronize the translation events when using the SetUpTranslationService() method in the MainPage.xaml.cs file. Use the SetUpTranslationServiceWithJoin() method if you want to have some synchronization. The main advantage of Rx is the composition of event streams, so this synchronization shows how simple things could be.
  • The code’s style is not expressing my real coding skills. Since this is just an example project, I did not make it stylish and bullet-proof.

That’s it! Have fun and please feel free to give me feedback.

kick it on DotNetKicks.com

News on Rx (Reactive Extensions for .NET)

Rx Logo - Reactive Framework - Reactive Extensions for .NETAs written before the Reactive Extensions for .NET (Rx, aka „Reactive Framework“) have been published as pre-release on their own DevLabs-site. The Rx-team is asking for feedback from you as developers and will include improvements into timely released development packages, until they’ll ship the final pieces with .NET 4.0. Check out the MSDN forum to give your feedback or ask for support.

So what’s new in Rx compared to the early DLL from the Silverlight 3 toolkit sources?

In general, many improvements were made on the API and functionality: methods on the Observable class have been rearranged and extended to give you full flexibility in many use cases. One method that I really love is Throttle(). Imagine that you have a textbox and everytime the user makes an input (without pressing Return) a data source is queried for items that match this input in some way (e.g. filtering by name or something). Now you discover that you’ve got performance issues. The search is done as the user types the first character and that’s not what you want. You only want to react to user’s input if he isn’t typing anything for -let’s say- 1 second. Throttle() solves this for you by one method call, you do not need anything else or do something manually. That’s great! Try to develop this with common event-based programming and you know what I mean…

Then the Rx-team intends to converge the functionality of IEnumerable and IObservable. IObservable has much of the functionality of IEnumerable and LINQ operators make composing, filtering and transformation of event streams very simple and intuitive. And in the DevLabs-release of Rx the Rx-team is moving some functionality from IObservable (such as the Amb() method) to IEnumerable as well. If you need it or not: this is leveraging the dualism of both concepts for developers and makes both interfaces more intuitively usable.

Furthermore the ground base of Rx is now Px (or PFx), the Parallel Extensions for .NET that will be part of .NET 4.0 as well. For every concurrent operation Px is taken and does the whole work (by creating a Task<T>). As a side effect of supporting Rx for .NET 3.5 SP1, the Rx-team has back-ported Px from .NET 4.0 to .NET 3.5 SP1 and made it usable for this platform as well. Great job!

One thing very cool and worth to mention are Subjects as new components in Rx. Subjects implement the type ISubject<S,T> and are kind of hybrids between IObserver<S> and IObservable<T>. A Subject implements both IObservable and IObserver and can be seen as „channel“ or „transforming storage“. The channel behavior is that you can push values as input into the subject via the IObserver methods (OnNext(), OnCompleted() and OnError()) and that you can subscribe to the Subject via the IObservable.Subscribe() method to get the output from the Subject. The Subject itself can do some transformation with the values that are pushed into it, can store the values and is able to take responsibility of what happens if someone subscribes to it. Subjects act as storage as well. When values are flowing into the Subject it can store them (or only the last or some transformed value, …) and when someone subscribes it can return all stored values (or only the last etc.). That means that e.g. an asynchronous operation needs not to be executed multiple times when using Subjects. The return value is stored in the Subject and can be extracted everytime a client subsribes to the Subject (independent of the moment of the subscription).
Dependent on the intent of the Subject, Rx comes with several implementations that differ in their transformation and output behavior:

  • AsyncSubject<T>: This subject is used for asynchronous operations where only one value is expected as result. Thus the AsyncSubject remembers only the last value.
  • BehaviorSubject<T>: This subject always has a current value and fires everytime the value changes. Thus it’s kind of the INotifyPropertyChanged event.
  • EventSubject<T>: This subject corresponds to an event stream and thus will never invoke OnError() or OnCompleted().
  • ReplaySubject<T>: This subject is like a tape/video recorder. It records all events that are pushed into it and can be replayed. On replay it will return all events that have been recorded in exactly the same order and time interval in which they occurred.

Another really nice development is an Add-In for Visual Studio: Reactive Extensions Generator. It overcomes the problem that all types in the .NET Framework rely on .NET events and don’t offer methods or properties that return corresponding instances of IObservable. This tool allows you to choose an assembly and it generates extension methods for all .NET events that it finds on the components of the assembly. Those methods will return the Observable pendants for those events instead. Really impressing stuff and very timely! Single drawback: it can be used only with  Visual Studio 2010 and .NET 4.0.

So to sum up again: I think Rx is valuable in many situations. First it’s a better pattern for reactive programming that unifies asynchronous programming (that normally returns just one value) and event-based programming (that typically has an infinite event-stream) and second it’s very strong when you want to compose (+ filter and transform) several event streams and when you want to build up and react to very special and complex events. Stay tuned for more information and examples on that in upcoming blog posts.

kick it on DotNetKicks.com

PDC09: Live Framework… news?

Live Mesh LogoAt the end of 2008 and at the beginning of 2009 I was really fascinated about the Live Services, Live Framework and Live Mesh. And I was so enthusiastic that I spread it around in some blog posts and one magazine article. I really liked the basic idea, the platform and (already in CTP state) the development tools. And I saw a huge potential in building social applications that can be synchronized, shared, run online or offline on many devices and last but not least are easily developed, by giving us as developers a platform that we can easily leverage and where we can concentrate on our business/application logic.

Then things became quiet at Microsoft and everybody was wondering about the future directions of the Live Framework…

On September 8th the Live Framework CTP was shutdown by Microsoft… rest in peace! This made me really angry. The developer pieces were great and fun to use. And now everything was over, nobody could write applications for the Live Framework any longer or even use their already existing code bases… I just thought: what happened to Microsoft to take this great platform offline and to carry this huge potential to grave?

When announcing the shutdown of the Live Framework CTP the guys at Microsoft said as well that they will make the Live Framework/Services part of Windows Live and that news on it will come on PDC09.

Now there was the PDC last week. But where was Live Mesh or the Live Framework? It was something so huge on the last PDC and there have been really impressive showcases, but this year’s PDC lacked information about it nearly completely. There was just one session (CL26) on the whole topic: Live Framework – Present and Future. But this session was disappointing as well. It seems that the Microsofties themselves don’t know what future direction the Live Framework will take. Two announcements were made, but only in a more-or-less inofficial fashion:

  1. Mesh technologies will be part of the next release of Windows Live.
  2. Mesh technologies will be fundamental for some Windows Live applications.

That’s it. The spirit to build a great platform has gone, at least I don’t feel anything left of it…
Just one demo has been shown, but this was disappointing as well: something like a Live Framework with synchronization capabilities, but everything is stored in folders and files on the filesystem and there seems to be no logical unit of data any more (besides those physical files/folders). What are you making there guys?

Mary-Jo Foley asked Ray Ozzie for Live Mesh at the PDC09. He said news on Live Mesh will be published at MIX 2010 respectively in spring 2010. Until then: I’m still very confused and sad about the current situation and developments on this topic at Microsoft. It seems that those guys haven’t understood the potential and once again they haven’t understood the community and the customer’s needs!

kick it on DotNetKicks.com

Silverlight 4 Beta released!

Short announcement again. I really like watching PDC keynotes! Today tons of new features in Silverlight 4 have been presented and last but not least: you can download the Silverlight 4 Beta today!

An RC will follow and the Final will be released in the first half of 2010. Stay tuned!

Download and information: http://silverlight.net/getstarted/silverlight-4-beta/
What’s new: http://silverlight.net/getstarted/silverlight-4-beta/#whatsnew
SL4 Training Course: http://channel9.msdn.com/learn/courses/Silverlight4/

Reactive Framework: it’s here!

Short announcement: Microsoft has published the Reactive Framework as Reactive Extensions for .NET (Rx) on its own DevLabs page (see release notes). Check it out now!

Rx
(Have you noticed the former Volta logo? ;-))

New Channel9 video are available, too: Rx in 15 minutes, Reactive Extensions intro, first Rx app).

And they’ve got a new Rx Team Blog.

I will give it a look at this weekend.

Reactive Framework (Rx) – first look

During the last weeks I took some time to have a first look at the Reactive Framework. Here I want to share some impressions and information with you.

Rx: What is it about?

The Reactive Framework (Rx) has been developed at the Microsoft Live Labs and is another creation by Erik Meijer, the father of LINQ. Rx will be part of the upcoming .NET Framework 4.0, but is already included as preview DLL (System.Reactive.dll) in the sources of the current Silverlight 3 Toolkit. It’s used there to get some smoother Unit Tests to work.

The aim of Rx is to simplify/unify complex event-based and asynchronous programming by providing a new programming model for those scenarios. That’s very important in a world which becomes more and more async (Web, AJAX, Silverlight, Azure/Cloud, concurrency, many-core, …) and where present approaches (event-based programming with .NET events, Begin/Invoke) hit the wall. Program logic gets hidden in a sea of callback methods which leads to nasty spaghetti code. Those of you who are creating larger async programs know what I mean 😉

Basic ideas

The main concept of Rx is reactive programming and that’s not new at all. It involves a distinction of data processing methods into push and pull scenarios:

  • In a pull-scenario your code/program is interactively asking for new data from the environment. In this case the actor is your program while it pulls new data from the environment.
  • In a push-scenario your program is reactive. The environment in pushing data into your program which has to react on every new incoming data item (see illustration below). Reactive programs are ubiquitous: every event-handler (e.g. for UI events) is an example for a reaction in a push-scenario.

Reactive Programming

The guys at Microsoft got a very important insight which builds the fundament of Rx: there’s a dualism between the Iterator and the Observer pattern! This means that both patterns are essentially the same, if you dismiss their practical intentions for a moment.
With the Iterator pattern you get a sequence of data which is iterated in the pull-mode: the Iterator is the actor and asks the iterable object for data.
The Observer pattern can be interpreted equivalently: the environment pushes data into your program (e.g. through events), which has to react. As result with repeatedly fired events you get a sequence of data, which makes the relationship to the Iterator pattern obvious.

With this, an Observer in the push-scenario is equal to an Iterator in the pull-scenario and that’s the key insight, which has led to the development of the Reactive Framework. 14 years had to pass from the publication of the GoF Design Patterns book until now to figure out this intense relationship of the Iterator and the Observer pattern.

LINQ to Events

Rx realizes the Observer pattern with the two interfaces IObserver and IObservable which are the pendants for IEnumerator/IEnumerable of the Iterator pattern. IObservable is a sort of „asynchronous collection“, which represents the occurrence of a certain event at different points in time. Thus it expresses a sequence of data, on which you can run arbitrary actions. In fact IObservable for push-scenarios is essentially the same as IEnumerable for pull-scenarios.

The interplay of IObservable and IObserver is the following: on an IObservable you can register (Subscribe()) an IObserver (Note the dualism to IEnumerable/IEnumerator here!). The IObserver has three methods OnNext(), OnCompleted() and OnError(). These methods are invoked when the IObservable gets new data, completes the data sequence or results in an error. Thus your IObserver implementations take care of the data processing which replaces your custom callback methods.

The real impressing thing with Rx is that with events as data sequences you can use LINQ syntax to process and transform these data sequences (that’s why it’s sometimes called LINQ to Events). To create instances of IObservable and for providing LINQ methods, Rx comes with the class Observable. If you want for example take the first 10 click events on a button but skip the first click, you could easily write:

Observable.FromEvent(button1, "Click")
    .Skip(1)
    .Take(9)
    .Subscribe(ev => MyEventAction(ev));

Subscribe() has some overloads. In this example I’ve directly specified an action which is executed when an event (= a piece of data) comes in. Instead you could give it e.g. your custom implementations of IObserver as well.
LINQ gives you real power in processing, composing and transforming your events as data stream. Even in the simple example above, if you would implement it by event-based programming without Rx, you would need some additional effort. You would have to use temporary variables to skip certain elements, take others and so forth. In general, more complex cases require complete finite state machines which can be circumvented with Rx.

Composing events with LINQ is another typical and impressing example for Rx. Thus, a dragging event on a textblock can be implemented as:

IObservable<Event<MouseEventArgs>> draggingEvent =
    from mouseLeftDownEvent in Observable.FromEvent(textBlock1, "MouseLeftButtonDown")
    from mouseMoveEvent in Observable.FromEvent(textBlock1, "MouseMove")
        .Until(Observable.FromEvent(textBlock1, "MouseLeftButtonUp"))
    select mouseMoveEvent;
draggingEvent.Subscribe(...);

In this example, with the from keyword the two events "MouseLeftButtonDown" and "MouseMove" are chained together. Everytime the left mouse button is pressed on the textbox, the „gate“ opens to react on mouse move events. The „gate“ closes again when the left mouse button is released. So the composed stream includes all events where the left mouse button is pressed and the mouse is moved – the typical dragging event!

There are other possibilities to compose events, which for example consider the order of events differently. Those build the interesting parts of the Reactive Framework and clarify the use cases, where Rx has real advantages over present event-based .NET programming.

Bottom line

Personally I like the new way of thinking of events as data sequence! The dualism of the Iterator and the Observer pattern has nothing artificially constructed, but some sort of purity and mathematical elegance for me. But one big question remains: do we need this in our everyday’s developer life and which advantages come with it?

Erik Meijer himself says about Rx:

Of all the work I’ve done in my career so far, this is the most exciting. […] I know it’s a bold statement, but I really believe that the problem of asynchronous programming events has been solved.

That’s a really strong message and it has some important weight since Erik is the creator of LINQ and has a big expertise in language design. Does Rx hold what he promises?

In my opinion Rx is really beautiful and valuable when you do complex asynchronous operations, where you have to compose and orchestrate events/data from several sources. With Rx you’re able to chain and filter events to easily create the concrete event, to which you want to react. That’s the power of LINQ, which allows transforming the resulting data as well. LINQ gives you the whole flexibility of processing the data stream that you already know from LINQ to Objects (on IEnumerable) etc.

Beyond that at the moment I don’t see a real big impact in many current development scenarios. If you have to handle simple events or do simple async computations, you are still fine with the present event-based programming model. Of course with Rx you can write your own observers to prevent a sea of callback methods, but encapsulation of handler logic can be done without that as well. Thus at the end I like the concepts of Rx (Observer, LINQ, …) and I’m curious to see how this whole thing develops after the release of .NET 4.0, but I’m not over-enthusiastic at the moment.

Links

Finally here is a list of links to some interesting websites regarding the Reactive Framework:

kick it on DotNetKicks.com

Is the Specification Pattern obsolete?

I’m a guy who loves many of the new patterns that I get to know. But sometimes when I show that pattern to colleagues around me, they tilt their heads and say: „Arrrm, who needs this?“. Often they help me to get back to the ground and think again about intents and benefits of one or the other pattern.

Currently I’m rethinking the Specification Pattern, which has been introduced by Eric Evans and Martin Fowler some time ago and got some attention in the DDD community and beyond. The intent of the Specification Pattern is to separate the logic for (e.g.) filtering an entity from the entity itself. This responsibility is encapsulated in single classes – the specifications. Those specifications are given for example to a single method Filter() on a repository, which takes care of filtering the domain model by the specifications. Thus, you bypass the need for having several special methods in your repository which take care of the actual filter operation (such as FilterByCustomerName(), FilterByCustomerAddress() etc.).

An example interface snippet for a repository of persons with a specification filter method could then be:

interface IPersonRepository
{
    IEnumerable<Person> Filter(ISpecification<Person> filterTerm);
    // ...
}

Summarized, some key benefits of the Specification Pattern are:

  • Loose coupling of the filter logic from the objects being filtered,
  • Single responsibility: Interface of repository/data provider isn’t polluted with lots of filter methods,
  • Callers can express in a flexible way by which criteria entities can be filtered,
  • Composition of specifications (e.g. by a fluent interface) yields to flexible filter queries, for example:
    [sourcecode language=’c#‘]var filter = Filter.By(25).And(„Frankfurt“)[/sourcecode]

But now the provocative question that one could come with: Who needs the Specification Pattern in times of C# 3.0 and Expressions? This might sound disturbing at first, but let me explain…
C# 3.0 came up with the new concept of Expressions/Expression trees. This way, code can be treated as a kind of syntax tree in the program. Developers can extend the tree with additional code portions and then compile it into executable code which can be invoked.

Therefore Expressions seem to give us similar benefits for filtering as specifications do. By using Expressions, we are able to define a single Filter() method on the repository, which gets an appropriate Expression as argument. Consumers of the repository can call this method with their custom filter Expressions and thus we’ve got the same benefits: loose coupling of filter logic and objects to be filtered, flexibility for callers to provide custom filter criteria and the possibility to combine several filter criteria (several Expressions).
One could argue that with specifications we’ve got better encapsulation of the filter logic into separate classes. But this can be done with Expressions as well (e.g. by separate wrapper classes or dedicated Expression providers), so that isn’t a good argument…

The interface of a repository of persons with a filter that uses Expressions might look like this:

interface IPersonRepository
{
    IEnumerable<Person> Filter(Expression<Predicate<Person>> filterTerm);
    // ...
}

This leads again to the question: Do we still need the Specification Pattern or is it already embedded with Expressions in the language (C# 3.0) itself?

Pattern focus

First I want to mention that the intent of a pattern is not (only) to provide a technical solution, but also a conceptual guideline for a problem at hand. Thus Expressions as technical solution don’t cover the intent of the Specification Pattern. The Specification Pattern can be implemented with the help of Expressions, but that’s another point. So, directly comparing the Specification Pattern with Expressions is like an apple-pear-comparison.

Encapsulation focus

Let’s come to use cases when I would prefer the use of dedicated specification classes rather than directly using Expressions.
First as a team lead you could want to enforce the use of dedicated specification classes in your development team (thus enforce encapsulation of the filter logic). By giving Expressions or Predicates to filter methods directly,  developers would be allowed to define filter expressions whereever they want to. You don’t have the control over this process and please don’t trust your project guidelines: If developers are allowed to do something wrong, they will do.

With specifications you can force your team members to write specification classes for their requirements, which leads to enforced encapsulation. Furthermore you drive reuse of existing specification classes. Other developers are encouraged to use existing specifications, especially because of the additional effort for writing new specifications. By combining several specifications, the reusability aspect is pushed even more.

Domain model focus

Giving consumers the full flexibility of defining custom filter criteria with specifications can be very handsome in many situations. However, in other scenarios instead of giving full flexibility, you may want to restrict the set of filters for your domain model. If you focus on your domain, you perhaps want a restricted set of specifications, each with a very specific meaning in your domain! Binding such specifications to your domain model makes the purpose of your domain and how it can/should be used in terms of filtering much clearer.

Technically, in order to restrict access to a particular set of specifications, you could create sealed specification classes inside of your domain model services (same layer as repository). Consumers of the repository would be allowed to call the Filter() method on the repository with those specifications (and compositions of those), but they would not be able to create new specifications if you don’t mark the specification interface as public. This way you get two characteristics: Restricted filtering, which fits into your domain and your use cases on the one hand, and encapsulation/separation of filter logic and entities which should be filtered on the other hand.

Bottom line

This article started with an interesting and provocative question: Is the Specification Pattern obsolete? This question came up with a look at Expressions in C# 3.0. Technically you can achieve similar results when using Expressions instead of implementing the Specification classes by hand. But as the last sections have shown, in my opinion the Specification Pattern is not obsolete! As pattern it’s adding very specific value to the plain technical solution, when you take encapsulation and domains into account. Then it clearly goes beyond the technical aspect which many developers see at first sight.

Those are my current thoughts on specifications, but of course my opinions are not carved in stone. What do you think? What points I’ve missed perhaps? I’m eager for your comments!

kick it on DotNetKicks.com

Code Contracts #8: Sandcastle integration

Release 1.2.20903 (4 Sep 2009) of Code Contracts comes with a nice integration of contracts on classes and methods into Sandcastle documentation! By this, Code Contracts achieve an important goal: real „checked documentation“. This short article gives an overview of how to get your Sandcastle installation to handle contracts.

1) Install Sandcastle (+DocProject)

At first, of course you need a valid Sandcastle installation. Just go to the Sandcastle project page, download the latest release and install it. I recommend installing DocProject for Sandcastle and HTML Help Workshop and Documentation as well. This gives you a nice Visual Studio integration for creating documentation by Sandcastle.

2) Patch Sandcastle with Code Contracts files

Code Contracts documentation syntax is currently not included in the Sandcastle project. In order to make Sandcastle aware of the Code Contracts documentation items, you have to patch the Sandcastle installation with the Code Contracts files. For this, there exists a folder „Sandcastle“ in the Code Contracts installation directory (default is „Program Files\Microsoft\Contracts\Sandcastle„), which contains a file „Sandcastle.zip„.

If you’ve installed Sandcastle from the MSI package, just copy the contents from the „msi\vs2005“ folder of the UIP file to the following location of your Sandcastle installation: „Program Files\Sandcastle\Presentation\vs2005\„. Now you’re done and ready to generate documentation for your contracts!

3) Set up your project

First, if you want to generate documentation for a project in Visual Studio, go to the project properties and in the „Build“ option pane, check the XML documentation file option:

Activate the "XML documentation file" option

Then, to get the contracts injected into the generated XML doc file, go to the „Code Contracts“ option pane and select both the Build a Contract Reference Assembly and the Emit contracts into XML doc file options:

Select generation of Code Contracts documentation

Now, when you build your project, first the documentation of your project’s components will be created as XML file and then the contracts documentation will be injected in the same file.

4) Create your documentation!

For demonstation purposes, I’ve generated a project (including a new solution) AccountExample in Visual Studio, which holds just one class Account. This example class contains some contracts and looks as follows:

/// <summary>
/// Represents an account, to which you can deposit and from which you can withdraw money.
/// </summary>
public class Account
{
    private float _balance;
    /// <summary>
    /// The current balance of the account.
    /// </summary>
    /// <value>The account's balance.</value>
    public float Balance
    {
        get { return _balance; }
        private set
        {
            Contract.Requires(value >= 0);
            _balance = value;
        }
    }

    [ContractInvariantMethod]
    protected void ClassInvariants()
    {
        Contract.Invariant(_balance >= 0);
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="Account"/> class.
    /// </summary>
    /// <param name="balanceInitial">The initial balance, which will be set.</param>
    public Account(float balanceInitial)
    {
        Contract.Requires(balanceInitial >= 0);
        Contract.Ensures(Balance == balanceInitial);

        Balance = balanceInitial;
    }

    /// <summary>
    /// Deposits the specified amount to the account.
    /// </summary>
    /// <param name="amount">The amount to deposit.</param>
    public void Deposit(float amount)
    {
        Contract.Requires(amount > 0);
        Contract.Ensures(Balance == (Contract.OldValue(Balance) + amount));

        Balance += amount;
    }

    /// <summary>
    /// Withdraws the specified amount from the account.
    /// </summary>
    /// <param name="amount">The amount to withdraw.</param>
    public void Withdraw(float amount)
    {
        Contract.Requires(amount > 0);
        Contract.Requires(amount <= Balance);
        Contract.Ensures(Balance == (Contract.OldValue(Balance) - amount));

        Balance -= amount;
    }
}

Moreover, I’ve added a new DocProject to my solution, where I’ve chosen the „AccountExample“ project for generating the documentation from. With that we’re ready to roll!

When building the whole solution, first the assembly of the „AccountExample“ project is built. In this step, the following XML documentation file is extracted as well (note the injected contract tags – requires, ensures and invariant):

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>AccountExample</name>
  </assembly>
  <members>
    <member name="T:AccountExample.Account">
      <summary>
            Represents an account, to which you can deposit and from which you can withdraw money.
            </summary>
      <invariant>_balance >= 0</invariant>
    </member>
    <member name="M:AccountExample.Account.#ctor(System.Single)">
      <summary>
            Initializes a new instance of the <see cref="T:AccountExample.Account" /> class.
            </summary>
      <param name="balanceInitial">The initial balance, which will be set.</param>
      <requires>balanceInitial >= 0</requires>
      <ensures>Balance == balanceInitial</ensures>
    </member>
    <member name="M:AccountExample.Account.Deposit(System.Single)">
      <summary>
            Deposits the specified amount to the account.
            </summary>
      <param name="amount">The amount to deposit.</param>
      <requires>amount > 0</requires>
      <ensures>Balance == (Contract.OldValue(Balance) + amount)</ensures>
    </member>
    <member name="M:AccountExample.Account.Withdraw(System.Single)">
      <summary>
            Withdraws the specified amount from the account.
            </summary>
      <param name="amount">The amount to withdraw.</param>
      <requires>amount > 0</requires>
      <requires>amount <= Balance</requires>
      <ensures>Balance == (Contract.OldValue(Balance) - amount)</ensures>
    </member>
    <member name="P:AccountExample.Account.Balance">
      <summary>
            The current balance of the account.
            </summary>
      <value>The account's balance.</value>
      <setter>
        <requires>value >= 0</requires>
      </setter>
    </member>
  </members>
</doc>

In a second step of the build process, the DocProject generates the documentation for the „AccountExample“ project by taking its XML documentation file. When finished, we’ll have a nice CHM file with the documentation of our example project.

In this documentation we can see our contracts now. On class level, we have our invariant:

Class invariants in Sandcastle documentation

And on method (+properties) level, we get the pre- and postconditions:

Method contracts in Sandcastle documentation

Conclusion

As you can see, contracts in documentation are really valuable. Including them in Sandcastle documentation brings the claim of „checked documentation“ to life! This really helps other developers to understand the intent of your classes by looking at the documentation. And by automatically generating documentation out of your code-based contracts, you can be sure that docu and code do not run out of sync. This really puts more value on Code Contracts and is a real practical advantage!

kick it on DotNetKicks.com

New Code Contracts Release

On September 4th, Microsoft has made a new Code Contracts release available. Release 1.2.20903 (4 Sep 2009) comes among others with the following changes:

  • Inclusion of Code Contracts into Sandcastle documentation! Thereby, Code Contracts achieve a full state of „checked documentation“.
  • Improvements of the dynamic and static checker
  • More contracts on core .NET framework assemblies
  • Silverlight 3 support
  • Many bugfixes on community feedback

Important hint: there are no API changes! Thus existing examples and blog posts on Code Contracts remain valid. Have a look at the release notes for a full list of changes.

Please keep posting your comments and suggestions for improvement on the Code Contracts forum.

Code Contracts #7: Relation to Guard classes

Hey guys. After two months of many things to do I come back again with an article to Code Contracts. This day’s topic are guard classes and how they relate to Code Contracts.

Recently my colleague AJ posted a really nice article about guard classes. He’s the first one who explained the topic as a whole and showed the advantages of using guards. In short version, guard classes in this context are mainly about guarding against passing invalid arguments into class methods.

For example, without having a guard, you would check method arguments that way:

public void FooMethod(string arg)
{
    if(arg == null)
        throw new ArgumentNullException("arg");
    if(arg == "")
        throw new ArgumentOutOfRangeException("arg");
    ...
}

While this approach is defensive and can lead to less errors, it’s quite ugly to have those checks defined in every method directly. First, the if-clauses are polluting the method’s body. The if and throw keywords are too much information at this location. Second, for example if a string should not be empty, it’s obvious that it may not be null as well. And what if we want to log those exceptions or do something else (for example inform an administrator)? Here come guard classes into play. The aspect of throwing exceptions and perhaps do something before that is outsourced into a separate utility class Guard. With that on hand, the example from above would transform into:

public void FooMethod(string arg)
{
    Guard.AssertNotEmpty(arg, "arg");
    ...
}

You can find the guard’s AssertNotEmpty() method in AJ’s post.
The guard encapsulates the argument validation as cross-cutting-concern and makes it exchangable. The call clearly expresses what is done at that point and thus it’s better separated from the core logic of the method. It concentrated on the main purpose and not on the implementation details.

Well, how are method guards fitting with Code Contracts or Design by Contract (DbC) at the whole? The simple answer: method guards are nearly equivalent to preconditions in DbC! They express the basic conditions on level of physical constraints, under which a method is expected to work correctly.

With Code Contracts, in .NET 4.0 we don’t need an explicit Guard class any longer. The above example can be realized with Code Contracts as:

public void FooMethod(string arg)
{
    Contract.Requires(arg != null, "arg should not be null");
    Contract.Requires(arg != "", "arg should not be empty");
    ...
}

As with guard classes, this ‚precondition block‘ abstracts the implementation details of the check itself and it’s purpose is obvious, thus leading to a separation of the core logic, if you look at the method with developer’s eyes.
One ‚problem‘ remains with this example. With the guard class we’ve had the chance to define individual methods, that fit our needs. For example, it checks for empty strings that they aren’t null as well (please take aside String.IsNullOrEmpty() for a moment) or it puts in logging logic. Code Contracts gives us just the Contract.Requires() method, which doesn’t have these abilities at first. If you have many repeating individual checks I suggest to use a separate static class that contains all of your needed checks as methods, that return a boolean value if the check passes. Those methods must be declared [Pure] in order to be used in contracts, thus they must be free of observable side effects. With such a class Check, the example above would look as follows:

public void FooMethod(string arg)
{
    Contract.Requires(Check.NotEmpty(arg), "arg should not be null or empty");
    ...
}

Check is simple in this case:

public static class Check
{
    [Pure]
    public static bool NotEmpty(string arg)
    {
        return ((arg != null) && (arg != ""));
    }
}

Alternatively, you could define extension methods on the datatypes, that should get individual checks. This frees you from a dedicated class, that must know all of the datatypes to check.

For doing additional stuff like logging on fail of a precondition, you get the ability to plug in your own custom contract runtime class. Please read the Code Contracts documentation for detailed information on this subject.

Thus, Code Contracts give you the same advantages as guard classes. But moreover, there are clear additional benefits!
First, you are free to change the check behavior of your preconditions by configuration. The Code Contracts tools allow you to perform checks in debug mode only or even in the release build. Furthermore you can define, if you want the program to Assert or to throw an exception, if a precondition check fails and so on. Thus, you get a high flexibility to adapt Code Contracts to your own needs.
Second, Code Contracts give you the ability to directly extend the interface of your class. It allows you to define contracts on abstract classes and interfaces, that will be automatically taken into concrete implementations.
Third, contracts of all kinds are derived to every subclass of the class, where you have defined them. By that, you aren’t allowed to add any precondition in your subclass with Code Contracts, but you are able to define additional postconditions or invariants. Thereby, the compliance of the Liskov Substitution Principle is enforced on the level of contracts.
Fourth, don’t forget that DbC is a design principle and goes beyond the technical implementation on the level of guard classes.
Fifth, precondition checks allow tool support. They can be included in the run of the static checker and even the automatic test generator Pex is aware of contracts and uses preconditions of your methods as test oracle.

That’s it for now. In conclusion, Code Contracts go beyond guard classes and because they are a core component of .NET 4.0, you don’t need custom guard classes any longer. Simply use contracts instead…

kick it on DotNetKicks.com