Possible runtime differences

xUnit.net 1.5 is compiled against the .Net Framework 3.5. If you’re using F# in combination with the VS2010 RC or RTM (like I do) you’ve got at least to options to make them work together.

1. Use multi-targeting  and configure the F# projects to compile for the .NET 3.5 runtime (Properties/Application/Target Framework).
2. Update the app.config files of xunit.console.exe and xunit.gui.exe with a startup section and specify the .NET framework 4.0 version as supported.

   
        <startup>
       	<supportedRuntime version="v4.0.30128" safemode="true"/> <!-- VS2010 RC -->
       	<supportedRuntime version="v4.0.30319" safemode="true"/> <!-- VS2010 RTM -->
        </startup>
   

Pay attention to your parentheses

My choice was to update the xUnit.net configurations. After the update of the configuration files my assembly was loaded, however the test runner failed to detect my unit tests. As it turns out the open parentheses after a test function play an important role.

     [<Fact>]
     let After_converting_a_valid_data_row_the_title_should_have_been_extracted = //This compiles, but the test doesn't show up in the test runner.
        let row = convertDataRow "Test, 1234"
        Assert.Equal(fst(row), "Test")

     [<Fact>]
     let After_converting_a_valid_data_row_the_title_should_have_been_extracted() = //This will work fine
        let row = convertDataRow "Test, 1234"
        Assert.Equal(fst(row), "Test")
  

My first reaction was: WTF? But after reading some more chapters of "Real world functional programming" and a discussion at our local F# book club the behavior makes sense to me. My current understanding is that omitting the parentheses results in a different method signature. You can easily spot this in FSI. The first one is val After_converting_a_valid_data_row_the_title_should_have_been_extracted : unit while the second one results in a val After_converting_a_valid_data_row_the_title_should_have_been_extracted : unit -> unit. What you can see here is that the first function signature doesn’t have a parameter while the second has a parameter of the type unit. One interesting difference between F# and C# is that the F# equivalent to C#’s void is an actual type called unit. The fun part is that () is it’s only value. Parentheses play a completely different role here The xUnit test runner looks for methods with one unit parameter and a return type of unit. That’s why you need the parentheses.

Testing exceptions with xUnit.Net

One little subtlety I came across when testing exceptions is that you have to explicitly "ignore" the return value when you’re using Assert.Throws and pass in a method which doesn’t return unit. Feels a bit strange at first, but explainable. Again a signature mismatch. Assert.Throws expects a method with a unit -> unit signature. You have to do this in order to please the compiler. (If there’s a better way for this, please let me know)

    [<Fact>]
    let Trying_to_convert_an_invalid_format_throws() =
        Assert.Throws(fun () -> convertDataRow "FuBar" |> ignore)
  

The ignore function simply throws away any value it receives, returns a unit and makes the F# compiler happy.

Conclusion

I hope you saw in this post that testing F# with xUnit.net is actually pretty easy. It’s also a wonderful case for language interop on top of the CLR. Go see it for yourself

Some of my older posts on the topic showed that the component responsible for Screen activation and deactivation in StoryTeller is the ScreenConductor. However, when the ScreenConductor activates or deactivates a Screen, it delegates a major part of work to the so called IShellService. The only implementer of this interface, the ShellService, is just a little facade around three things.

