orktane

In the first part I introduced nRoute.Toolkit as nRoute vNext sans Navigation and Composition components - whilst it lacks two of the key features, it introduces a boat-load of new features including Bindable Dependency Objects, Bindable Triggers, Actions and Behaviours for Blend, an IObservable-based Messaging Framework, Services component, View Services component, Modules component, ViewModel component and more. Extending that feature-set, in this post I'll cover some of the other more component-oriented features in the toolkit, like ICommand implementations, ICommand extensions, Weak Eventing handlers, Eventing extensions, and various Relays.

Action(able) ICommands

With regards to MVVM in Silverlight, I believe two interfaces carry a disproportionate share of the "architectural burden"  - with the two interface being ICommand and INotifyPropertyChanged. Both these interfaces bridge the chasm between the View and the ViewModel - one signifies an action occurrence, and the other signals a value change. Now, as far as the ICommand related functionality is concerned, they are well represented in the toolkit by two implementations named ActionCommand<T> and ActionableCommand<T>. Both of these implementations are actually refinements of what was earlier available in nRoute, however now they derive from a common interface called IActionCommand.

With reference to the IActionCommand interface, the 'IsActive' property allows you to enable or disable the command, whereas the 'RequeryCanExecute' method allows you re-evaluate as to if the command can be executed, and CommandExecuted event is, well, quite self-explanatory. Both the ActionCommand<T> and ActionableCommand<T> support strongly-type parameters, and take in an Action<T> delegate to handle the command execution. The difference between Action and Actionable Commands is that the latter allows you to designate another delegate to determine as to if the command can be executed. Here's a simple example:

   1: // declared

   2: public ActionableCommand<string> SearchCommand { get; private set; }

   3:  

   4: // defined

   5: SearchCommand = new ActionableCommand<string>((s) => Repository.Search(s),

   6:                 (s) => !string.IsNullOrEmpty(s));

In the example above, we have defined a command that can take in a string value and uses it to search some repository. The command also defines a delegate that ensures that the search string is not null or empty before executing the command.

Now, as show in the class diagram, we also have non-generic versions of these commands that not only drop the generic parameter but also relieve you from having to process the same - so they ask for an Action delegate as opposed to Action<T>. I was surprised how useful these non-generic versions are, in my own use scenarios nowadays almost 95% of all of my commands are of the parameter-less variety.

Command Extensions

Very often you will find that a command's execution is dependent on some other factor, for example a delete command might be dependent on having something selected or like above a search command is dependent on the search-string being not null and not empty. Given a set of dependencies, a single change in any dependency requires us to manually re-evaluate a possibility of change in the executable-status of the command - specifically, with the IActionCommand interface, this is done via its RequeryCanExecute method (which inturn suggests this by raising its CanExecuteChanged event).

So, the point of the command extensions is to explicitly define dependencies which then can automatically trigger the possibility of a change in the executable-state of a command. I think the concept is easier described in code, have a look:

   1: var DeleteCommand = new ActionableCommand(

   2:     () => Repository.Delete(this.ActiveItem),

   3:     () => this.ActiveItem != null

   4: ).RequeryOnPropertyChanged(this, () => ActiveItem);

In the snippet above, the delete command allows us to delete the active item, where an active item is something that has been say selected in a ListBox. And the constrain on the execution of this command is that the ActiveItem property is not null, as shown in line 3. Now every time the selection of the ActiveItem changes, we must re-query the command's executable state - this intent is made explicit with the extension method shown in line 4. Here, the extension method exploits an INotifyPropertyChanged capable ViewModel (this) and listens for 'ActiveItem' property changes, which when changed triggers a re-query of the command's executable-state. Another version of this extension method exists that doesn't require a property name, as it listens to any/all property changes.

Similarly, we have another extension method that re-evaluates the executable-state after the command is executed. In the example below, the command's task is to set the count value to zero and therefore is only executable when the count is not zero. By using the RequeryWhenExecuted extension method we ensure that whenever the command is executed it's state is re-evaluated.

   1: var SetCountZeroCommand = new ActionableCommand(

   2:     () => this.Count = 0, 

   3:     () => this.Count != 0);

   4: SetCountZeroCommand.RequeryWhenExecuted();