1. The ICommandbar, which is the main toolbar of StoryTeller
2. the IOptionsMenu, which is a kind of Shortcut menu for StoryTellers Commands and
3. the IScreenObjectRegistry, which acts as a store / front-end for the current Command registration.

    public class ShellService : IShellService
    {
        private readonly ICommandBar _Commands;
        private readonly IOptionsMenu _options;
        private readonly IScreenObjectRegistry _registry;

        public ShellService(
              IScreenObjectRegistry registry,
              ICommandBar Commands,
              IOptionsMenu options)
        {
            _registry = registry;
            _Commands = Commands;
            _options = options;
        }

        #region IShellService Members

        public void ActivateScreen(IScreen screen)
        {
            _registry.ClearTransient();
            screen.Activate(_registry);
            refill();
        }

        public void ClearTransient()
        {
            _registry.ClearTransient();
            refill();
        }

        public void Start()
        {
            refill();
        }

        #endregion

        private void refill()
        {
            _Commands.Refill(_registry.Actions);
            _options.Refill(_registry.Actions);
        }

You can see some interesting aspects in the short code above.

1. The word transient appears several times. StoryTeller differentiates between two types of Commands: Permanent Commands and transient Commands. Permanent Commands are displayed, well permanently, while transient Commands are what I depicted as contextual Commands. They are Commands which should be only visible in a particular context.

2. Contextualization of Commands is handled on a per Screen basis in StoryTeller. Every time a Screen gets activated or deactivated the ICommandBar and the IOptionsMenu get reset and completely rebuild. With this you can have a very different Command UI depending on which Screen is activated.

3. The actual Command configuration in the Screen Activation Lifecycle is completely delegated to the active Screen. In his Activate() method he receives a reference to the IScreenObjectRegistry which can be used in order to start the Command configuration via a small fluent API.

    public interface IScreenObjectRegistry
    {
        //Gets a collection of all currently known command configurations
        IEnumerable<ScreenAction> Actions { get; }

        //Removes all transient command configurations from the registry
        void ClearTransient();

        //DSL starting point for the configuration of transient Commands
        IActionExpression Action(string name);

        //DSL starting point for the configuration of permanent Commands
        IActionExpression PermanentAction(string name);
    }

The following code snippet shows an example of how this API could be leveraged inside a Screen.

        public void Activate(IScreenObjectRegistry screenObjects)
        {
            screenObjects
                .Action("Save")
                .Bind(ModifierKeys.Control, Key.S)
                 .To(_save); //This can be either Systen.Action or an System.Windows.Input.ICommand

            screenObjects
                .Action("Cancel")
                .Bind(Key.Escape)
                .To(_cancel);
        }

Gabriel Schenker has written an excellent series on how to write such a fluent API. Although it’s targeting Silverlight, most of the involved problems are explained in detail there, so forgive me if I don’t dive into the actual DSL implementation.

Some final thoughts

Making the Screen responsible for setting up his Commands makes a lot of sense to me, since the Screen is the unit which gets plugged into the UI infrastructure and it also very likely plays the role of the Command receiver in terms of the classic GoF pattern description. This doesn’t necessary mean that Screens are the only place for Command configuration. The initialization of modules in a Composite application is also a very likely place for registration of permanent Commands.

I consider having a fluent API for configuring the Commands also a plus, because it IMHO makes the actual Command configuration a lot easier and accessible. I’ve used the same setup (fluent API + delegation to screen) on my last 3 projects and it always worked for me like a charm.

Like I mentioned in the previous post, what I don’t like that much is the idea of mixing in visual aspects (Icon, Size, Location) into the Command configuration, mostly because I’ve been burned by this in the past when facing complex menus, like the ribbon. I think it’s a good idea to externalize the visual aspect via XML, at least for all the static stuff.

This is it

This was the last post about StoryTeller (at least for a while). It has been an interesting voyage which taught me a lot about UI infrastructure design, StructureMap usage and Convention over Configuration. Although it was primarily my learning excercise I hope you took something interesting with you from this blog series, too.

I’m going to continue my research on UI architecture with another deep dive into Rob Eisenbergs Caliburn soon. If your interested I would be very happy to have you with me on that trip . . .

Let’s take a look at some of the questions I left unanswered in the last post.

Is the basic GoF Command pattern sufficient for a modern composite application?

The basic GoF Command pattern has no notion of visual state of a Command, such as (Is)Enabled or (Is)Visible. Its original purpose was to encapsulate an action, so that it can be passed around and executed at some later point of time. Not more, not less.

interface ICommand
{
   void Execute();
}

Obviously real world desktop apps need something a bit more sophisticated. I’ve seen several infrastructures in my (not so old) career so far (home grown as well as OS alternatives), which extended this basic idea with at least one of those properties mentioned above.

Take for instance the P&P Composite UI Application Block (now better known as part of the Smart Client Software Factory). CAB implements a delegate based variation on the Command pattern. The delegate represents the action which is passed around. However, this delegate is managed by the Command class which has a notion of Status.

enum CommandStatus
{
    Enabled, //visible and enabled
    Disabled, //visible and disabled
    Unavailable //invisible
}

The WPF Command infrastructure version of the Command interface is more like the original pattern and adds the Enabled Property and an EnabledChangedEvent to the interface definition.

interface ICommand
{
    void Execute();
    bool Enabled {get;}
    event EventHandler EnabledChanged;
}

To be honest the Command interface never looked like the original GoF definition in ANY APPLICATION or project I’ve worked on so far. It always had a slight modification in one or another way.

StoryTeller’s Command interface

StoryTeller is a WPF based application, so naturally it gets the WPF Command infrastructure out of the box. However it composes the WPF ICommand into a StoryTeller specific structure, the IScreenAction.

public interface IScreenAction
{
     bool IsPermanent { get; set; }
     InputBinding Binding { get; set; }
     string Name { get; set; }
     Icon Icon { get; set; }
     ICommand Command { get; }
     bool ShortcutOnly { get; set; }
     void BuildButton(ICommandBar bar);
}

ScreenAction extends the capabilities of the original GoF-Pattern with a lot of metadata, mostly for visual aspects (Icon, Description). If you’re wondering why he included visual aspects: That basically tries to solve a reoccurring problem in composite apps:

In composite applications modules are not known at compile time to the infrastructure. Neither are all their capabilities and how they might be displayed in the infrastructure shell. Because of that, the infrastructure needs a dynamic, deferred way for doing the shells visual configuration at application startup.

One way to implement this is to delegate the responsibility for setting this up to the modules itself. This can be done during the module load time or every time a screen is displayed. This fits very well with the idea of the Open Closed Principle, since adding new modules/screens doesn’t require any reconfiguration/recompilation of other modules or the infrastructure. This is more or less the approach that StoryTeller takes.

Some personal thoughts on IScreenAction

I’ve worked on three applications in the past which followed down the same road. One thing I noticed throughout those three applications is that this approach isn’t really well suited when you’ve got strict and/or complex requirements about how the UI of an application should look. Let me clarify a bit what I mean:

• The Ordering Problem. Even if you organize tools representing commands in a simple toolbar (as StoryTeller does) you can very easily get into situations where the product owner wants to have the tools in a very specific order which is different to module load order, some internal event order, whatever. I’ve encountered this several times now.

  First time we solved this by introducing a global constant class containing tool names. Very, very bad idea, do not repeat this. This introduces a kind of hidden temporal coupling, because now modules must be loaded in a particular order (so that a tool already exists to which we can refer by name).

  StoryTellers take on this is a bit better (but IMHO not much). The Icon class has an Integer based Order property. All tools get sorted based on this property in StoryTellers CommandBar when it’s reloaded. This is less coupled, because it eliminates the temporal aspect of the coupling, but still has coupling.

• API bloat with visual aspects. One area where I really started to find this approach annoying is when you stop having simple toolbars and start to use more complex menu types like for instance the Ribbon. Taking the ribbon as an example: Now don’t have simply an ordering problem, but at minimum an icon problem (Normal icon vs. Quick Access Toolbar), a size problem (Displayed large or small) and a positioning problem (/Tab/Group/ElementGroup vs. /ApplicationMenu/Left).

  We added all those stuff to our Command registration and guess what, we weren’t happy with that. We created a monster API actually doing very little.

So what do I (currently) prefer? Our current project (also using the Ribbon) completely strips the visual aspect of the Command. Our Command API looks very much like the WPF one, with the only addition of an Id property. The whole visual aspect is configured using an XML file which is loaded at application startup.

<Ribbon>
   <Tab>
      <Group>
         <Button imageId=”CancelIcon“ commandId=”CommandXYZ” />
      </Group>
   </Tab>
</Ribbon>

I think you get the point. It works very well for our scope. (Slight warning though: This solution might not be the best in case you need to represent menu state based on dynamically loaded data).

See you next time for: Commands strike back

The Command Pattern

A lot of the content in this series dealt exclusively with how the StoryTeller UI layer manages Screens in its content area, but as you know most of the time an application consists of more parts than just the plain content area. A typical desktop application is probably going to have some sort of Mainmenu, a Statusbar and of course Contextmenus. Items displayed in those areas very often represent actions an application can perform. They act as a trigger of those actions.

A typical way to implement this is using the GoF-Command Pattern, which separates the invoker of an action (for instance a button) from the receiver instance which executes the action by introducing the Command abstraction. A Command encapsulates the knowledge needed for an invokation of the receiver instance, so that it can be executed at a later time.

Commands are potentially contextual

An application can have lots and lots of Commands. While some of these Commands are available all of the time, some of them can only be executed in a particular context. A typical example for Commands of the first category might be the “Exit application” Command. A typical example for the latter category might be the “Undo” Command or “Redo” Command in all kinds of text editors, which can only be executed when the currently viewed document has some changes. It’s not uncommon to have lots of contextual Commands in an application that are only related to a very specific Screen or Screen state.

When we think in terms of usability, the least a user should be able to take granted from an app is that the app appropriately shows which actions can be performed at a particular point of time. This can be achieved by enabling / disabling related items depending on the availability of the Command (be it manually or through databinding). Sometimes though,it might be a better approach to have an even more contextualized UI that only shows the commands related to the current context. So for instance if no code editor view is shown in Visual Studio than the “Undo” and “Redo” Commands should also not be visible (NOTE: VS doesn’t actually behave that way). I think this idea of contextualized UIs becomes more and more popular. Office 2007/2010 was build with this idea in mind.

Commands in a Composite UI

Composite UIs which follow the Open / Closed Principle add another problem to the mix. When new modules or new screens are loaded into a composite app, they shouldn’t need to modify the app infrastructure in order to add their related commands. The app infrastructure needs to provide a way to plug those commands in without modification. This also includes their visual representation (Text, Tooltip, Icon, etc.).

Questions we should take a closer look at

• Do we need to differentiate between types of Commands?
• Who is responsible for adding / registering commands?
• How is the visual representation of commands configured?
• Who is responsible for deciding whether Commands are available?
• Is there build-in .NET Framework support for this?
• Of course: How does StoryTeller implement all this?

I’m afraid that’s all for today. I wish you all merry Christmas and a happy new year.

See you in 2010

You could say that we mostly talked about ingredients. Today I would like to take some additional time in order to show how this is all assembled into an actual API. Those of you who’ve  already spend some time with the StoryTeller codebase too or have watched one of the many screencasts about the Screen Activation Lifecycle probably know what I’m going to show today. Today is all about the Screen Conductor.

Screen Conductor vs. Application Controller

Before we dive into the actual code, let’s take a short break and talk a little bit about a more high level view on the Screen Conductor and the role the conductor is fulfilling in an application.

Martin Fowler identified the pattern ApplicationController some years ago as “A centralized point for handling screen navigation and the flow of an application.”

It’s kind of a coordination structure which manages / coordinates the lifecylcle of child screens in an application as well as the lifecycle of the application shell itself (think about controlled shutdown for instance).

You can think of the ApplicationController as a Facade client code can call in order to create/activate/deactivate screens in an application. This Facade defines a nice separation between application code on the one side and the UI infrastructure on the other side. It shields away implementation details of how the application is actually displaying screens (tab style, web style, etc) from the client and also provides a nice point for handling scenarios like dirty checks on screens.

As an application grows over time, it’s a good idea to break down the ApplicationController into several collaborating classes and decouple its implementation details from another in order to make the system more manageable and maintainable. Adding a new screen to the application for instance should not require a change in one of the UI infrastructure classes.

When breaking down the ApplicationController into several collaborating classes a good lead is to use the Single Responsibility Principle in order to identify responsibilities which can be extracted. That’s exactly what Jeremy D. Miller did in his Screen Activation Lifecycle.

He broke down the ApplicationController pattern into several smaller responsibilities, the most important beeing

• the ScreenCollection (which keeps track of all existing screens and the one beeing the active screen)
• the ScreenSubject (which is used to separate identification and creation of a screen from the screen itself)
• Screens (which provide the content beeing displayed and hooks for instance for the dirty check when the application closes)
• and the ScreenConductor.

Jeremy describes the ScreenConductor and its responsibilities as the following:

“Controls the activation and deactivation lifecycle of the screens within the application. Depending on the application, the conductor may be synchronizing the menu state of the shell, attaching views in the main panel or otherwise, and calling hook methods on the Presenter’s to bootstrap the screen. It may also be just as important to deactivate a screen when it’s made the inactive tab to stop timers. My first exposure to a Screen Conductor was an insurance application that was built with web style navigation. Anytime the user moved away from a screen we needed to check for “dirty” screens to give the user a chance to deal with unsaved work. On the other hand, we also had to check the entry into a requested screen to see if we could really open the screen based on pessimistic locking or permission rules. We pulled our a Layer SuperType for our Presenters for methods like CanLeave() and CanEnter(). The Screen Conductor would use these methods and others to manage screen navigation.”

To me the ScreenConductor is more or less an OCP-fied subset of the original ApplicationController pattern, focussing on the coordination and facade ideas of the original pattern.

A short episode in the Screen Activation Lifecycle

Let’s give our discussion a bit more detail. So far it was rather abstract. Before looking into the actual code I would like to walk you through a typical usecase which depicts how those components actually work together. The example Jeremy mostly uses for this is “Opening a source code file in Visual Studio” . I’m lazy, so I’m going to reuse this one.

“Consider you double-click a file in the  Solution Explorer of VS. When you do this for the first time a new tab displaying the contents of the file will be opened. Doing the same thing a second time will not open a new tab, but rather focus the existing tab displaying the contents of the file.”

It’s actually easy to translate this story into a more abstract version using the responsibilities described in this post so far.

“Consider you want to open a Screen via a ScreenSubject. When the ScreenSubject detects that no related Screen is being displayed to the user, a new Screen will be created by the subject and then added to the ScreenCollection. Doing the same thing a second time will not open up a Screen, but rather activate the existing SCREEN, because the ScreenSubject detected that the Screen is already open.”

The interesting sidenode in this design is that from a client code perspective there is no difference between opening up a screen and activating a screen. Really nice . . .

Usecase: Opening a Screen

Now that you’re familiar with the first scenario, time to show some code. I’ve shown parts of this before in the previous post (Sorry for the duplication), but added some bits in order to illustrate this example.

From the outside world a call to the ScreenConductor for this usecase might look like this.

var subject = new CSharpFileSubject(@"C:\end\of\the\world.cs");
screenConductor.OpenScreen(subject);

Notice that all data needed for creating the actual Screen will be passed in with the concrete ScreenSubject implementation.

public class CSharpFileSubject : IScreenSubject
{
     private _fileName;

     public CSharpFileSubject(string fileName) { _fileName = fileName;}

     public bool Matches(IScreen screen)
     {
          return screen is SourceCodeScreen &&
                    string.Equals((SourceCodeScreen)screen.FileName, _fileName));
     }

     public IScreen CreateScreen(IScreenFactory screenFactory)
     {
          var screen =  screenFactory.Build<SourceCodeScreen>();
          screen.File = _fileName;
          return screen;
     }
}

This is not quite the code I would write for a real system, but I think you get the point. Two methods need to be implemented for the IScreenSubject interface. This is bool Matches(IScreen) which identifies a related screen and IScreen CreateScreen(IScreenFactory) which is used to create the screens.

I really like this kind of API design since it gives you all sorts of extension points without the need to open up the actual infrastructure. Want to show a WaitCursor while you create the Screen? Go ahead. Want to do some loading before the screen is opened? Here’s the place to do it . . .

Anyway, the ScreenConductors side of things looks like this.

        public virtual void  OpenScreen(IScreenSubject subject)
        {
            if (subject.Matches(_screens.Active))
            {
                return;
            }

            IScreen screen = findScreenMatchingSubject(subject);

            if (screen == null)
            {
                screen = createNewActiveScreen(subject);
            }
            else
            {
                activate(screen);
            }

            _screens.Show(screen);
        }

Pretty slick, isn’t it? The whole code is really dense. Most of the methods involved are not more than 5 lines long. Finding the related screen for instance is just a matter of a LINQ-Query on the ScreenCollection using the Matches-method as its predicate.

private IScreen findScreenMatchingSubject(IScreenSubject subject)
{
      return _screens.AllScreens.FirstOrDefault(subject.Matches);
}

Creation of the target screen on the other hand is just a matter of handing the ScreenFactory (which is actually just a facade to the IoC-Container of choice) to the subject, activating the created Screen and adding it to the ScreenCollection.