There is another similar extension method called RequeryOnCommandExecuted which re-evaluates a command's status when another command is executed. So for example:

   1: // two commands

   2: SubscribeCommand = new ActionableCommand(() => { ... };

   3: UnsubscribeCommand = new ActionableCommand(() => { ... };

   4:  

   5: // explict dependencies

   6: UnsubscribeCommand.RequeryOnCommandExecuted(SubscribeCommand);

   7: SubscribeCommand.RequeryOnCommandExecuted(UnsubscribeCommand);

In the case above, the subscribe and unsubscribe commands' execution-states are re-evaluated when any of the other command is executed. Their respective execution-state is dependent on the whether or not a subject is subscribed or not. Another extension method called RequeryOnCommandCanExecuteChanged can re-evaluate a command by listening to another command's CanExecuteChanged event. However, you must be careful to not peg this extension method onto two commands re-querying against each other, as you will create an infinite loop between the two.

   1: // Declared

   2: public ActionableCommand CreateItemCommand { get; private set; }

   3:  

   4: public ActionCommand UndoCommand { get; private set; }

   5:  

   6: // Dependency Defined

   7: UndoCommand.RequeryOnCommandCanExecuteChanged(CreateItemCommand);

Lastly, we also have a RequeryOnCollectionChanged extension method, that can re-query a command when an INotifyCollectionChanged implementing collection changes. For example below, the command's execution status is dependent on the messages' collection having one or more messages, and so we make that explicit:

   1: ClearCommand = new ActionableCommand(() => Messages.Clear(),

   2:     () => Messages.Count > 0).RequeryOnCollectionChanged(Messages);

These extension methods work by pinging against the IWeakEventListener implementation that both ActionCommand<T> and ActionableCommand<T> support. Basically, the commands uses the ReceiveWeakEvent method to listen to any external suggestions that the command's execution-state might have changed, and so when pinged they raises the CanExecuteChange event to tell others to check their execution-status against the command. And as the interface name suggests, this is weakly/indirectly-referenced so you don't create leaking dependencies. Further, you can also use the same technique to attach explicit dependencies, using custom extension methods or just by making the command listen to any relevant event.

Execute Command Behavior

The ExecuteCommandBehavior does as it reads - with two notable features, one that both the command and command parameter are bindable. And second that it can enable/disable the usage of the associated element if ManageEnableState option is selected (see right).

The ManageEnableState option basically enables or disables a Control-type derived element, based on whether or not the command is executable. It listens to the CanExecuteChanged event and can re-evaluate the execution state of the command. Now, in the case where the element attached to the behaviour is not a Control-type derivative, it enables/disables the "interactivity" of the element - the interactivity concept is the same as one I mentioned in part one except here when the element is disabled we set the opacity to 50% (which might not be appropriate in all cases).

The snapshot above shows the effect of the ExecuteCommandBehavior managing the enable state for you. The "Button Command" reading element is a button control (which is derived from the Control type), whereas as the "Border Command" reading element is a border element (not deriving from the Control type). In both the cases when the command cannot execute, they are non-responsive to user input - however as I've mentioned before there are limitations to how far the the interactivity approach will take you.

Weak / Event Handling

In another previous post I had detailed some of my ideas around weak eventing, with the crux of the idea being that by wrapping event handlers we could make the eventing infrastructure smarter without having to re-imagine the consumption or creation of events. And smarts give us the ability to weakly-reference the consumers, which makes the event consumer's lifetime independent of the event producers. Here's the how-to:

   1: source.SomethingHappened += new WeakHandler(Handle_Something, 

   2:     (h) => source.SomethingHappended -= h);  

In the snippet above rather than using an EventHandler delegate, we are using the WeakHandler class to handle the SomethingHappened event on the source object. The WeakHandler class implicitly creates the event handler, whilst lifting itself into the handler - and so it sits between the consumer and producer of event. By virtue of having a go-between we can do a lot of interesting things (as we'll see ahead), and so we also provide wrappers for normal handling (ie. non-weak) of the events. Secondly, by having this go-between we also gain the capability to allow consumption of events for non-delegate consumers - specifically, for IWeakEventListener and IObserver<Event<T>> based consumers. Consider:

   1: // using Listeners

   2: source.SomethingHappened += new WeakListener(weakEventListenerObj, 

   3:     (h) => source.SomethingHappended -= h);  

   4:  

   5: // using Observers

   6: source.SomethingHappened += new ObserverHandler(weakObserverHanderObj, 

   7:     (h) => source.SomethingHappended -= h);  

Also the IActiveCommand component mentioned above that makes uses of the WeakListener handler, similarly the Rx Framework makes use of Event to IObserver<Event<T>> translation for all its magic. Now, I'm not going to go into the depth of the eventing infrastructure, but basically there are six main classes - which allow for handling, listening, and observing of events in both strongly-referenced and weakly-referenced manners.

In all the classes above the type E generic parameter is an EventArg derivative associated with the event handler delegate of type H - for example to handle a size changed event for a Window the parameter E would be SizeChangedEventArgs and the associated parameter H would be SizeChangedEventHandler. To save you some time, there are some pre-defined wrappers available to handle common events based on EventHandler, EventHandler<E>, RoutedEventHandler and PropertyChangedEventHandler delegates. Also note all the given handlers are disposable - so when a handler is called upon to dispose it unregisters from the event and clears all references to the consumer/producer paving the way to be GC'ed.

Eventing Extensions

Like I said earlier, the idea with event handling wrappers was to introduce smarts in the consumption of events - and we have a number of smarts (beyond weak handling) available in the form of extension methods. Now, a lot of this would look like the Rx Framework which is by both by inspiration and design, but functionally it is quite different - here we have a pipeline model as opposed to an event stream model. And it works by the wrapper having pre-handling, post-handling and predicate-type gateways to the actual handling of the event. Also you can use these extensions whilst consuming an event via handlers, listeners or observers.

Handle When

   1: this.MouseEnter += new Handler<MouseEventArgs, MouseEventHandler>(

   2:         (s, e) => StartDragging(e),

   3:         (h) => this.MouseEnter -= h).

   4:     When(

   5:         (e) => e.EventArgs.StylusDevice.DeviceType == TabletDeviceType.Touch);

The When extension is simply a predicate to handling the event, and so when true it handles the event else it ignores the event call.

Skip When

   1: this.MouseLeftButtonUp += new ObserverHandler<MouseButtonEventArgs, MouseButtonEventHandler>(

   2:         _mouseButtonObserver,

   3:         (h) => this.MouseLeftButtonUp -= h).

   4:     SkipWhen(

   5:         (e) => _flagged);

The SkipWhen extension is the simply a negated version of the When predicated, therefore when true it skips the handling else it handles the event.

Handle Once

   1: Button1.Click += new RoutedHandler(

   2:         (s, e) => ProcessQuotation(),

   3:         (h) => Button1.Click -= h).

   4:     HandleOnce();

As the name suggests the HandleOnce extension ensures that you handle the event once and only once, it disposes off the handler post the first event. This is quite useful especially when you knowingly will only handle the event once, as in the case of loading or initialization, and with this extension you don't have to worry about unregistering the handler.

Handle Exactly

   1: LoginButton.Click += new RoutedHandler(

   2:         (s, e) => LoginUser(),

   3:         (h) => LoginButton.Click -= h).

   4:     HandleExactly(5);

HandleExactly extension will only handle the event a given number of times, thereafter it will unregister and dispose off the handler.

Handle While

   1: AuthorizeButton.Click += new RoutedHandler(

   2:         (s, e) => Authorize(),

   3:         (h) => AuthorizeButton.Click -= h).

   4:     While(

   5:         (e) => User.Session.IsAlive);

Keeping to its name, the While extension method handles an event while the given condition is true. If the condition turns false, it will unregister and dispose off the handler.

Handle Until

   1: AuthorizeButton.Click += new RoutedHandler(

   2:         (s, e) => Authorize(),

   3:         (h) => Authorize.Click -= h).

   4:     Until(

   5:         (e) => User.Session.IsAlive);

The Until extension is basically similar to the While extension, except that it allows for at least handling the event once. The While/Until terminology is akin to similarly-named operators in Visual Basic.

Handle For

   1: _model.PropertyChanged += new PropertyChangedHandler(

   2:         (s, e) => OnCountChanged(),

   3:         (h) => _model.PropertyChanged -= h).

   4:     HandleFor(

   5:         () => _model.Count)

   1: this.DecreaseButton.Click += new RoutedHandler(

   2:         (s, e) => _viewModel.DecreaseCount(),

   3:         (h) => this.DecreaseButton.Click -= h)

   4:     Throttle(

   5:         TimeSpan.FromSeconds(5d));

The Throttle extension limits the handling the event to once per the given duration, so in the example above the handler will only be allowed to be executed once every five seconds from the execution of last event - with other calls within the same period being ignored.

Handler Timeout

   1: this.ConfirmButton.Click += new RoutedHandler(

   2:         (s, e) => _viewModel.Confirmed(),

   3:         (h) => this.ConfirmButton.Click -= h).

   4:     Timeout(

   5:         TimeSpan.FromSeconds(120), () => ConfirmButton.IsEnabled = false);

The Timeout extension awaits for event to occur within the specified time span, failing which the event handler is deregistered and the handler disposed off. Also you can specify an Action to be executed when the timeout expires. One benefit to this extension is that it brings the timeout semantics to any/all types of event.

Recurring Timeout

   1: this.KeyUp += new WeakListenerHandler<KeyEventArgs, KeyEventHandler>(

   2:         _dharmaInitiativeListener,

   3:         (h) => this.KeyUp -= h).

   4:     RecurringTimeout(

   5:         TimeSpan.FromMinutes(108), () => BlowupLostIsland());

The RecurringTimeout extension is basically like the Timeout extension except that every time the event occurs it resets the timeout and starts counting down again. Similarly, if the timeout were to occur the event handler is deregistered and the handler is disposed off, plus you can also specify a timeout Action delegate.

Lastly, note you can apply one or more of these extensions to a single handler, and equally you can create your own extensions for use with the given handlers in the toolkit.

Relays

My earlier post on relays, introduced IValueConverter and ICommand relays - building on that, we now have a ValueRelays and binding support for all relays types. Simply put, the point of relays is to act as a statistically declared go-between the actual implementation or value that is specified at runtime. The scenarios where this is useful is when you need to delegate the actual implementation/value from some other source such as a ViewModel or into something like a DataTemplate.

Value Converter Relay

Basically you use the ValueConverterRelay as a statistically declared resource that fronts an IValueConverter implementation defined at runtime. Statically, declaring a relay is as simple as:

   1: <nComponents:ValueConverterRelay x:Key="DateStringRelayConverter" />

   1: ((ValueConverterRelay)this.Resources["DateStringRelayConverter"]).Converter =

   2:     new ValueConverter<DateTime, string>((d) => d.ToString("DD, MMMM"));

   1: this.SetRelayConverter<DateTime, string>("DateStringRelayConverter",

   2:     (d) => d.ToString("DD, MMMM"));

The other way of defining a backing implementation for a value-converter relay is to bind the relay by bridging it. To do this, you can use the generously-named BridgeValueConverterBehavior type behaviour, and have it bind to any implementation like say from your ViewModel.

   1: // declare

   2: public ValueConverter<User, string> UserNameConverter { get; private set; } 

   3:  

   4: // define

   5: UserNameConverter = new ValueConverter<User, string>(

   6:     (u) => u.LastName.ToUpper() + ' / ' u.FirstName + ' ' + u.Title);

   1: <!-- Declared as a Resource -->

   2: <nComponents:CommandRelay x:Key="UpdateTimeRelayCommand" />

   1: this.SetRelayCommand<object>("UpdateTimeRelayCommand", (o) => UpdateTime());

   1: <i:Interaction.Behaviors>

   2:     <nBehaviors:BridgeCommandBehavior 

   3:         CommandRelay="{StaticResource UpdateTimeRelayCommand}" 

   4:         CommandSourceBinding="{Binding UpdateTimeCommand, Mode=OneWay}"/>

   5: </i:Interaction.Behaviors>

   1: <!-- Data Template declared as a Resource -->

   2: <DataTemplate x:Key="TimeInfoTemplate">

   3:     <Grid>

   4:         <Button Content="Update Time">

   5:             <i:Interaction.Triggers>

   6:                 <i:EventTrigger EventName="Click">

   7:                     <nBehaviors:ExecuteCommandAction 

   8:                         Command="{StaticResource UpdateTimeRelayCommand}"/>

   9:                 </i:EventTrigger>

  10:             </i:Interaction.Triggers>

  11:         </Button>

  12:     </Grid>

  13: </DataTemplate>

   1: <nComponents:ValueRelay x:Key="CurrentTimeRelayValue" />

   1: this.SetRelayValue<DateTime>("CurrentTimeRelayValue", DateTime.Now);

For bridging the value we can make use of the BridgeValueBehaviour type behaviour. It takes in the relay and provides it with a value as defined by either the ValueSource or ValueSourceBinding property (see right).

   1: <TextBlock Text="{Binding Value, 

   2:     Source={StaticResource CurrentTimeRelayValue}, Mode=OneWay}" />

nRoute Toolkit is basically a packaging of some components from the next drop of nRoute - I thought some of the components had merit beyond the nRoute framework, so I packaged them separately in a smallish 50K toolkit. The Silverlight only toolkit features Bindable Dependency Objects, Bindable Triggers, Actions and Behaviours for Blend, an IObservable-based Messaging Framework, a Resource Locator Framework, Module Components, Service Components, ViewModel Components, ViewService Components, Weak Eventing Handlers, Action ICommands and a number other bit and pieces useful for MVVM style development.

I hope to have this introductory post as a semi-documentation for the toolkit and its features, so please bear with me as it does get long. Secondly, the next drop of nRoute will essentially be a superset of what's in this toolkit - namespaces and all will remain the same, however the toolkit doesn't include any routing or navigation related features.

Bindable Dependency Objects

One of the biggest pain point with Silverlight, as of version 3, is that it only supports binding on FrameworkElement derived objects - which in effect limits binding to "visual components" - and therefore "inline" elements don't get the benefit of binding. Now, what I have here is not a perfect solution but a pretty workable one, and I refer to it as attached-bindings because it attaches the binding on any FrameworkElement derivatives (even non-hierarchically related).

The trick in play here is that you have to expose and consume the binding as a System.Windows.Data.Binding type. So for instance, say we have a Dependency Object derived class that has a ordinary "IsReady" dependency property; now, to make it bindable using attached bindings, we have to use what I call a dual-property pattern - wherein we expose the property "normally" but also have another property (post-fixed with the Binding word) of type Binding that is used to bind to the dependency property. Have a look below, note 'GetAttachedBinding' and 'SetAttachedBinding<T>' are extension methods:

   1: public bool IsReady

   2: {

   3:     get { return Convert.ToBoolean(this.GetValue(IsReadyProperty)); }

   4:     set { this.SetValue(IsReadyProperty, value); }

   5: }

   6:  

   7: public Binding IsReadyBinding

   8: {

   9:     get { return this.GetAttachedBinding(IsReadyProperty); }

  10:     set { this.SetAttachedBinding<bool>(_frameworkElement, IsReadyProperty, value); }

  11: }

Given the above, to bind we use the binding syntax against the 'IsReadyBinding' property, while to read the current value of we use 'IsReady' property. If you don't want to use bindings, the IsReady property works just as before and everything else remains the same. The critical part to enable attached bindings is to have a FrameworkElement derivative element to attach too, as represented above by the '_frameworkElement' variable - without this it wouldn't work. But once you have that you can have as many attached-bindings appended to it as you like, it doesn't matter. Secondly I understand having an additional property for each bindable property is not ideal, but it's a working solution and is kind of akin to the async post-fix we already use. Plus, with the extension methods shown above this is not that intrusive of a methodology, especially since you don't need do anything more than create an additional property declaration per dependency property.

Now there are a lot of uses for this, and using this infrastructure included in the toolkit are extensions to the Blend behaviours framework as we'll see right ahead - this also happens to be my favourite new feature in the toolkit.

Bindable Behaviors, Actions and Triggers 

In the first drop of nRoute I did a lot of work on behaviours, in fact I did create something very similar to what is available in Blend but didn't generalize it using triggers, rather per my preference of strong-typed stuff, I created many-many statically declared attached properties to expose/use behaviours. But part of the reason was also that inline dependency objects could not be bound in Silverlight, where as attached properties declared directly onto any FrameworkElement derivate could be. Now, with the binding infrastructure given above and fantastic tooling support in Blend, I choose to dump my behaviour's framework and extend the behaviours and triggers framework made available with the Blend SDK - essentially by making them bindable. This really makes for some fantastic possibilities, because we can now use and consume behaviours that are directly bound to our ViewModel or have them react to property changes through the richness of binding in Silverlight.

In the nRoute.Behaviors.Interactivity namespace you will find four classes that extend the behaviours, trigger actions and triggers in the Blend SDK, with bindable base classes.

The binding-enhanced base classes (below the red-line) give you wrappers around the attached binding solution, and a very important capability to set bindings even when the "AssociatedObject" is not available (it stores and applies the binding to it when the object is attached). So for example, if we had the IsReady property sampled above exposed in any of the above behavior/trigger classes we would write the same as:

   1: public bool IsReady

   2: {

   3:     get { return Convert.ToBoolean(this.GetValue(IsReadyProperty)); }

   4:     set { this.SetValue(IsReadyProperty, value); }

   5: }

   6:  

   7: public Binding IsReadBinding

   8: {

   9:     get { return base.GetBinding(IsReadyProperty); }

  10:     set { base.SetBinding<bool>(IsReadyProperty, value); }

  11: }

As you can see in Line 9 and 10 we are using the base-class based GetBinding and SetBinding methods, they do the attach-binding business underneath. So quite simply, to make your behaviour/trigger/trigger-action property bindable you just need to additionally write something similar to lines 7 to 11 and that's it. Also, with this you can use all the UI facilities in Blend to set the bindings as usual, alternatively if you wanted to bind to static resources you would use the non-binding version (ie. IsReady and not IsReadyBinding). The binding-enhanced base classes are there for your own use, but I've also included some commonly needed behaviours, triggers, and trigger-actions some of which are detailed below.

Value Triggers

Value triggers are Blend-SDK based triggers that fire when a given property's value matches a given criteria - for example, you could use a ValueTrigger to show a special discount animation when when the total cart amount exceeds $1000 in your ViewModel. You can also use this with UI controls, like match some value in a text box and trigger a command in your ViewModel.

In many ways ValueTriggers are central to MVVM, because to my understanding in a MVVM architecture data changes are the primary ViewModel-based mechanism that effect changes in View, and for the other side of the equation data changes and ICommands are the two View-based mechanisms that effect changes in the ViewModel (see the diagram below). Events are not used, because they are a form of direct-coupling - and so there is a total reliance on the SL binding infrastructure for the loosely-coupled glue that makes it all possible. Further for me, this minimal scope of connections is both the beauty and the practical stick that keeps the ViewModel and View independent of each other despite the fact they are intimately interwoven.

Given the concept above, the practical problem in SL today is consuming the data-changes to effect logical changes in your application, value changes in the controls such as text value is 100% supported but changing the logical state is not. And this is where the ValueTriggers come into play, by combining binding, triggers and trigger-action we can effect logical changes in the View such hiding something or moving something. Next, I'll go through the five value triggers available in the toolkit - just keep in mind you can pair this up with just about any trigger-action or behaviour.

ValueMatchTrigger

Basically it allows you trigger an action when a given source's value equals to another specified value - in the example shown from Blend, the value must match the specified "nRoute" value and then only will it trigger the associated action. Also, the source binding is coming from a ViewModel and we're matching it against a static word but you could match it against anything bindable by using the ValueBinding property. Also note any changes in the Source Binding triggers a re-evaluation of the condition. Alternatively, if you require it not match the specified value then you can negate the result, by using the negate checkbox. The xaml for this example looks like:

   1: <nTriggers:ValueMatchTrigger SourceBinding="{Binding Key, Mode=OneWay}" Value="nRoute">

   2:     <nBehaviors:SetPropertyAction PropertyName="Foreground" Value="#FFFF0000"/>

   3: </nTriggers:ValueMatchTrigger>

Note, by default in Blend the Value property wouldn't be editable, in that case you might have to append it via xaml directly - I hope to create Blend designer extension soon to rectify this.

ValueNullTrigger

This is similar to the ValueMatchTrigger in that it exclusively looks to match the source value to a null. You can also negate this, so that it matches a non-null value. This is really useful when tracking asynchronously loaded data, for example when loaded items list in not null, we could visually effect the UI to indicate the availability of the data. Below is an example of this in xaml:

   1: <nTriggers:ValueNullTrigger SourceBinding="{Binding Key, Mode=OneWay}" Negate="True">

   2:     <nBehaviors:SetPropertyAction PropertyName="Foreground" Value="#FF23FF18"/>

   3: </nTriggers:ValueNullTrigger>

ValueCompareTrigger

Most data comparisons boil down to equals to, greater than, less than or their negated comparisons - and so in addition to earlier mentioned triggers, the ValueCompare trigger allows you to value comparisons with >, >=, ==, !=, <, <= equality operations. For comparison purposes it relies on source value implementing the IComparable interface or you specifying an IComparer implementation.

In the screenshot from Blend show on the right, we compare some Source Value bound from a ViewModel being greater or equal to ten - which triggers the specified trigger action. In xaml the same thing would look like:

   1: <nTriggers:ValueCompareTrigger SourceBinding="{Binding Value, Mode=OneWay}"

   2:     Equality="GreaterThanOrEquals" Value="10">

   3:     <nBehaviors:SetPropertyAction PropertyName="Foreground" Value="#FFFF4321"/>

   4: </nTriggers:ValueCompareTrigger>

ValueChangedTrigger

As the name suggest this trigger executes every time its source value changes - which at times is all you need. The xaml example below triggers an animation whenever the value changes:

   1: <nTriggers:ValueChangedTrigger SourceBinding="{Binding Key, Mode=OneWay}">

   2:     <im:ControlStoryboardAction Storyboard="{StaticResource FlashTitleStoryboard}"/>

   3: </nTriggers:ValueChangedTrigger>

ValueSwitchTrigger

Just as in procedural code the switch-cases pairing allows you selectively trigger one or more actions if the Source value matches the Case value. Have a look at a xaml example, first:

   1: <nTriggers:ValueSwitchTrigger SourceBinding="{Binding Value, Mode=OneWay}">

   2:     <nBehaviors:SetPropertyAction nTriggers:ValueSwitchTrigger.CaseValue="1"

   3:         PropertyName="Foreground" Value="#FFFF4321"/>

   4:     <nBehaviors:SetPropertyAction  nTriggers:ValueSwitchTrigger.CaseValue="2"

   5:         PropertyName="Foreground" Value="#FF23FF18"/>

   6: </nTriggers:ValueSwitchTrigger>

KeyTrigger

The KeyTigger is not part of the value-related triggers, all the same it a very useful trigger that responds to keyboard events. Now, I understand there is already an existing KeyTrigger in Blend, but before I found it I had already created this one and I've kept it because it helps with some advance scenarios.

More or less it is all self explanatory, except you can check for more than one modifiers - so a Control+Shift+V can be checked for. Also, you can negate the result to be everything except the keystrokes you have specified, and believe me this is useful. You can also throttle the key inputs by specifying a duration within which only a single key stroke will be processed - again this really useful and recently I had a situation where the UI couldn't keep up with keystrokes so I throttled the user's input and it worked like a charm. Lastly, you can also specify the max number of key strokes past which it will disable the triggering - useful for perhaps limiting baby smash torture.

MouseWheelTrigger

The MouseWheelTrigger is not like a scrolling solution, it is a trigger which fires when the MouseWheel turns and you can then use it to invoke an action such as scrolling or index change. Also it passes through a delta value, which is factored by whatever you have specified in the DeltaFactor property (the default as shown is 120). And like the KeyTrigger you can throttle the mouse wheel events by defining a time-duration to allow-in a single wheel event.

Trigger Actions

I've only included four trigger-actions in this Toolkit, yet I've found them to remarkably useful particularly because they make of the of the binding.

The first of the four triggers is SetPropertyAction, which you've seen being used above - and as the name suggests, it is used to set a property value on the applied element with a specified value. Now, there is something similar already in Blend, but herein we get the possibility to set a binded value - which opens it up to your ViewModel's usage. In the blend screen grab on the right we are setting the text property to a value from our ViewModel, when the associate trigger invokes the action. Also if you just wanted to set the value statically use the non-binding Value property.

Quite similar to the SetPropertyAction is the TargetedSetPropertyAction, using which you set value on another element (ie. the target) as opposed to the declaring element itself. For example:

   1: <i:EventTrigger EventName="Click">

   2:     <nBehaviors:TargetedSetPropertyAction TargetName="BackgroundRectangle"

   3:          PropertyName="Fill">

   4:         <nBehaviors:TargetedSetPropertyAction.Value>

   5:             <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">

   6:                 <GradientStop Color="#FFB8EBFF" Offset="0.762"/>

   7:                 <GradientStop Color="White"/>

   8:             </LinearGradientBrush>

   9:         </nBehaviors:TargetedSetPropertyAction.Value>

  10:     </nBehaviors:TargetedSetPropertyAction>                        

  11: </i:EventTrigger>

I've included four generalized behaviours, in addition to some feature specific ones, and they resolve around the idea of having an element viewable depending on the source being null or not null, or based on some true/false evaluation. This is really useful, in scenarios where you are loading data asynchronous and parts of UI are to be viewable per the availability of data.

So the first of these behaviours is called the BoolValueVisibilityBehavior, which make the targeted element visible if the given bool Value is true else the visibility is set to collapsed. You can negate this behaviour by using the negate option, like before. Similarly, the NullValueVisibilityBehavior sets the visibility to collapsed if the given value is null else it sets it to visible. This is again is negatable, and the value you evaluate against is bindable because it uses BindableBehavior<T> base class mentioned before.

For example, consider we have a search bar we don't want to show until some data is loaded into a ListBox, and so we could attach the following behaviour that tracks as to if the Items property from the ViewModel is null or not. And because we are using dependency properties we listen to data changes, so say if the data is re-loading then the toolbar will automatically hide and show-up when the data has been loaded again.

   1: <i:Interaction.Behaviors>

   2:     <nBehaviors:NullValueVisibilityBehavior ValueBinding="{Binding Items, Mode=OneWay}"/>

   3: </i:Interaction.Behaviors>

I find the above very useful, but there is a very significant side-effect to setting the visibility to collapsed in that it "shutsdown" the element from processing visual changes. And so for example, if you were to put a NullValueVisibilityBehavior onto a ListBox and wanted to have it viewable once the ItemsSource is set - the items wouldn't show up because when collapsed it wouldn't have process any UI changes - and rightly so.

Now how do deal with that, well firstly we make an element non-viewable by setting its opacity to zero. However, the ListBox could still process mouse events, which is a problem especially if it unknowingly to the user triggers some changes and yet the element is not visible to the user. The second, step to rectify this is to set its IsHitTestVisible property to false - which makes the element non-interactive and yet the UI changes will be processed underneath.

Now, by combining the two solution above I've packaged them as interactivity altering behaviours called BoolValueInteractivityBehavior and NullValueInteractivityBehavior - which like their visibility counterpart, can used to make an element non-viewable though in this case they are capable of processing UI changes. However note this is not a perfect solution, because an element could still possibly handle keyboard triggered changes, if it had the focus. Nonetheless, in a lot of scenarios this works out just fine but be careful of the caveat. And just like before, you can inverse the workings of all these behaviours by using the negate option.

IObservable-based Messaging Framework

Recently, with the Silverlight Toolkit there was a hidden gem shipped by the name of Rx Framework, which you can read about extensively here. Basically, the idea behind it is that by using the observable pattern you can do "reactive programming", kind of like event handling. But the twist is that you can turn past, current and future "observed items" into a persuado data source, which opens it using LINQ to process, shape and consume the observed data. Think event stream processing, as opposed to a pipeline model - and the items are like an IEnumerable being pushed as opposed to being pulled. I am not gonna discuss the reactive framework here, but it is really cool and you should definitely check it out if you still haven't.

In relation to the Rx Framework, what I've done is used its interpretation of the observable pattern vis-e-vie their IObservable<T> and IObserver<T>interfaces (which I understand will be part of .NET 4 and hopefully SL4) and created so-called Observable Channels - which are basically singleton implementations of the IObservable<T> to which you can subscribe and publish. With the publish subscribe capabilities, it becomes a messaging framework kind of like Prism's EventBroker, but with a very easy to use API. 

As show above the Channel<T> class is the IObservable<T> implementation, to which any implementation of IObserver<T> can subscribe. Once subscribed, we return an IDisposable implementation based on the ChannelSubscriptionBase<T> class. In simpler terms you subscribe to a channel of Type T, whereby T can be any type you want to send and receive messages for, and on subscription you get a channel subscription token onto which you can call the Dispose method to get yourself unsubscribed.

Now, also provided is a generic IObserver<T> implementation predicatively called ChannelObserver<T>, and it makes it really easy to consume any channel's incoming data, as well Subscribe and Unsubscribe as required. Below is an example, for that:

   1: // declared

   2: ChannelObserver<ApplicationStateInfo> _observer;

   3:  

   4: // subscribe

   5: _observer = new ChannelObserver<ApplicationStateInfo>((s) => DoSomething(s.CurrentState));

   6: _observer.Subscribe(ThreadOption.UIThread);

   7:  

   8: // unsubscribe

   9: _observer.Unsubscribe();

Here we are tunning into the "ApplicationStateInfo" channel, which is one of the build in channel used by the Resource Locator Framework. It basically, publishes application lifetime state changes - which include starting, started, exiting, and exited states (this is based on IApplicationLifetimeAware callings). Note to subscribe one has to explicitly call for it, as shown in line 6, and the option we are excising there is to receive the subscription on the UI thread. Similarly to unsubscribe you need to call the Unsubscribe method and you can also check if you are currently subscribed via the IsSubscribed property. Further, once you have unsubscribed you can subscribe again, which makes it really easy to play/pause a subscription using the ChannelObserver.

By default, subscriptions are weakly referenced - which means that even if a subscriber that goes out-of-scope, were not to unsubscribe, it would still be available for GC (though you should always unsubscribe). On the flip side, if you wanted to ensure a non-weak referenced connection, for performance reasons or otherwise you could choose an option during subscription to keep the subscriber strongly-referenced.  Just as in Prism's Event Broker (whose API I've mimicked), you can subscribe to on the UI Thread, on the Publisher's Thread, or in a Background Thread. Also you have the option to publish asynchronously, however in this case you need to ensure the subscribers don't run into cross-threading exceptions. And keep in mind that, by design, a Channel always throw back any exception raised by a subscriber whilst receiving a payload.

Publishing to a channel is very straightforward, just use either the Channel or Channel<T> class to publish, there are also non-generic overloads available for publishing. Below is a straightforward example, of publishing a SearchQuery:

   1: // to publish a search query

   2: Channel.Publish<SearchQueryInfo>(new SearchQueryInfo("Silverlight"));

   3:  

   4: // to publish async search query

   5: Channel.PublishAsync<SearchQueryInfo>(new SearchQueryInfo("Silverlight"));

Also included is a trigger action which allows publishing to a channel directly from the UI. Because the ChannelPublishAction can bind the payload from the ViewModel, you could rig say a button 'click' to trigger the publishing. Also it can determine the channel by the type of payload set, however in cases it is expected to be null or based on derived types, you must set the ChannelType explicitly.

Coming back to the Rx Framework, because the channels are basically an IObservable implementation they are open to party on the IObservable-related LINQ operators available in the Rx Framework. And this is big deal, because you do a lot of intelligent processing on the client side (and I will try and show this separately with a post). However note, the current build doesn't take a dependency on the Rx Framework, but a separately compiled version is available if you require.

Resource Locator Framework

The Resource Locator (RL) is basically a thread-safe register of resource locators, and a resource locator is an implementation of the IResourceLocator interface, which identifies any given resource by a unique name and can return an instance of that resource (see the interface on the right).

This really is not far off from IoC components, but the idea here is that any type of resource can register its own locator. And the locator's resource materialization strategy is its own business, and so when the RL is asked for a resource, it delegates to the locator. The core of this is really very simple, but around the resource registry are a number of utilities that really make it's consumption seamless and almost transparent from direct use. 

The RL is actually a generalization of what was there in the first drop of nRoute; in fact I had two separate implementations one for navigation and one for actions that did the same thing but in a more specific manner. If you have used nRoute you will know things like the MapNavigationContent, MapActionHandler attributes that when used with MapAssemblyRoutes or MapLoadedAssembliesActions static methods located all resources and fed them into the routing engine as routes. Here with the RL, we generalized that to not just produce routes (which themselves are actually locators in a way) but return IResourceLocator which is independent of any particular use.

Now the question is how do we feed locators into the RL registry, we could do it manually one by one, through a configuration file, or we could do using my preferred way by the means of an Assembly Mapper. The mapper basically looks for all MapResourceAttribute derivates in any given assembly, and yields an IResourceLocator implementation, which is then registered automatically.

Well, we have five feature implementations in the toolkit that make use of the RL, lets have a look at them individually.

Modules

The modules concept is straight out of Prism, but herein we use the RL with attribute-based mappings to locate and instantiate a module. For example:

   1: [MapModule("ContactsModule")]

   2: public class ContactsModule : IModule

   3: {

   4:     // .. implementation 

   5: }

Thanks to the RL, there is nothing much to the Modules concept, and the only important class is the IResourceLocator implementation which is registered into the RL by the MapModule attribute. And the ModuleLocator static class is just a candy wrapper around the ResourceLocator static class, but specifically geared for Modules-related info. Also by overriding the DefaultModulesLocator and MapModuleAttribute implementations you can add more features or change the internal workings to your requirements.

Services 

Again akin to Prism, services are essentially an implementation of some service contract (defined as an interface) which can then be located and realized.

   1: [MapService(typeof(IDateService))]

   2: public class DateService : IDateService

   3: {

   4:     // implementation of IDateService

   5: }

Here in Line 1, we are registering a Service of type IDateService which here is implemented by the DateService class - note the mapped class must implement that identified service contract. Now there are two more optional parameters to that attribute, which let you specify a name for the service, another one lets your list an array of other service types that the is dependent on. Also, you have three more named parameters, using which you can specify the lifetime of the service (see the InstanceLifetime Enum), initialization mode (see the InitializationMode Enum), and a boolean value specifying as to if it is the "default" service.

Like with the ModulesLocator static class, we also have a wrapper class for Services which helps with getting/checking for services. Also with services, actually with all types of resources, there is a concept of having a default resource - which is either a specifically designated resource (see the SetDefaultService<T> method above) or by default the first registered resource is considered the default service. So in the case of a default service, it can be retrieved without having to specify a name. So for example:

   1: // get the default service

   2: _dateTimeService1 = ServiceLocator.GetService<IDateTimeService>();

   3: // get a named service

   4: _dateTimeService2 = ServiceLocator.GetService<IDateTimeService>("GMT");

If you said this is just about like using any IoC component out there, well, I would agree with your - and feature-wise this implementation is not even that sophisticated. However the services as a concept has a lot of semantic value, which in this context is a non-visual building block for your application. Nonetheless if you wanted more smarts, you could "smartern" the locators up by creating a custom IResourceLocator implementation that uses an IoC component under the hood.

View Models

In the earlier release of nRoute we had this unfortunately named MapViewModelViewNavigation attribute, using which you could specify the View type, the ViewModel type and a Url to go with that - and what it did was when the Url was requested it instantiated the View in a Navigation Container, then create the ViewModel, which it injected into the View as its DataContext. Here with the toolkit, we don't have the composition capabilities of the nRoute Navigation component, but we have resource locators that can inject the ViewModel into a View using behaviours. Lets look at an example:

   1: [MapViewModel(typeof(Page4))]

   2: public class Page4ViewModel : ViewModelBase

   3: {

   4:     //..

   5: }

   6:  

   7: // OR - choose either way

   8:  

   9: [MapView(typeof(Page4ViewModel))]

  10: public class Page4 : UserControl

  11: {

  12:     //..

  13: }

Above we are defining the association between a View and a ViewModel, you could choose either of the two mapping mechanisms - either map the View and specify the ViewModel type or map the ViewModel and specify the View type. Once we have that all you need to do is drop the "BridgeViewModelBehavior" on the View's (at the root level).

This behaviour uses the RL to locate and instantiate a ViewModel instance and then injects it into the View's DataContext. Further, as you can see on the right, we can even bind some commands to the View's lifetime events - specifically for initialization, loading and unloading. Each command can pass in a parameter, and that too is bindable. Unfortunately, the unloading command was not firing so I've disabled it for now - it seems that the OnDetaching method on the behaviour is not being called.

We also a have specialized ViewModelLocator, if you like to use it procedurally. 

Also in the nRoute.ViewModels namespace you will also find a ViewModelBase class, which just implements the INotifyPropertyChanged interface and provides an helper to notify property changes. Note, its use is not required.

View Services

The idea of the ViewServices is that the ViewModel shouldn't have to take dependency on visually implemented controls or on platform specific contraptions - think notification balloons, save file dialog, etc. In practical terms, these are exposed just like services, where we have an interface defining the contact and an implementation that is transparent from its consumption. Now, build into the toolkit are four such services for opening files, saving files, showing messages and showing exceptions.
 

To call upon any ViewService you can make use of the ViewServiceLocator static class, which just like the ServiceLocator requires the type of ViewService and optionally a name.

   1: IShowMessageViewService _messageBoxService;

   2:        

   3: // setup 

   4: _messageBoxService = ViewServiceLocator.GetViewService<IShowMessageViewService>();

   5: _messageBoxService.ButtonSetup = MessageBoxButton.OKCancel;

   6: _messageBoxService.Text = "Please confirm?";

   7:  

   8: // use 

   9: var _result = _messageBoxService.ShowMessage();

And similarly, declaring a ViewService is very much like everything else.

   1: [MapViewService(typeof(IShowMessageViewService), IsDefault=true)]

   2: public class NewShowMessageViewService

   3:    : IShowMessageViewService

   4: {

   5:     // IShowMessageViewService Implementation

   6: }

The MapViewService attribute requires that you specify the type of ViewService you implementing and optionally it can take in a name, you can also configure the lifetime and the initialization mode - very much like Services. Also you get a ViewSerivceLocator static class that helps you consume ViewServices.

Now, ViewServices are different from plain-jo services in two ways, one, it is semantically designated for View related functionality whereas ordinary Services, like with Prism, are more back-end providers. The second difference is a more practical one, you could define a ViewService directly within a UIElement or UserControl implementation - and this can then be the located by scanning the VisualTree. If you look at the ViewServiceLifetime enumeration, we have a DiscoveredInstance option which works by looking for the first instance of the ViewService in the VisualTree. Another, similar option is the SelfRegisteredInstance, wherein a UIElement or UserControl declares that it's a ViewService but will will self-register it's instance through the ViewServiceLocator when it is realized in the VisualTree.

In some ways if you look at Child Windows or MessageBox or File Dialogs they are like non-integrated visuals - they are not in the VisualTree per se, whereas if you have a status bar within the main UI  that can be called an integrated-visual. So the Discovered and Self-Registering instances option is to support these kind of integrated visuals, whose life-time you do not control directly, but yet they need to be addressable directly from some Service or ViewModel.

Consider, if we have a background-running "Stocks Watch Service" which finds-some abnormalities with your preferred stock, and it want to notify you - what does it do? Well, you could give it a ViewService contract, by which it can notify the user. This idea can be used further to componentized your visuals and avail them for without creating UI dependencies, so for example you could create a Bookmarks Panel ViewService, or Logged In/Logged Out controlling ViewService.

I am not sure if this is very clear, but I will provide some samples showing how this can help to expose and consume visual components in a non-visual manner.

Channel Observers

Earlier I had shown an in-built IObserver<T> implementation, which really makes it easy to listen to any channel without having to implement the IObserver<T> interface; however in some cases you might want a dedicated listener - for example, a logging observer. In these cases you can implement the IObserver<T> interface onto a class and we can register and avail it though the RL. For that, we could do something like:

   1: [MapChannelObserver(typeof(ApplicationStateInfo), 

   2:     InitializationMode=InitializationMode.WhenAvaliable,

   3:     Lifetime=InstanceLifetime.Singleton)]

   4: public class ApplicationStateObserver : IObserver<ApplicationStateInfo>

   5: {

   6:     // IObserver<ApplicationStateInfo> Implementation

   7: }

Here we are mapping the ApplicationStateObserver class as an observer for the AppicationStateInfo Channel, we have set it to be realized as a singleton instance as soon as it is registered into the RL. Also when mapping you have the option to have it listen on a particular thread, see the ThredOption enumeration. Further, you can rely on the RL to instantiate the observer very early in the application lifetime, even before the RootVisual is created. 

And like before, we also have a static ChannelObserverLocator, using which you can locate your registered observers - though I am not sure how useful it is. Also, the IObserver<T> interface has three methods, the OnNext method is used to receive the channel payload, however the OnComplete is never called because a channel remains open for the lifetime of the application and I see no point executing the OnCompleted when the application is about existing. Lastly, the OnError method of the interface is also effectively not called because a Channel which implements the IObservable doesn't have the context of the publisher to generate an error - though I am mulling over the idea that any publisher can also publish an error. However, for now, just keep in mind that the workings of the channel-based messaging might change as my think evolves - and if you have any input on this, do share.

Locating Resources

One of the things with Resource Locator and it's preferred mechanism of using attributes to map resources, is that an assembly is the working currency - and indeed you could load an assembly and feed it to the AssemblyMapper static class to have any and all resources mapped. To aid this scenario, there is a RemoteResourceLoader class which helps you point to any url and load either a single dll or a xap file - in the later case it reads the xap's manifest and maps all included dlls. Here's how you can use it:

   1: // to load a dll

   2: var _loader1 = new RemoteResourceLoader();

   3: _loader1.AssemblyLoadComplete += Loader1_AssemblyLoadComplete;

   4: _loader1.LoadAssembly(new Uri("DynamicallyLoaded.dll", UriKind.Relative));

   5:  

   6: // to load a xap

   7: var _loader2 = new RemoteResourceLoader();

   8: _loader2.PackageLoadComplete += Loader2_PackageLoadComplete;

   9: _loader2.LoadPackage(new Uri("DynamicallyLoaded.xap", UriKind.Relative));

It really is very simple, and in the Assembly/Package LoadCompleted event you don't need to do anything to map the assemblies that is done for you once they are loaded, but if it was an error you will need to respond to it appropriately. Also the RemoteResourceLoader class has two static methods to check if any Uri is or has been used to load either a xap or dll.

In the attribute based mapping examples you have seen above, you have to tack the attribute on the mapped target - for example the MapModule attribute has to be tacked onto the IModule implementing type - however, this might not be possible sometimes or it may not gel with your preferences. So with toolkit there is another solution to this, a rather clean one, which allows you to "define", as oppose to "map", your resources. Have a look:

Here I created an empty cs fil, and added these assembly-level attributes - for all functional purposes, these attributes are the equivalent of the MapXX attributes described earlier. It works just as before, however when using the define version you need to specify the mapping target - for example with the DefineModule attribute you you have to specify the implementing type in addition to the name of the Module. Beyond the mater of personal tastes, the main benefit here is that rather than having mappings sprinkled all over the project, they located are in this one single location whilst still being strongly-typed. Also I hope the "Define" prefix as opposed to "Map" makes the intent clear here.

Quite obviously, the Resource Locator doesn't start by itself - you have to make it start and the recommended way to do that is to instantiate an nRouteApplicationService class into the Application's ApplicationLifetimeObjects collection.This can be simply done in your app.xaml file like this:

   1: <!-- declare the xml namespace -->

   2: xmlns:nRoute="clr-namespace:nRoute.ApplicationServices;assembly=nRoute.Toolkit"

   3:     

   4: <!-- and add it your application's LifetimeObjects collection -->

   5: <Application.ApplicationLifetimeObjects>

   6:     <nRoute:nRouteApplicationService />

   7: </Application.ApplicationLifetimeObjects>

A lot of the work I've been doing lately with .NET eventing and stuff comes down to the concept of resource-management - like how do we manage our resources' lifecycles without causing unintended negatives (like memory-leaks or performance issues). On the face of it resource-management is a problem of pluses and minuses, creating and releasing resources per their need - but the fact is, with frameworks like .NET there is so much resources creation and disposing going-on that we figuratively end up managing needles above a haystack.

The Idea: Take'em down with me

More to the point, I have this idea of managing the disposing of resources by creating a persuado supporter-dependent hierarchy of resources - sounds fancy but it is really simple. And the other part of the equation is having an API that isn't too intrusive - this is quite important to me, as I think with tiresome APIs the usefulness whether-away like a new-year's resolution.

In practical terms the disposing of resources is based around this single interface, called IDisposeRelated - which has the following make-up:

   1: public interface IDisposeRelated

   2: {

   3:     event EventHandler DisposeRelated;

   4: }

Basically, you introduce this interface on any object that wants to limit the lifespan of one or more dependent resources to no more than its own - so good candidates include user controls object or event handlers. For example we could, append the IDisposeRelated interface as such:

   1: public partial class Window1 : UserControl, IDisposeRelated   

   2: {   

   3:     public event EventHandler DisposeRelated;    // IDisposeRelated Members

   4:  

   5:     public Window1()   

   6:     {   

   7:         InitializeComponent();

   8:         this.Closing += (s, e) => 

   9:            {if (this.DisposeRelated != null) DisposeRelated(this, EventArgs.Empty);};

  10:     }

  11: }

All we are saying here is that when closing the user control raise the DisposeRelated event, indicating that you want dependent resources to be brought-down too. Do note, I don't use the word "dispose" in the strict sense as with the IDisposable interface, which relates it to releasing unmanaged resources.

Dependent Resources: Proactively com'n down

Once we have the IDisposeRelated resource defined, we indicate the dependency using (mainly) extension methods - consider two examples:

   1: this.Writer = new StreamWriter(_filePath).DisposeWith(this);

   2: // or

   3: ParentWindow.LostFocus += 

   4:     new RoutedEventHandler(ParentWindow_LostFocus).DisposeWith(this);

In line1 we are creating a new stream writer, to which we append the "DisposeWith" extension method to indicate that it should be disposed off when disposing "this". And "this" would/could be any object supporting the IDisposeRelated interface - so in other words, because the IDisposeRelated interface indicates as to when it wants to dispose related resources, we listen to that and take down any earmarked resources with it. And that's it.

The Take Down

Now, when I say "take-down" resources - the garbage collector would stare blankly first, but basically we know how to do certain stuff like with IDisposable objects we will call the Dispose method or with event handlers we can unregister it. For other stuff or when you want more control you can use another DisposeWith extension method definition that takes an action delegate (with the target passed in) to effect the "take-down" as you specify. For example:

   1: var _cache = new MemoryCache().DisposeWith(this, (c) => c.Clear());

In the case of the cache object above, the "take-down" concept in its context would mean clearing whatever is in the memory. The point being, if we can proactively add this instruction of how to redeem resources whilst creation (though you could still add these instructions later) we won't loose the proverbial needle in the haystack. Further, by earmarking resources by the "dispose with" instruction, we create this persuado supporter-dependent hierarchy.

Technically Speaking

Having specified "dispose with" for an object does not preclude you from disposing it earlier - just later if it hasn't been disposed then it will do it for you. Secondly, the "dispose with" instruction only holds a weak reference to its target, and so it doesn't itself become a memory leak source. Also, you could possibly have more than "dispose with" instructions against a resource and it will be fulfilled in a first-come first-serve basis. Further, the dispose with thing doesn't have to be based on a resource's parent's lifecycle, it could be based on a peer object or on some other domain context - which is why I said a persuado supporter-dependent relationship and not a parent-child one.

Performance-wise, I've not checked because I am still mulling over the validity of the idea. But, I don't think it would be too great of hit, because my current implementation is basically adding a weak handler against the "DisposeRelated" event. All the same, there are other ways to implement the same functionality, so we'll see about the performance.

This current implementation is very basic, possibly in the future, if it is worthy, we could add fancy features like LINQ based dependency evaluation or lazily attach it with a control's lifecycle. For now, it is something simple I am trying in my code, but like in a lot of cases ideas as these comes down to the usefulness v/s inconvenience of the feature.

Above is a simple Silverlight 3 application that demonstrates the usefulness of weak events in avoiding memory-leak issues. To demonstrate, I've made use of weak event handler wrappers I introduced in my previous post (the code can also found there). The application itself is very simple, it shows the current memory consumption, allows creation of two types of child windows and enables garbage collection on demand. The two types of child windows by design consume more than a million bytes of memory each (per instance), and both windows basically link up with the root visual's size changed event - with a call like:

   1: // Normal Child Window

   2: ((MainPage)App.Current.RootVisual).SizeChanged +=

   3:         new SizeChangedEventHandler(WeakEventChildWindow_SizeChanged);

However the Weak Event Child Window, makes the following call:

   1: // Weak Event Child Window

   2: ((MainPage)App.Current.RootVisual).SizeChanged +=

   3:       new WeakHandler<SizeChangedEventArgs, SizeChangedEventHandler>(WeakEventChildWindow_SizeChanged);

And that's the only difference between the two. Also, neither of the two handlers are unregistered on closing of the child windows (as they should). But with the weak event window, the memory is reclaimed back when the window is closed (to try open some weak event windows and then give the collect garbage hyperlink couple of clicks), whereas each and every instance of the normal window would persist in the memory until the application is closed/unloaded. The weak event child window can get by, because the event handler doesn't store a strong reference to the child window, rather it holds a weak reference which disconnects the child window's lifetime from the event sources.

Now, even though this a very contrived/simple example, it does show how a casual use of a handler can cause serious memory leaks issues (especially when they are spread out all over the place, with small amounts of leaks). On the flip side, the basic principle for correcting this is that if your event source is going to outlast the event listener's life span, then make sure the event handling is disposable/disposed with the listener closing.

As part of the next drop of nRoute, I've been doing some work around events and listeners in .NET - the main issues have been around memory-leaks, selectively multi-casting events, performance and loose-coupling. Certainly, this is not something new and there are a number of solutions out there, but usability and performance have been the compromises which was something I wanted to avoid.

The Idea : Wrap'em

From my work on it, I take that we don't want the semantics of exposing and using events to change - so basically the the producer and consumer syntax should remains the same, however if the producers and consumers are dumb about it, I suppose we should make the messenger smarter. So here is what I'm mean:

   1: source.SomethingHappened += new WeakHandler((s, e)=>{ . });  

   2: //or 

   3: source.SomethingHappened += new WeakHandler(Handle_Something);  // delegates to a method

On the left the source exposes a "SomethingHappened" event using the EventHandler delegate, and on the right we have a custom class that handles the event - the use API is actually not far off from where we are today. We just changed the normal handlers with the "WeakHandler" class that wraps (not inherits) the actual handler and introduces the logic for weak delegation. In my solution I make use of closures and lifting .NET features to create "self-referencing" event-handler that are aware of their wrappers. It's not that hard, however the benefit is that we can make it do smart things such as respond to say a specific property change on a PropertyChanged event, consider:

   1: source.PropertyChanged += new WeakPropertyChangedHandler( 

   2:    ()=> SelectedItem,  

   3:    SelectedItem_PropertyChanged);

In this case the 'SelectedItem_PropertyChanged' method will only be called when the 'SelectedItem' property changes. And the best part is the listener or consumer is weakly referenced, so it can be available for garbage collection when it has no outstanding references (without having to remove the event handler itself). And if the listener has been disposed off, the handler will de-register itself and dispose off.

The Implementation

Like I said the event handling classes above, like WeakPropertyChangedHandler, are basically wrappers around the actual event handlers - however note, we don't need to create specific event handlers for each and every event type. We have a generic definition that can that can handle every type of event; its constructor signature is a follows:

   1: public class Handler<E, H> 

   2:        where E : EventArgs 

   3: { 

   4:     public Handler(Func<Action<Object, E>, H> createAction, Action<Object, E> action, 

   5:                 Action<H> removeAction) { .. } 

   6: }

The H type is supposed to be your handler type which unfortunately cannot be constrained. All the same, just like every event handler we need to be able to do four things, namely create the handler, attach the handler, handle the event and remove the handler. Now, if you look at the constructor we don't do the attaching part, that's up to the user but for the rest we take in delegates - so a full blown handler can be written as:

   1: Application.Current.MainWindow.SizeChanged += 

   2:     new Handler<SizeChangedEventArgs, SizeChangedEventHandler>( 

   3:     (a) => new SizeChangedEventHandler(a),    // How to create 

   4:     (s, e) => Console.WriteLine("Main Window Size Changed."),  // How to handle 

   5:     (h) => Application.Current.MainWindow.SizeChanged -= h);  // How to remove

I know that is somewhat verbose, however that's the full monty, whereas you have more specific implementations and additional constructors that can do the creation and removing part for you. The other important thing to realize is that the Handle<E,H> type can be paraded around as a named variable, consider:

   1: var _handler = new RoutedHandler((s, e) => MessageBox.Show("GotFocus"));

   2: this.GotFocus += _handler;

   3: // when done

   4: _handler.UnregisterHandler();

Here we create the handler variable, which when done can be specifically called to unregister. I specifically designed this  to call an unregister method rather than have to -= the handler.

The Variants

As you can probably tell we have many different types of handlers, which can generally be qualified into three separate categories (see below). First, we have types deriving from Handler<E,H>, which are basically like normal events wrappers that hold a direct reference to the event listener and have to be manually unregistered. The second category is based on the SingleHandler<E,H> type that only handle the first call and then recuses itself - which might seem strange, but actually they are very useful in handling things like Loaded, Initialized, Errors related events. They save memory, plus ensure you don't end up holding unnecessary references. Lastly, we have the WeakHandler<E,H>based types, which as the name suggests holds a weak reference to the listener and allow for its disposing independent of the event source. Also note, WeakHandler types also allow you to manually call the UnregisterHandler method to discontinue the event handling.

As shown above, based on the three categories of handler wrappers we have specific types that handle EventHandler<E>, EventHandler, RoutedEventHandler and PropertyChangedEventHandler types of event delegates. They just allow for an easier to use API, however you could resort to the generic types if you wanted too.

Performance

Given the use syntax is very similar to the normal event handlers, the other important use tenant for me is the performance. Lets see how it fares (time in seconds):

Based on the table, the performance of the wrapped handlers have a disadvantage ranging from 1.5x-15x, primarily on the event raising front. Attaching is notably slower, however unless you are doing very processer intensive stuff, I think for most part these are within the range of "acceptable costs", especially for client-side apps like with Silverlight. Also, there are further optimizations to be had, as this is quite early stuff.

Listeners

Now if you like what you have seen, it gets better. Given some of the problems with eventing as it stands, the WPF team rolled out their own implementation based on the Weak Event Pattern. They essentially provided an event manager, a custom event definition wrapper, and a relative simple consumption interface - which all somewhat works like normal events. The consumption interface called IWeakEventListner has the following signature:

   1: public interface IWeakEventListener

   2: {

   3:     bool ReceiveWeakEvent(Type managerType, object sender, EventArgs e);

   4: }

The weak event pattern is performant, but the provider side requirements of obscure per-event setup, registration and the middle men solution are all a bit clumsy. So how about if we could attach IWeakEventListner implementation to normal event handler defined events, something like this:

   1: source.SomethingHappened += new WeakListener(weakEventListnerObj);

   2: // or 

   3: source.PropertyChanged += new WeakPropertyChangedListnerHandler(

   4:     () => Items,

   5:     weakEventListnerObj);

Based on the figures above the build in handlers still have a distinct advantage, however it is less pronounced. And again from my perspective, the costs of using listeners with events are nominal. And, with respect to handlers performance listed earlier, listeners fare much better considering the conversions between delegate to interface based handling.

There is More

• Possibly, implement IDisposable on all the handlers, not for reclaiming unmanaged resources use but more for user's remember-to-dispose considerations. I'm still thinking about this
• Introducing -= operator, I personally prefer the use of the UnregisterHandler method
• Introducing a common base class, with overridable methods
• Because I'ved used a lot of lambda statements, I want to see if there is a way to increase performance. Also if I understand correctly in .NET 4 lambda statements can be compiled (as opposed to only expressions right now), which should help with performance
• I also want to further squeeze performance out of the Weak handlers, I've used a number of techniques to ensure through-and-through performance, but I still think there might be better ways. I am looking at late-bound expression trees to see if they can help, if you know of any better way please let me know
• I'm also looking for alternative and strongly-typed ways to create and remove handlers. What I have currently, it's quite performant but there might be a better way
• Also I think with .NET 4.0's dynamic types we might be able to hopefully get some improvement in performance, especially since we will be able to rigorously match event defined signature with delegates
• For Silverlight, there is an access limitation to only being able to call public methods and not private ones - I want to if there is an alternative to that (note this only effects the Weak Handlers types). If you know of any alternatives, do let me know

The code is attached below, it references the "WindowsBase" dll for the IWeakEventListener interface - but if you want to use this in non-WPF environments then just expose the interface and remove the RoutedHandlers related classes. Similarly, for use in Silverlight, just link/add the code to a Silverlight project and it should compile as is. 

Download Code (updated for Silverlight use)

Update: I re-did all the performance tests because they were highly skewed in favour of listeners - because earlier the handlers did not do any work. The new figures, better represent real-usage and reflect the expected costs of wrapping event handlers.

Lately, its been raining M-V-VM (Model-View-ViewModel) in the SL and WPF world, and rightfully so because M-V-VM to me is the best pattern for application-development given the features in SL and WPF. Now, in this post I'm not going to introduce or detail the pattern itself, read this article by Josh Smith for a great intro, rather I'll go over what nRoute (download here) brings to the party as far as M-V-VM is concerned. And this is significant because nRoute was specifically, but not exclusively, designed for use with M-V-VM.

Separation of Concerns

From a larger perspective, M-V-VM is based on a simple principle of "separation of concerns" - in this case between the consumable View and the View's State and Behaviour which is represented by the ViewModel. However, it is important to appreciate that the ViewModel is not a dumb conductor, rather it is a contextually and state-fully rich orchestrator (which inturn makes the View as "logic-free" as possible). This separation also plays into enhancing the Developer-Designer workflow Microsoft has been touting for sometime.

Further, in my previous post about the demo app I explicitly tried to highlight how nRoute helps in another type of separation of concerns - between the infrastructure faculties and the actual actionable/usable content. Using Urls as a abstraction over content, nRoute dynamically binds together the infrastructure and content into a consumable application. The critical benefit being that infrastructure and the usable/actionable content can be clinically separated and evolved independently of each other.

This whole range of separation of concerns, with the traditional n-tier and domain-model helps create a flexible application and infrastructure - perhaps more complex, but one that will stand the stress-of-change much better.

Mediator

Central to nRoute is the routing engine, which is a direct port of the engine found in ASP.NET 3.5sp1 or MVC. It plays the role of a mediator that uniquely identifies resources using Urls, which are used for both composition and navigation purposes. In addition to a "resource locator" role the mediator also has another important role, which is that it allows for loosely-coupled dependencies amongst resources. When I say dependencies amongst, it can either be of composition nature like parent-child windows, or it can be of linkage nature like in wizards screens - both of which are discussed below. Also appreciate that because the mediator in nRoute uses string based Urls to resolve dependencies, your resources can evolve independently of each other akin to say HTML pages on a Web server.

Often people find the use of strings as locators a bit too loose of an abstraction, however Urls in nRoute are not magic-strings rather they have to be formally registered and properly formatted too. And equally the fact is that Urls are perhaps the most successful and all-encompassing form of resource locators in use. Further like MVC et al., Urls in nRoute support tokenised fragments which makes for even easier and broader use semantics.

Composition

Increasingly the metaphor of a "Window" is taking a back seat to the metaphor of a "Page", because with the success of the Web-Page model the window metaphor easily breakdowns in the face of web-like fluent user experiences. And though, it is not technically hard to achieve composition in its simplest form, what has historically hurt is the lack of a proper/built-in composition model. Further the complexity and clumsiness of solutions like Regions in Prism or WPF Frames hasn't helped, that is without even considering the locator, state-management, and navigation type issues the page metaphor brings.

And in this scenario, nRoute really shines because it brings a simple and well-understood model for composition using Urls, along with inherent support for state management and navigation features. The composition model in nRoute is akin to IFrames in HTML, and as suggested it makes use of so-called "container controls" (or simply containers) which by design exhibit different state-management behaviours (like Back-Forward History). Build into nRoute are four such container, plus the container model is fully customizable/extensible to accommodate custom needs. Now, what is profound here is that your content doesn't need to be aware of the container or vice-versa, because nRoute makes the composition magic happen without direct dependencies.

Further, like HTML pages/IFrames you can have one container within another, which allows for Master Pages or Parent-Child Pages type of use models. Alternatively, you can place two or more containers next to each other (each container individually addressable) to get something like the antiquated FRAMES model in HTML. In all, with the composition model in nRoute gives you a boat-load of flexibility coupled with a high degree of loose-coupling between the infrastructure and the content.

Navigation

With composition, navigation has always been the bane - but by using Urls it becomes both simple and easy to effect. Further, nRoute features an extensive range of behaviours that extend navigation to almost all control's common events, and accompanying that is a simple NavigationServices API. And depending on your preferences you can either drive the application-flow via code in the ViewModel or in the xaml based View. Additionally also supported is a concept-of an application-wide default container for navigation purposes, which comes into play in deep-linking scenarios.

State-Management

Interlinked to navigation is state-management, which in nRoute is an opt-in feature driven by a simple interface called ISupportNavigation. Within a M-V-VM archetype, you can implement the said interface in the ViewModel, and equally use it for both saving and restoring state independent of the View. Furthermore, the ISupportNavigation interface helps formalize the passing of tokenized parameters (and optionally a name-value collection) in the course of navigation. The benefit of state-management vis-a-vis navigation is that the lifetime of any View is limited to it being active in a container - however the content state can be persisted independent of the View.

Commands

Because of the nature of M-V-VM separation of concerns, the command-model gains added prominence in achieving the View and the ViewModel interaction pattern. And nRoute features first-rate support for both creating and consuming ICommands - it has an expansive implementation of non-routed Commands and behaviours to enable its consumption. The ICommand implementations which I blogged about earlier, features a strongly-typed parameter, INotifyPropertyChanged notifications, enabling/disabling the command, and a bindable command parameter property. Further, like in the case of navigation, nRoute features an exhaustive range of behaviours for consuming ICommands, which can respond to almost every control's common events.

Actions

Actions in nRoute are Url addressable functionality, that execute off the UI thread - this is useful for things like triggering some downloads or enabling pub-sub type of communications. The model for constructing actions is relatively simple, it is based on an interface called IActionHandler and the consumption pattern like earlier is based on attachable behaviours or alternatively by the use of the ActionServices API.  Further Actions support multi-casting to one or more globally registered handlers, and because of the loose-coupling it's a form of Weak Eventing using Urls. Also, you can direct an Action request to a specified handler which can be real handy sometimes, as described below.

In a way you can think of Actions in nRoute as mediated ICommands that can be addressed, in a loosely-coupled fashion, via Urls. And like ICommands, you can expose Actions in your ViewModel using a Delegate-Command type property (see the DelegateAction type), and on the View side you equally could bind to the Action property for use with behaviours. Further, like navigation Urls the actionable Urls also supports tokenized Url fragments and additively a request can be furnished with a name-value collection parameter for greater flexibility.

ViewModel Injection

One of the obvious to-dos with M-V-VM is injecting the ViewModel into the View - and because in nRoute the Views are instantiated by the mediator it gives us the perfect opportunity and place to inject the ViewModel. There is a build-in attribute-based approach to this, which uses the wordy MapViewModelViewNavigation attribute to set the ViewModel as the DataContext of the View. However, you are not constrained to use this attribute, you could easily create your own attribute-based implementation that say uses a service locator to determine and inject the ViewModel. Further, if you know MVC then you'll appreciate how much can be done by creating a custom IRouteHandler, and in nRoute using the IRouteHandler extension point you could totally lay out a custom M-V-VM implementation atop nRoute.

Service Locators

One of the common tripping points with M-V-VM is the use of platform specific and/or task specific functionality like MessageBox or File Dialogs in the ViewModel. The solution for the same is wrapping the functionality in a platform/task agnostic way into a locatable service; however this begins to creep mightily into the territory of Service Locators such as Unity or NInject, which makes me rather uncomfortable. So, I am considering having a set of M-V-VM helper services that optionally plug-into your chosen implementation of a Service Locator (reverse Dependency Injection?).

Forthcoming Additions

In addition to the helper Services, a number of forthcoming features in nRoute will directly help with M-V-VM. Firstly, as described in my earlier post, we'll have strongly-typed INotifyPropertyChanged support using extension methods. Also introduced will be bindable data-triggers for SL, which can be used to trigger either Navigation, ICommands or Actions. And probably something like an Action that yields a response, with the response being consumable in the View. 

In summary, I hope what is observable through the list of features mentioned above, is that nRoute is acutely geared towards realizing M-V-VM type of applications - ensuing a range of benefits probably described elsewhere.

My previous post detailed the Navigation Services infrastructure, in this post I will get into the Action Services Infrastructure. The Action Services also build above the Routing Services, however it has a markedly different API. The constant is that we use Urls as the primary identifier (optionally with name-value parameters), but the action themselves are executed in fire-and-forget manner. Like before I will take on each part individually, but first below is my mind-map type class diagram for Action Services. Before we go ahead, let me point out that I've erroneously misspelt definition as "defination" as seen above - I will definitely correct that.  However, I'm quite prone to such mistakes, including all-things related to grammar, spellings, punctuation, syntax and the likes  - it's a known defect, so please do excuse me.

No Returns for a Two-Step Process

In the class diagram above you might have noticed, that we have an IUrlRequest derivate type called ActionRequest but no equivalent IUrlResponse derivative. That is because an Url based action doesn't return a value, think Action<T> delegate - even so there is nothing stopping you from relaying back a response albeit indirectly. Secondly, to get an action registered it is a two step process, one we register a route with an Url and then we register one or more handler against that route. The logic for this disconnection is that we can have zero or more handlers registered against the same route and, equally we can also unregister a handler - think Pub/Sub. The sample code below shows both the deeds:

// We need to register an action url
ActionService.MapAction("CounterAddRoute", "Counters/Add/{CounterName}");

// we can now register a handler
var _thumbsUpHandler = new ThumbsUpCounterHandler();
ActionService.RegisterHandlerByRoute("CounterAddRoute", _thumbsUpCounter);

// we register another counter
ActionService.RegisterHandlerByUrl("Counters/Add/{CounterName}", new ThumbsDownCounterHandler());

// and we can unregister a counter too
ActionService.UnRegisterHandlerByRoute("CounterAddRoute", _thumbsUpHandler);

In the snippet above, we first register an Url with a route name "CounterAddRoute", this helps us reference the route. We then create an instance of the "ThumbsUpCounterHandler" class that implements the IActionHandler interface, which we register as a handler for the route. The next statement shows how we can also register handlers against Urls just as we can against Routes - it is essentially the same thing either way. Also, as shown in the last statement we can also unregister handlers, note there is another way of doing this - which is by naming the handlers while registering so that you can unregister it by the handler name rather than the instance.

 IActionHandler

The IActionHandler interface is a contract that is used to respond to action requests. It's signature is very similar to the INavigationHandler and equally it is also very ICommands'que. Basically we check with the handler if can handle the action, if it can handle then only the handle method is invoked. The handle method also has a very simple signature, it get passed in an IActionDefination (or IActionDefinition) that contains the original request and the parsed parameters. Like everywhere else in the framework the parsed parameters are a merged name-value collection of the original request parameters, the default parameters set while defining the route, and the parsed token-parameters from the Url. And sequence for merging is such that request parameters override Url parsed parameters, which in turn override the default parameters.

One other critical thing to note is that when you register a handler you are registering an implicit singleton instance for handling all action requests, and so you have to be mindful of that in your handler's code. And if this doesn't suit you needs, just wrap it within a factory-style implementation of IActionHandler that can provision as required.

Action Request

Like I've mentioned earlier all requests constitute of two principle things, one the Url and two a name-value collection; as evident in the IUrlRequest interface below. The other member in that interface is the ServiceState property, which is supposed to be for internal use to carry service's own water.   
The one thing the ActionRequest type adds is the Dispatcher property, which is self-descriptively a type of the Dispatcher class. This is important because the ActionHandlers are executed off the UI-thread and asynchronously, and to effect any results or changes this provides the bridge back to the UI thread.

Action Route Handler

The Action Service uses a specific IRouteHandler implementation of a type named ActionRouteHandler; instances of this type are registered with the RoutingServices as the handlers for all action related routes. This is non-configurable, because this specific handler is used to maintain a collection of IActionHandler(s) registered for the particular route. You will normally not deal with this class directly, as the ActionService consumes it internally. However it is good know.

 Action Service

The Action Service wraps around the Routing Service, but unlike the Navigation Service it has a fire-and-forget type of consumption semantics. As I've said before, calling on an action doesn't return any value whatsoever, so you might have ten registered handlers for a specific action or you might have zero handlers but there are no indications about the handles count or the result as far consumer's API is concerned. Now, I've explained the two-step registration process, which separates the registration of the route/Url and adding or removing of the related IActionHandlers - think .NET events, where we have the event definition and adding/removing of the event handlers. And you can register or un-register handlers by identifying it through the route name or the mapped Url, either way. Also, you also check if an action is already registered using the IsActionUrlRegistered or IsActionRouteRegistered methods.

The Process method is the entry point to get an action executed, it has two overrides, one that uses the registered handlers and another one which can execute against a given IActionHandler instance. In the second option, only the given handler is called for and not the registered ones, however as of now this is executed synchronously but this will change in the future to an asynchronous execution model. Furthermore, the option that you can execute an action against a handler gives you an almost ICommand like capability, the difference being the loosely-coupled Url based identifier. And particularly for this scenario, you can use the ActionDelegate type which implements the IActionHandler interface which gives you a simple wrapper to use from your ViewModel (by exposing it as a property and binding within the UI). However do note, even if you use your custom handler for an action the Url must have been registered - this is by design.

Attributes Mapping

Like with the Navigation Services, we also get an extensible AOPish style functionality to auto-register actionable Urls. This functionality is accessed by the MapAssemblyActions and MapLoadedAssembliesActions methods on the ActionService class.
 
This works in a similar way to the Navigation related attributes, the ActionService when asked to auto-map actions from a given assembly it looks for the MapActionBaseAttribute type on all public types. As you can see the attribute has an Url property and resolves an IActionHandler - which are the two things required to get an action route and handler setup. It is a very simple system, and you can extend this by your custom implementation of the base attribute, to address your custom loading/mapping strategies. The other benefit of using the attributes is that it is not statically registered, rather is runtime based which you exploit to your advantage. For example, if the user is not Admin we don't load and map the actions usable only by the admin or you could load different UIs identifiable by the Url but we just exchange the assembly yet the identifiers stay the same.  Below is a simple snippet from the demo app that gets itself registered via the MapActionHandleAttribute, and is used to navigate externally.

[MapActionHandler("System/NavigateExternal/{URL}")]
public class NavigateExternalAction : IActionHandler
{

    const string URL_KEY = "URL";
    const string ORKPAD_COM = "http://www.orktane.com";
    const string NROUTE_CODEPLEX = "http://nRoute.codeplex.com";

#region IActionHandler Members

    public bool CanHandle(IActionDefination action)
    {
        return true;
    }

    public void Handle(IActionDefination action)
    {

        // we need to use the dispatcher to navigate to external addresses
        action.Request.Dispatcher.BeginInvoke(new Action(() => 
        {

            var _urlKey = action.ParsedParameters[URL_KEY].ToString();

            if (string.Equals(_urlKey, "Orkpad", StringComparison.OrdinalIgnoreCase))
                HtmlPage.Window.Navigate(new Uri(ORKPAD_COM, UriKind.Absolute));

            else if (string.Equals(_urlKey, "nRoute", StringComparison.OrdinalIgnoreCase))
                HtmlPage.Window.Navigate(new Uri(NROUTE_CODEPLEX, UriKind.Absolute));

        }));
    }

#endregion

}

This finishes another part of the laborious documentation, I have three/four more big topics to go. However, I'll take a detour to rather write up samples and a couple of quick starts on the core features. Anyhow, I hope this post underscored how the actions infrastructure in nRoute helps to further and easily "demarkify" business-functionality from the UI.

In this post, I want to describe how the Navigation Service works and how it relates to the all important INavigationHandler. To be honest, the Navigation Service is a very thin wrapper around the Routing Service; but it is semantically very important because it puts a context around the consumption of the routing responses - for navigation purposes obviously. I'll take on each part related to the Navigation functionality in a piece by piece manner, but first below is what I consider my mind-map relating to Navigation and Routing in nRoute:

Navigation Requests

Basically all requests constitute of two principle things, one the Url and two a name-value collection; and this is accordingly reflected in the IUrlRequest interface. The other member in that interface is the ServiceState property, which is supposed to be for internal use of the services to carry any service-specific data. 

Now, the only thing that the NavigationRequest type adds is the the NavigationMode property, which is an enumeration that tells the container what kind of request (back, forward etc) we are dealing with - it's usage is container specific and some containers totally ignore it. However, I made it a first level concept to enabled browser integration and minimize ambiguity. All the same, for most purposes you will only need to be concerned with the the Url alone. In fact I suggest that you should try and minimize the need for passing name-value parameters, and consider using defaults parameters if necessary. One other point, the Url that you register or use should not contain a "?" and it should not start with either "/" or "~" (these are trimmed on use, but avoid them), I've carried these requirements intact from asp.net routing specifications as it made the relative Urls sort of consistent.

Navigation Response

The navigation response is based on the IUrlResponse interface, that defines five almost self-describing properties. The important ones are Content, which holds the actual result. And the other is ResponseParameters, which is basically a merged name-value collection of the original request parameters, the default parameters set while defining the route, and the parsed token-parameters from the Url. And priority level for merging is such that request parameters override Url parsed parameters, which in turn override the default parameters.
 
The navigation response adds one things, which is the NavigationStateManager property of type ISupportNavigationState interface. The ISupportNavigationState is a mechanism to participate in state management but participation is optional, and also the reason it is separated from the actual result is to facilitate M-V-VM like pattern. So for example, the response itself can be an Usercontrol, but it doesn't have to implement the state management, whereas it's ViewModel can do that or a parent controller can do that. One last thing, the Error property only holds exceptions that are occur in the course of getting the actual response (from the IRouteHandler) and not say from an invalid Url.

IRouteHandler Implementations

You can think of the IRouteHandler as the your end of the bargain, that when posed the Url-specific request provides the response - which is basically the same in asp.net routing or MVC.  Now you can create your own handlers very easily, but I provide two build-in implementations - one specializes in loading assembly-embedded resources like images, xaml-only files, text files etc. The other, more general purpose one, takes in two delegates yielding the response and optionally an ISupportNavigationState object.   

// NavigationRouteHandler Constructor
public NavigationRouteHandler(Func<ParametersDictionary, Object> responseResolver,
           Func<Object, ISupportNavigationState> navigationStateManagerResolver) { ... }

INavigationHandler

The INavigationHandler Interface is a very simple interface, almost ICommands'que. The ValidateRequest is asked as to if the handler can process the request, if false it yields a NavigationResponse will null content and Cancelled status. The ProccessResponse, is equally simple in that it is asked to process the response. Now, the inbuilt navigation containers all use this to get the response and display it, but if you were devious enough you will know that it doesn't have to be that. You could for example use this as a signalling mechanism or even get data - and you can get even more creative if used with navigation behaviours I mentioned in my last post. However, you must be careful because the calls to the handler are all synchronous, which means you can potentially block the UI thread inappropriately.

Navigation Service

Like I said earlier the Navigation Service is a wrapper around the Routing Services, but it importantly provides the capability to inject responses into through the INavigationHandler interface. And it does use that mechanism, when you use the Navigate method that takes in a NavigationRequest and an INavigationHandler - to which it will given back the response to process. The other main method is Resolve, which takes in a NavigationRequest and gives out a NavigationResponse. That is important in a way, because it means you can get the response from without having to go through a handler. So you have two ways to get the response, but you will almost always use the Navigate method which in a manner of speaking injects the response into the passed in INavigationHandler container.

The MapRoute method provides a couple of different ways to register a Navigation Route, some of which I shown before. However, truth be told, in as far as registering routes you can totally forgo the NavigationService and register against either the RouteTable or the RoutingService itself. Lastly, the MapLoadedAssemblieRoutes and MapAssemblyRoutes methods provide support for mapping Url to content using attributes. MapLoadedAssembliesRoutes enlists all loaded assemblies and passes them to the MapAssemblyRoutes method which auto-registers navigation routes - as described next.

Attributes Mapping

In a lot of use-cases the "strong-by-convention" way of registering routes can frankly be burdensome, so I created an extensible AOPish way to auto-register Url and it's required IRouteHandler.

The shown MapNavigationBaseAttribute is the attribute the NavigationService looks for when asked to map an assembly, and then to register the navigation route it calls upon the attribute's ResolveHandler abstract method. That is very simple, but what this also means is you can create your own derived attributes to suit your loading strategy, say one that uses some kind of dependency injection tool. And the other obviously useful thing about attributes is that it is registered at runtime, so you can say load in a different assemblies on a per user basis (like don't load Admin related assemblies when the user is a not an Admin). I'll also show in another post a derived attribute that does M-V-VM automagically for you.