private IScreen createNewActiveScreen(IScreenSubject subject)
{
     IScreen screen = subject.CreateScreen(_factory);
     activate(screen);
     _screens.Add(screen);
     return screen;
}

The last missing piece here is the actual activation of the Screen.

private void activate(IScreen screen)
{
    _shellService.ActivateScreen(screen);
}

This is delegated to the so called IShellService. You might ask yourself why this particular dependency exists (at least I did). The main purpose of this service is mostly the topic of registering Commands and filling up option panes related to the current Screen. This will be a post on its own, so don’t be mad at me, when I don’t cover it today. Instead I would like to take a look at another common use case:

Usecase: Closing a Screen

Now that we’ve seen how a Screen gets opened, let’s take a look at the other side of the coin, at how it’s closed.

public virtual void Close(IScreen screen)
{
    if (removeScreen(screen))
    {
        activateCurrentScreen();
    }
}

Most of the handling is in the removeScreen-method (btw, where does this convention of having all private methods beeing camel-cased come from? Is this some Java-exposure leaking through? )

private bool removeScreen(IScreen screen)
{
     if (!screen.CanClose()) return false;

    _events.RemoveListener(screen);
    _screens.Remove(screen);

    _shellService.ClearTransient();

    return true;
}

It delegates the decision whether a screen can be closed to the screen and in case it can be closed, it removes the screen from the EventAggregator(_events), from the ScreenCollection (_screens) and clears its Command-registration (_shellService.ClearTransient()), before it activates the next screen becoming visible (in case there is one).