That's it for now, these posts are really getting long and dry - but the drudgery is necessary because these are meant to be persudo documentation for nRoute. Anyhow, I hope you have learned how the whole request in and response out thing works. I'll leave you with some immortal words from Karate Kid:

Daniel LaRusso: Hey, what kind of belt do you have?
Mr. Kesuke Miyagi: Canvas. J.C. Penny. Three ninety-eight. You like.
Daniel LaRusso: No, I meant...
Mr. Kesuke Miyagi: In Okinawa, belt mean no need rope to hold up pants.

As weird as the title sounds, I love what behaviours using attached properties bring to Silverlight and WPF. They are kind of what Javascript is to HTML elements - the wonder that extends controls beyond their limited initial intentions.

Now, with respect nRoute, what I did was map every event in almost all the controls in SL 2 base library to do three things, one navigate, two take an action and three execute an ICommand (sorry this is like a little mantra I keep repeating). The core point being, this is a very extensive body of abstraction that should help with over 75% of your UI interaction at the very least. Also, this is based on the Prism 2's behaviours' code pattern, but in their instance they were limited to Buttons - here it is starts right at the bottom from UIElement. Tabulated below are the behaviours available for events in nRoute:

Believe it or not these are almost all the events exposed by SL2 base-library controls with exception of four events (Tooltip's opened and closed events, and ComboBox's DropDownOpen and DropDownClosed events) and three other controls' (MediaScaleImage, MediaElement, and Thumb Control) events. Note, the Timeline object is a DependencyObject and not an UIElement derivative, so it exhibits a bit different usage semantics (explained ahead).