private void activateCurrentScreen()
{
        IScreen screen = _screens.Active;

        if (screen != null)
        {
            activate(screen);
        }
}

Usecase: App shutdown coordination

There is another common usecase implemented by the ScreenConductor I would like to show you. This is how the whole app shutdown is coordinated.

Prerequesites for this: Instances interested in beeing notified when the user tries to shut the application down, need to a) implement the IClosable interface and b) be registered at the EventAggregator. The latter is done automatically for Screens by the ScreenConductor.

public interface ICloseable
{
    void AddCanCloseMessages(CloseToken token);
    void PerformShutdown();
}

The IClosable interface just consists of two methods. void AddCanCloseMessage(CloseToken) is called in order to get feedback from listeners whether the application is allowed to be shutdown. You can think of CloseToken as a more or less extended version of CancelEventArgs.

public class CloseToken
{
     private readonly List<string> _messages = new List<string>();

     public string[] Messages { get { return _messages.ToArray(); } }

     public void AddMessage(string message)
     {
         _messages.Add(message);
     }
}

The following code piece is hooked into the Closing – event of StoryTellers main window (the shell). It heavily leverages the delegate based eventing of StoryTellers EventBroker in order to interact with all interested listeners.

public bool CanClose()
{
     var token = new CloseToken();

     _events.SendMessage<ICloseable>(x => x.AddCanCloseMessages(token));

    bool returnValue = true;

    if (token.Messages.Length > 0)
    {
         string userMessage = string.Join("\n", token.Messages);
         returnValue = _messageBox.AskUser(CAN_CLOSE_TITLE, userMessage);
    }

    if (returnValue)
    {
        _events.SendMessage<ICloseable>(x => x.PerformShutdown());
    }

    return returnValue;
}

One remark to the CanClose() code: _messageBox is just a small wrapper abstraction in order to make user interaction via message prompts testable. There’s nothing really fancy behind that.

I really like the way the app shutdown is implemented. In fact we’ve added something very similar in my current project. However, I’m not so sure when it comes to the question whether this particular code piece should be part of the ScreenConductor. You could argue that this method has only very limited cohesion with the rest of the ScreenConductors methods. In fact most of the stuff the ScreenConductor interacts with (ScreenCollection, Screens, ScreenFactory, ScreenSubject) isn’t touched in this method. Besides that, it’s code that client application code normally IMHO doesn’t need to or even should call. In our current app we’ve extracted this responsibillity into a separate class called the ApplicationShutdownCoordinator because of that.

Some more impressions on StoryTellers ScreenConductor

The exposed API of the ScreenConductor is pretty small, actually only 6 “core” methods and some overloads.  Most of the API really shines. However, besides the already mentioned CanClose() functionality, there is another functionality which in my opinion should not be in the ScreenConductor. Can you spot it?

LoadHierarchy(Func<Hierarchy>)) looks a bit misplaced to me because it seems to work on a different abstraction level than the rest of the methods. It looks very application specific, while the rest of the StoryTeller APIs look very general purpose (independant from the fact whether Jeremy actually wanted to achieve this or this being just the result of applying good design practices).

Same applies to one of the Messages / Events the ScreenConductor is registered for at the EventBroker, namely DeleteTestMessage. I don’t think it should be directly handled in the ScreenConductor.

A static code analysis might indicate that the ScreenConductor has too many dependencies. In fact there’re

7 direct dependencies injected into the constructor,

• IEventAggregator
• IScreenCollection
• IScreenFactory
• IApplicationShell
• IShellService
• IScreenObjectLocator
• IMessageCreator

6 transient dependencies (method parameters or local scope),

• IScreen
• IScreenSubject
• CloseToken
• UserScreenActivation
• OpenItemMessage
• DeleteTestMessage

and 3 Message interests

• UserscreenActivation
• OpenItemMessage
• DeleteTestMessage

in the ScreenConductor class. Sounds pretty heavy and like a refactoring candidate at first. However, as I mentioned earlier, the ScreenConductor is mostly a Facade with some additional coordination logic in it. When I say “some additional coordination logic” I mean this literally. ScreenConductor has just round about 250 LOC.

I’m totally ok with this. It certainly has some potential for optimization of the dependencies (IScreenObjectLocator seems to be at least partially obsolete, IApplicationShell and IShellService could be merged I guess), but even without that I consider it a really good example of strong extensible design for  composite desktop apps.

For me personally the ScreenConductor fills a really important gap in the p&p composite app guidance (be it CAB / SCSF or PRISM). I always had the feeling that I’m missing something there, but was unable to point out exactly what I’ve been missing. This feeling mostly came up when I added some screen activation or screen creation logic in places that didn’t felt right. Now I know why. Interestingly others observed the need for something similar as well.

Having a ScreenConductor in your application makes IMHO the whole UI infrastructure a lot more approchable and easier to understand.

Some final thoughts

I left the rest of the ScreenConductors code out of this post intentionally, because if there’s one thing I’d like you to take from this post or even the complete series is that StoryTeller is a really good learning resource. I really value, what I’ve learned from the Dovetail guys while inspecting the code. I wish I had done this earlier.

Good design matters. If you’re looking for a place to learn more about it, the StoryTeller codebase might just be the place for you.