How do we use it? In Visual Studio, you import the relevant namespaces and basically attach them to what ever element you want. Below we have behaviours attached to a Button, Border, ItemsControls and it can be almost anything deriving for any of the classes listed above so thing like ListBox, CheckBoxes, Storyboard or your custom controls.

Let me explain the three behaviours attached to the buttons in the screenshot just above. In the first case we have attached a behaviour that on the click event of the button executes the NewOrderCommand. In the second example, we have an action behaviour attached to the mouse-enter event of the button, and the action is identified with the Url shown. Also the action can have zero or more handlers at the back end, which can do whatever as necessitated by the business logic. Lastly, we are attaching a behaviour that will execute if there is a binding validation error, and it will navigate to the shown Url. Now, where (as in which container) the navigation occurs is configurable, but you can say put up a side panel that could show the content from that Url.

I just want to raise this point here again, you can attach to all the listed events above and execute any of the three categories of behaviours from just about any control, including your own. If you see the code for the demo app posted, I used these behaviours and had exactly zero code-behind the xaml files (except where I had to do element to element binding or triggering property updates - both these facilities are now there in SL3). This is very significant for both M-V-VM design pattern, and in general to raise the level of abstraction (along with flexibility, changeability etc benefits) from having to deal with Urls rather than instance types.