See you next time, when we take some time to dig into the command structure of StoryTeller . . .

Current Version is 1.0.1.16. You can download it here or get the latest sources from the trunk.

Happy specifying . . .

The common use case for the ScreenSubject

Lets first start with a little description of the usage of the two patterns in StoryTeller. When application code wants to open a new screen in StoryTeller it’ll probably use one of the OpenScreen overloads on the IScreenConductor facade in order to do that.

public interface IScreenConductor
{
    void OpenScreen(IScreenSubject subject);
    void OpenScreen<T>() where T: IScreenSubject;
}

The common use case for the ScreenSubject can be easily depicted using a tool we all know quite well, Visual Studio. Think about it: What happens when you click onto a source code file in the Source Code Explorer for the first time? Well, a new tab is created displaying the content of the file. However, if you click the item in the Source Control Explorer the second time, the previously created tab gets activated and NO NEW TAB IS CREATED.

How is this implemented

Let’s take a look at how this behavior is implemented in StoryTeller. The following code snippet shows a very small part of the ScreenConductor. I’ve inline some comments in order to make it more visible
what is going on there.

        public virtual void OpenScreen(IScreenSubject subject)
        {
            //_screens is of type IScreenCollection
            if (subject.Matches(_screens.Active))
            {
                return;
            }

            //This simply makes a LINQ-lookup on the ScreenCollection
            //using ScreenSubject.Matches as a predicate
            IScreen screen = findScreenMatchingSubject(subject);

            if (screen == null)
            {
                //This passes the global IScreenFactory into the
                //ScreenSubjects CreateScreen method in order to create
                //the screen.
                screen = createNewActiveScreen(subject);
            }
            else
            {
                activate(screen);
            }

            _screens.Show(screen);
        }

The IScreenSubject abstraction plays a quite important role in this use case. The interface defines only two methods matching the responsibilities of the ScreenSubject

    public interface IScreenSubject
    {
        bool Matches(IScreen screen);
        IScreen CreateScreen(IScreenFactory factory);
    }

As we saw in the ScreenConductor snippet the Matches method is used as a predicate in order to find the related screen. The CreateScreen method isn’t directly shown in the snippet, but it’s not that complicated. It’s responsible for coordinating the creation of a screen. When I say coordination I’m referring to the fact that the actual screen creation is the responsibility of the IScreenFactory (which is just a simple wrapper around StructureMap).

   public interface IScreenFactory
    {
        T Build<T>() where T : IScreen;
        IScreen<T> Build<T>(T subject);
    }

With this design in place we have a very nice extension point in place to do all kinds of things around the screen creation. Want to do some deferred data loading before the screen is shown? That’s your place. Maybe you want to show some progress indicator while doing this. Guess what, that’s your place to do this. And the best of it: The screen doesn’t have to know anything of this, you can free
him of this kind of logic.

There’re some base classes which provide some base implementation for different use cases in StoryTeller. I’m only going to show one of them, the ScreenSubject<T>. This class adds a bit generics on top of the ScreenSubject (in order to allow auto-registration using StructureMaps convention over configuration features).

   // Marker interface
    public interface IScreenSubject<T> : IScreenSubject
    {
    }

    public class ScreenSubject<T> : IScreenSubject<T>
    {
        private readonly T _subject;

        public ScreenSubject(T subject)
        {
            _subject = subject;
        }

        #region IScreenSubject<T> Members

        public bool Matches(IScreen screen)
        {
            var specific = screen as IScreen<T>;
            if (specific == null) return false;

            return specific.Subject.Equals(_subject);
        }

        public IScreen CreateScreen(IScreenFactory factory)
        {
            return factory.Build(_subject);
        }

        #endregion

        public bool Equals(ScreenSubject<T> other)
        {
            if (ReferenceEquals(null, other)) return false;
            if (ReferenceEquals(this, other)) return true;
            return Equals(other._subject, _subject);
        }

        public override bool Equals(object obj)
        {
            if (ReferenceEquals(null, obj)) return false;
            if (ReferenceEquals(this, obj)) return true;
            if (obj.GetType() != typeof (ScreenSubject<T>)) return false;
            return Equals((ScreenSubject<T>) obj);
        }

        public override int GetHashCode()
        {
            return _subject.GetHashCode();
        }
    }

The basic idea used in this implementation of IScreenSubject is that a ScreenSubject is related to a single data instance. Coming back to the Visual Studio example, this could have been represented as something like ScreenSubject<SourceCodeFile>. Really interesting . . .

The last code snippet for today I’d like to show is how the ScreenFactory is actually implemented. As usual really short, not very much code.

    public class ScreenFactory : IScreenFactory
    {
        private readonly IContainer _container;

        public ScreenFactory(IContainer container)
        {
            _container = container;
        }

        #region IScreenFactory Members

        public SCREEN Build<SCREEN>() where SCREEN : IScreen
        {
            return _container.GetInstance<SCREEN>();
        }

        public IScreen<T> Build<T>(T subject)
        {
            return _container.With(subject).GetInstance<IScreen<T>>();
        }

        #endregion
    }

I really like the way how StructureMap allows injecting transient parameters in the resolution process . . .

Closing thoughts

I’m honest with you. I consider ScreenSubject to be one of the most valuable patterns I’ve learned so far while playing with the StoryTeller sources. It provides such a nice extension point for screen initialization. I think it’s one of those patterns you don’t know how much you miss it until you see it for the first time and recognize how much it could have helped you in the past. At least that was my reaction.