Now, the "bhv" namespace imported above is a bit special, it is specifically used to attach multiple behaviours. And because of how the internals of Silverlight work, it has one limitation which is you can't use binding expressions with it (the same is the case with the timeline behaviour), but you can use static resources binding expressions just fine. Below is an example of multiple bindings where the arrow keys are mapped to some action Url.

<!-- KEYBOARD ACTION MAPPINGS, MAPPED TO/WITH THE BORDER -->
<Border>
    <bhv:Behaviours.Multiple>
        <bhv:BehavioursCollection>
            <bhv:KeyDownAction Key="Up" ActionUrl="Move/North" />
            <bhv:KeyDownAction Key="Right" ActionUrl="Move/East" />
            <bhv:KeyDownAction Key="Left" ActionUrl="Move/West" />
            <bhv:KeyDownAction Key="Down" ActionUrl="Move/South" />
        </bhv:BehavioursCollection>
    </bhv:Behaviours.Multiple>
</Border>

Navigation Behaviours

• NavigateHandler: Here you can specify (rather bind to) any object that implements INavigationHandler to handle the navigation response. Note this is also a way consume navigation requests and responses in non-visual ways.
•  NavigateHandlerElementName: Alternatively if the handler is an element in the user interface you can give it's element name and it will be asked to handle the result of the navigation. NavigateParameters: These are name-value collections you can pass with the request.
• NavigateUrl: Obviously the Url to navigate to, and it is required.
• NavigateUrlStringFormat: This is used to provide a format for the NavigateUrl property, it is similar to what was introduced in .NET 3.5sp1 binding and it helps in that it can avoid the use of type convertors in some scenarios.