In the past I’ve put a lot of the functionality which resides in StoryTeller in ScreenSubject implementations on my screens which polluted my screens with a lot of initialization code and sometimes (especially when you have high network latency) doesn’t even really look good (I bet you know what I’m talking about, don’t you? I bet a lot of you have seen the frozen screen, too).

The ScreenSubject pattern was introduced to my project last week and what can I say: I’m pretty happy to have it in our application

Last time we spend some time with the concept of Screens. Screens more or less provide the content of an application. Content needs to be displayed somewhere and that’s where the ScreenCollection concept comes into play.

In abstract a ScreenCollection is a container for multiple Screens. It’s used to display screens. The ScreenCollection concept is comparable to PRISMs Regions or CABs WorkSpaces. It doesn’t really contain a lot of intelligence. It only allows you to add a Screen, remove a Screen, getting all Screens in the container, make a Screen the active one. You know, all in all the typical stuff you would expect from a collection (maybe except the last one). The ScreenCollection contract is represented by the IScreenCollection interface which looks like this:

        public interface IScreenCollection
       {
             void ClearAll();
             IScreen Active { get; }
             void Show(IScreen screen);
             void Add(IScreen screen);
             void Remove(IScreen screen);
             IEnumerable<IScreen> AllScreens { get; }
             void RenameTab(IScreen screen, string name);
        }

If take a closer look at the interface you’ve probably recognized the last method which doesn’t really fit in there. Let’s spare that discussion for a moment. I’m going to comment on that in a moment.

StoryTeller contains only one implementation for the IScreenCollection interface, which is called (what-a-surprise) ScreenCollection. This class simply wraps around a standard WPF TabControl. Let’s take a look at how this is implemented, starting with the constructor.

    public class ScreenCollection : IScreenCollection
    {
        private readonly Cache<IScreen, StoryTellerTabItem> _tabItems = new Cache<IScreen, StoryTellerTabItem>();
        private readonly TabControl _tabs;

        public ScreenCollection(TabControl tabs, IEventAggregator events)
        {
            _tabs = tabs;
            _tabItems.OnMissing = screen => new StoryTellerTabItem(screen, events);
            _tabs.SelectionChanged += (s, c) => { events.SendMessage<UserScreenActivation>(); };

	    // Hack.  Sigh.
            events.AddListener(new RenameTestHandler(new ScreenFinder(this), this));
        }

	...
    }

There’re are two interesting things to notice here. The ScreenCollection uses a cache concept in order to correlate Screens and the TabItems used to display them. The Cache<TKey,TValue> class is a smart wrapper around an IDictionary<TKey,TValue> which (besides some other functionality) allows you to plug-in a custom handler which is called when no value is found for the specified key. This handler acts as a kind of value factory. That’s exactly what we see when we take a look at the line with _tabItems.OnMissing. Each time a Screen is not found in the cache StoryTeller creates a new StoryTellerTabItem.

The other interesting thing to notice is that the ScreenCollection doesn’t directly expose events but rather uses the Eventbroker for this. You can see this at the UserScreenActivation message.

Yeah and then there is the “RenameTab” thing. It’s marked as a hack. It simply shouldn’t be there. The problem it currently solves it that when a test is renamed the related TabHeader must also be updated (We take a look at the TabItem in a moment). I wonder whether this isn’t something that could be done in a cleaner way using WPF databinding on Screen.Title instead.

Lets take a look at how the cache magic is used. It’s really compact code. Most of the methods are one or two liners.

        public void ClearAll()
        {
            _tabs.Items.Clear();
        }

        public void Show(IScreen screen)
        {
            _tabs.SelectedItem = _tabItems[screen];
        }

        public void Add(IScreen screen)
        {
            _tabs.Items.Add(_tabItems[screen]);
        }

        public void Remove(IScreen screen)
        {
            TabItem tabItem = _tabItems[screen];
            _tabItems.Remove(screen);
            _tabs.Items.Remove(tabItem);
        }

        public IEnumerable<IScreen> AllScreens { get { return new List<IScreen>(_tabItems.Keys()); } }

The cache class is used like you would use a good old Hashtable. All in all I think I don’t need to say more here. Here is the code for determining the active Screen.

        public IScreen Active
        {
            get
            {
                if (_tabs.SelectedItem != null) return toScreen(_tabs.SelectedItem);

                return null;
            }
        }

        private IScreen toScreen(object tab)
        {
            return tab.As<TabItem>().Tag.As<IScreen>();
        }

Last but not least here’s the code for the TabItem which is build around a screen.

    public class StoryTellerTabItem : TabItem
    {
        private Label _label;

        public StoryTellerTabItem(IScreen screen, IEventAggregator events)
        {
            Func<Action<IScreenConductor>, Action> sendMessage = a => () => events.SendMessage(a);

            Header = new StackPanel().Horizontal()
                .AddText(screen.Title, x => _label = x)
                .IconButton(Icon.Close, sendMessage(s => s.Close(screen)), b => b.SmallerImages());

            Content = new DockPanel().With(screen.View);
            Tag = screen;

            ContextMenu = new ContextMenu().Configure(o =>
            {
                o.AddItem("Close", sendMessage(s => s.Close(screen)));
                o.AddItem("Close All But This", sendMessage(s => s.CloseAllBut(screen)));
                o.AddItem("Close All", sendMessage(s => s.CloseAll()));
            });
        }

        public string HeaderText { get { return _label.Content as string; } set { _label.Content = value; } }
    }

I need to talk more about this part, don’t I?

Again two intersting things here. First thing, it really makes heavy usage of C#3.0. You can see a lot of Extension Methods on WPF classes used in order to build and configure WPF elements in a very fluent and compact way.