One thing to know, and this is important, is how the behaviour chooses the container that will handle the response. Firstly, if you have specified the handler (either by binding or by an ElementName) it will just use that and life is simple. If you do not specify, it will look in it's visual tree first and try and find the first parent that implements INavigationHandler interface. This is also means that it works kinda like a browser whereby when you click a link the immediate most container (think IFrames here) handles the navigation for you. If no handler is found in the parental visual tree, it will look at the current application object and see if it has is a registered container (of type INavigationContainer) and use that. If it still doesn't find a container at the application level, well it gives up and throws an exception.

Action Behaviours

• ActionHandler: Here like above you can specify (rather bind to) any object that implements IActionHandler interface to handle the action request. Note the handler doesn't need to be registered against with the ActionService, and so this is also a way to bypass the registered Url handlers ie. they will not be called.
•  ActionHandlerElementName: Alternatively if the handler is an element in the visual tree you can give it's element name and it will be asked to handle the action. Again, as above this is a way to bypass the registered action handlers.
• ActionParameters: Like before these are name-value collections you can pass with the request.
• ActionUrl: Quite intuitively the Url for the action, and it is a required parameter.
• ActionUrlStringFormat: This is used to provide a format for the ActionUrl property, and helps in that it can avoid the use of type convertors sometimes.

The resolution of the action is basically similar to the navigation behaviours, but with exception that it doesn't look up in the visual tree for anything that implements IActionHandler and directly goes onto any registered handlers for the action Url.

Command Behaviours

• Command: You basically specify, like WPF, any object that implements the ICommand interface.
• CommandParameter: And the accompanying parameter can be specified here.

In this case the hooking up is rather direct, you must have specified the ICommand implementing handler and the behaviour will execute it for you whilst also passing in the parameter. This helps overcome the lack of build-in support for ICommand but also extends the usage semantics in WPF.

As this has gotten quite long I'll skip the demo for another post, but I hope you can see how these behaviours bridge the element's events with a handler/consumer either directly (like with ICommands) or indirectly (via Urls) saving you a lot of work and raising the abstraction level. In fact off the 35,000+ lines of code in nRoute 60% are dedicated to bring you these behaviours (over 75 of them) - so it's quite a bite.

If I could annotate a tag line for the software industry as a whole, I would put down "we are in the business of abstractions". And perhaps, if I was in marketing for the software industry, I would append that with "because you can't have it all". Well, more to the point, in my last post I mentioned a lot of working parts that constitute the nRoute Framework while also repeatedly mentioning there is a higher level API, and that is what I want to cover in this post.

First, how is nRoute an abstraction of a "higher kind"? In two ways, it abstracts resources and actions in the form of URLs (or more correctly as URL requests). So for example you want to show the customer page you abstract it as a relative Url like "Customers/Details/StevenSpielberg/" and similarly you want to abstract a Log Entry action with a relative Url like "System/Log/Critical/" whist passing in the actual log object in a name-value collection with the request. This also represents classic loose coupling, and what it gives you is the ability to link-up actual .net objects/controls in a systematic and structured way without having direct reference to each other (very much like hyperlinks) - of which I am sure you know benefits. Another characteristic this yields, is resilience to both changes and partial break-downs for a lack of a better word. Think about how the Internet works, just because a link has 404'ed it doesn't mean the entire system comes with an unhandled exception - it still works albeit without the missing resource. And just to point the obvious, with Urls if you say put in a new user control for the the customer's details page you wouldn't have to move a dime elsewhere ,as long as it still registered at the same Url.