Besides that you see here again how the EventBroker can be nicely integrated into Screen handling. Take a look at the context menu of each TabItem. It provides handlers which call directly into the EventBroker for triggering the typical close operations you can also see in Visual Studio. The important thing here to take away is that the close operations are only triggered here but performed by the IScreenConductor.

For those of you who didn’t follow my “StoryTeller” investigations from the start: The ScreenConductor is the great coordinator for the Screen Activation Lifecycle behind the scenes. It’s (as far as I can tell) the central facade to the Screen Activation Lifecyle from the perspective of typical application code. The ScreenConductor is a big topic which will be discussed in one of the next posts.

Closing thoughts

Lets not comment on the RenameTab thing, ok? I bet, Jeremy is going to fix that pretty soon. The ScreenCollection is (again) a good example of how much you can do with so few lines. However sometimes this can have downsides, too. I can only imagine .NET developers unfamiliar with
this heavy usage of C#3.0 features staring at the code and thinking something like: WTF, what’s happening here? Personally, I like it, especially the cache aspect of it. I’ve done the .Tag thing far too often now.

Sadly one thing I would have loved to see is missing in the code, the ability to block deactivation or activation. Typical example for this is a requirement forcing the user to save or discard changed data before leaving a Screen. I had this requirement in the last 5 applications I worked on. It would have been interesting to see how Jeremy tackles such a requirement. I’m just assuming that he would use the EventBroker for that …

Enought Screen Mania for today. I hope you’ve enjoyed the ride so far and we’ll rejoin next time when it’s time to take a look at the big guy in the game, the ScreenConductor.

For me personally, the design ‘around’ a Screen is one of the crutial elements for success in
developing a composite UI layer. Why do I think so?

Mostly because it’s one of the central points which connects the UI infrastructure with all the rest of the application, the actual application code. It’s THE INTERFACE that fills you’re framework / infrastructure with life. If you fail here you probably feel the result throughout the complete application. Day to day work happens around that interface and since the UI seems to be one of those places in an application that is very volatile and changes a lot, a Screen design with principles like DRY and OCP in mind will make your life as an application developer much easier.

So what are the basic responsibilities of a Screen?

• First of all it provides content. While a composite UI’s shell provides the hull of the application, the Screen provides the UI to fulfill a business requirement. I think it’s comparable to the relationship between an Asp.Net Masterpage and the aspx pages displayed in its content placeholder (Disclaimer: I’m no Asp.net expert so feel free to correct).
• Controlling Screen Activation. Since the UI infrastructure can’t possibly now what has to happen when a Screen is activated, it delegates the responsibility to the Screen itself. A practical example of the Tell-Don’t-Ask-principle. Interaction with the Command infrastructure mostly happens here.
• Controlling Screen Deactivation / Closing. I’ve seen this in several applications now. A Screen with changed data can only be left / closed when a) changes have been persisted or b) the user votes to discard the changes. Like in point 2. the UI infrastructure can’t possibly know when that’s the case, so it’s delegated.

With those 3 points in mind, let’s take a look at the Screen interface in StoryTeller.

    public interface IScreen
    {
        object View { get; }
        string Title { get; }
        void Activate(IScreeObjectRegistry screenObjects);
        bool CanClose();
    }

Pretty straight forward, isn’t it?. Next question, who is actually implementing the interface? And the answer is surprisingly: It depends! This interface can be implemented for instance by Passive View – or Supervising Controller – style Presenters. It can be implemented by ViewModels in Model-View-View-Model implementations. It can even be implemented by UserControls (though StoryTeller uses this only for very simplistic screens). It’s a very pragmatic solution giving a lot of choice to an application developer on how to interact with the UI infrastructure.

I think that’s a good choice. We, as a community, shouldn’t be dogmatic about MVVM vs. MVP, or the whole No-Code-Behind-debate. Consistency is import but, sticking to a pattern not suited for a particular screen (for instance using Passive View for a screen with a lot of fields) can hurt much more than the (pattern) consistency would justify. Mh, that was a little bit off-topic, wasn’t it?

Most of the Screens in StoryTeller are classical Model View Presenter implementations getting their view injected in the constructor.

    public class SuitePresenter : IListener<TestIconChanged>, ISuitePresenter, IListener<TestAdded>
    {
        private readonly Cache _drivers;
        private readonly ITestExplorer _explorer;
        private readonly ITestService _service;
        private readonly Suite _suite;
        private readonly ISuiteView _view;

        public SuitePresenter(Suite suite, ISuiteView view, ITestExplorer explorer, ITestService service)
        {
            _suite = suite;
            _view = view;
            _explorer = explorer;
            _service = service;

            _view.Presenter = this;
            _drivers = new Cache<Test, ITestLineDriver>(t => _view.AddTest(t, queueTest));
        }

	..........
    }

The structural aspect of the screens isn’t that interesting to me. Standard MVP stuff. The activation however (in particular the usage of IScreenObjectRegistry) looks really interesting. Take a look for yourself:

     public void Activate(IScreenObjectRegistry screenObjects)
     {
            screenObjects
               .Action("Run")
               .Bind(ModifierKeys.Control, Key.D1)
               .To(_presenter.RunCommand).Icon = Icon.Run;
     }

IScreenObjectRegistry will be inspected in a future post. The next post though, will take a closer look at the ScreenCollection. So, if you’re eager to learn more about the diamonds and jewels Jeremy has created in StoryTellers trunk (like I am) rejoin me for the next post when it’s time to go diving again . . .