Firstly, let me show you how you consume Urls within the UI. Below is a simplified xaml snipped from my demo app, in which you have a "Home" persuado button (Border actually) that links to the "Home/" Url.

<!-- nav NAMESPACE -->
xmlns:nav="clr-namespace:nRoute.Behaviours.Navigation;assembly=nRoute.Silverlight"

<!-- HOME BUTTON, with STYLES -->
<Border Style="{StaticResource HomeButtonBorderStyle" nav:MouseUp.NavigateUrl="Home/">
	<TextBlock Style="{StaticResource HomeButtonTextStyle}" Text="HOME ." />
</Border>

Second example is a xaml snipped again from the demo app, and it's for registering actions to take on certain keyboard events. If you have seen the sample app, it has 3 workspaces (aka blades) onto which you can navigate, however by design it is actually configurable from 1 to 9 workspaces.  So in the code below we register keyboard shortcuts for shifting from one blade/workspace to another (though in some case it does conflict with the browser shortcuts).

<!-- bhv NAMESPACE -->
xmlns:bhv="clr-namespace:nRoute.Behaviours;assembly=nRoute.Silverlight"

<!-- KEYBOARD ACTION MAPPINGS, MAPPED TO/WITH THE ROOT USER CONTROL -->
<bhv:Behaviours.Multiple>
    <bhv:BehavioursCollection>
        
        <!-- WORKSPACES 1 to 9 MAPPED WITH NUMBERS  -->
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/1" Key="D1" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/2/" Key="D2" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/3/" Key="D3" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/4/" Key="D4" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/5/" Key="D5" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/6/" Key="D6" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/7/" Key="D7" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/8/" Key="D8" KeyModifiers="Control" />
        <bhv:KeyUpAction ActionUrl="Workspace/Actions/Select/9/" Key="D9" KeyModifiers="Control" />
        
        <!-- OTHER MAPPING -->
        <bhv:KeyUpNavigate NavigateUrl="Home/" Key="H" KeyModifiers="Control" />
        
    </bhv:BehavioursCollection>
</bhv:Behaviours.Multiple>

Now, there are a lot of attached behaviours in nRoute to do three main things:

1. Navigate to an Url
2. Take an Action
3. Use an ICommand

You can attach these with almost all Silverlight build-in controls events, and I mean almost all. There is so much detail in these behaviours that I'll have to post it separately, but suffice to say, if you don't use nRoute take out the ICommand behaviours at least and use them - you will spare a lot code and time.

The demo app, available with complete source code, makes uses of all the features mentioned here.

The requirement for using the enlisted features is registering navigation and action Urls (with handlers to be precise). In my previous post I've shown how you can register via code, but now, I wanted to show the "higher abstraction" version of the same.

using System.Windows.Controls;
using nRoute.Navigation;

namespace nRoute.Samples.FutureDesktop.Pages
{
    [MapNavigationContent("Home/", "Home Page")]
    public partial class HomePage : UserControl
    {
        public HomePage()
        {
            InitializeComponent();
        }
    }
}

Now  registering actions is purposefully very similar to what is shown above. Here we have an action handler class that handles the foreshown KeyUp events. Also, note it doesn't point to any particular KeyUp event or any potential triggering mechanism, it just handles the action and the Action Service + behaviours take care of the plumbing infrastructure.

[MapActionHandler("Workspace/Actions/Select/{Number}")]
public class WorkspaceSelectionAction : IActionHandler
{

    const string NUMBER_KEY = "Number";

#region IActionHandler Members

    public bool CanHandle(IActionDefination action)
    {
        return (action.ParsedParameters.ContainsKey(NUMBER_KEY));
    }

    public void Handle(IActionDefination action)
    {
        // if we can't get the value
        int _newIndex = -1;
        if (!Int32.TryParse(action.ParsedParameters[NUMBER_KEY] as string, out _newIndex)) return;
        
        // we get the view model and check if the index is avaliable
        var _viewModel = ((App)Application.Current).WorkspacesViewModel;
        if (_newIndex < 0 || _newIndex > _viewModel.WorkspacesCount) return;

        // else we activate, note the use of the dispatcher
        action.Request.Dispatcher.BeginInvoke(() => _viewModel.ActivateWorkspace(_newIndex));
    }

#endregion

}

How do the mappings get registered? Well, in this case we make two calls on the action and navigation services as show below. This is from the demo app's App class, where we override the custom base applications class's register methods which kind of akin to overriding in global.ascx class in asp.net:

protected override void RegisterNavigationsRoutes()
{
    NavigationService.MapLoadedAssembliesRoutes();

    // we register the images
    NavigationService.MapRoute("Images/HeartYourWeb",
        new NavigationResourceHandler("Images/HeartYourWeb.xaml", NavigationResourceHandler.XamlLoader));
    NavigationService.MapRoute("Images/MixLab",
        new NavigationResourceHandler("Images/MIX09_Color_RGB_tag.xaml", NavigationResourceHandler.XamlLoader));
    NavigationService.MapRoute("Images/MixLogo",
        new NavigationResourceHandler("Images/MIX09Logo.xaml", NavigationResourceHandler.XamlLoader));

}

protected override void RegisterActionsRoutes()
{
    ActionService.MapLoadedAssembliesActions();
}

I hope I've show how you can perhaps work at a higher abstraction with respect to the constructs and plumbing in nRoute. Unfortunately, there is a lot more to show and tell, and I defer again to future posts especially with respect to using this with M-V-VM and custom loading/mapping strategies. My next post will go much deeper into behaviours and how they really are "code-savers" in the ever enduring adventures of "abstractions of the higher kind".