I’m working on a project for a customer where we are trying to get a new version of a product out the door. We need to add some features to an existing API, but don’t want to break the existing API for existing customers. Common story, common place to be.

However, in adding these new features, we really need to be modifying an existing API to add new options to existing methods. But we find ourselves in a place I’ve seen a number of times: the API tried to be too granular about its arguments. It provided flexibility for optional arguments with overloaded methods. Not a bad thing from an OO perspective. The slippery slope is trying to anticipate how many arguments you might actually need to that method over time and which of those arguments might be optional.

Defining a Clean, Version Tolerant API

Say you start with a simple API like this:

public interface ISomeInterface
{
    void SomeMethod(double alwaysNeeded);
    void SomeMethod(double alwaysNeeded, int optionArg1);
    void SomeMethod(double alwaysNeeded, string optionArg2);
    void SomeMethod(double alwaysNeeded, int optionArg1, string optionArg2);
}

There is one always needed argument, and a couple of optional args. Fine when there are just two options. What about when the list grows to 3, 4, 5, 6? How many overloads do you have to add to cover all the reasonable combinations of those arguments a user might want? The size of your API goes exponential, and the usability of it goes downhill quick.

This is the situation we find ourselves in. And this is why I have long recommended that unless an API is going to be static and always take the same set of arguments, you are better off packaging up those arguments in a single complex argument – a data structure single argument such as the following:

public class MyMethodArg
{
    public double AlwaysNeeded { get; set; }
    public int OptionalArg1 { get; set; }
    public string OptionalArg2 { get; set; }
}

Then you can simplify the interface definition to just the following:

public interface ISomeInterface
{
    void SomeMethod(MyMethodArg arg);
}

Now, over time, you can add additional required or optional arguments without affecting the interface API at all. As long as you write graceful handling for when optional parameters are not set explicitly on the data structure, you have much better ability to change the underlying arguments over time without breaking existing clients. And you have a much cleaner, easier to understand API.

Extension Methods to the Rescue

So then the question becomes: If you find yourself with an API that looks like the original version and you want to move to the cleaner version immediately above, do you have to break all your existing clients to get there? Thanks to extension methods, the answer is no.

Say you have existing clients that have code that depends on the original API. A simple one might look like the following console app:

class Program
{
    static void Main(string[] args)
    {
        ISomeInterface itf = new SomeImplementation();
        // V1 methods - obsolete
        itf.SomeMethod(1.0);
        itf.SomeMethod(1.0,42);
        itf.SomeMethod(1.0,"foo");
        itf.SomeMethod(1.0, 42,"foo");
        // V2 method
        itf.SomeMethod(new MyMethodArg { OptionalArg1 = 42 });
        Console.WriteLine("Press Enter to Exit...");
        Console.ReadLine();
    }
}

For sample purposes, say the original implementation looked like the following:

public class SomeImplementation : ISomeInterface
{
    void ISomeInterface.SomeMethod(double alwaysNeeded)
    {
        Debug.WriteLine("SomeMethod no optional args");
    }

    void ISomeInterface.SomeMethod(double alwaysNeeded, int arg)
    {
        Debug.WriteLine("SomeMethod optional int arg");
    }

    void ISomeInterface.SomeMethod(double alwaysNeeded, string arg)
    {
        Debug.WriteLine("SomeMethod optional string arg");
    }

    void ISomeInterface.SomeMethod(double alwaysNeeded, int arg1, string arg2)
    {
        Debug.WriteLine("SomeMethod optional int and string args");
    }
}

What you can do is use Extension methods to move the old API off the primary interface you want to keep for the long term (assuming there are also other methods and properties on that interface that you want to remain there instead of just defining a new interface with the new API). You could add the following class to your existing project:

public static class SomeInterfaceExtensions
{
    [Obsolete]
    public static void SomeMethod(this ISomeInterface itf, double alwaysNeeded)
    {
        itf.SomeMethod(new MyMethodArg { AlwaysNeeded = alwaysNeeded });
    }

    [Obsolete]
    public static void SomeMethod(this ISomeInterface itf, double alwaysNeeded, int arg)
    {
        itf.SomeMethod(new MyMethodArg { AlwaysNeeded = alwaysNeeded, OptionalArg1 = arg });
    }

    [Obsolete]
    public static void SomeMethod(this ISomeInterface itf, double alwaysNeeded, string arg)
    {
        itf.SomeMethod(new MyMethodArg { AlwaysNeeded = alwaysNeeded, OptionalArg2 = arg });
    }

    [Obsolete]
    public static void SomeMethod(this ISomeInterface itf, double alwaysNeeded, int arg1, string arg2)
    {
        itf.SomeMethod(new MyMethodArg { AlwaysNeeded = alwaysNeeded, OptionalArg1 = arg1, 
                                                                    OptionalArg2 = arg2 });
    }
}

Then, the implementation class can be collapsed to the following:

public class SomeImplementation : ISomeInterface
{
    void ISomeInterface.SomeMethod(MyMethodArg arg)
    {
        Debug.WriteLine("SomeMethod complex arg");
    }
}

The client can remained unchanged against the V1 API thanks to the extension methods, but will now get compiler warnings that the API is obsolete thanks to the Obsolete attributes. But they won’t break. New clients will not even see the old API unless they go looking for it, and then they should be smart enough not to write new code against things marked with the Obsolete attribute when there is a perfectly usable method on the primary API itself.

So this is the approach we are going to use to move forward the original lack-of-forethought API and clean it up for the long term.

Obviously this approach will only work if your clients (that you don’t want to break) are on .NET 3.5. If you could afford to lock them down to just .NET 4.0 or later, you would have another option with C# optional parameters or default values, but that is unlikely for most apps at this point in time.

Wednesday, November 04, 2009 8:51:30 PM (GMT Standard Time, UTC+00:00)
Comments [1]  | 

Last week I had the privilege of speaking at the Sydney .NET User’s Group while in Sydney teaching a WCF Master Class. It was an outstanding group and I spoke on WF 4 and Prism (Composite Application Guidance for WPF and Sliverlight). Had some great questions and discussion with the attendees, which is always what makes a group stand out in my mind.

If you want the slides and demos for the talks, you can find them here:

First Look at WF 4:   Slides   (no pre-built demo code, all on the fly demos in VS 2010 Beta 2)

Building Composite WPF and Silverlight Applications:   Slides    Demos

The other thing that made this group stand out for me (besides the above and the fact that it is run by friend and fellow RD Adam Cogan from SSW Software) was that instead of going out for beers or something else unhealthy afterwards, a small group of us went for a short power walk for some exercise afterwards around the area of the user group meeting. You can see the route we walked here:

http://www.mapmyride.com/route/australia/earlwood/465125612609191527

Nice variation for someone who is trying to lose weight and good chance to keep the technology discussion going with some of the attendees afterwards. Thanks to Adam for organizing!

Wednesday, October 28, 2009 4:41:32 PM (GMT Standard Time, UTC+00:00)
Comments [1]  | 

I’m spending the next two weeks in Australia to teach some classes and speak at some user groups. This week, 12-16 Oct, I am teaching our Architect Master Class through our training partner Readify in Melbourne. Next week I’ll be teaching our WCF Master Class in Sydney 19-23 Oct, also through Readify.

The timing worked out perfectly that I also get to be the guest speaker at a user group in each city as well. On 13 October, I’ll be presenting a talk on Prism at the Victoria .NET User Group. On Wed 21 October, I’ll be giving two sessions at the Sydney .NET User’s Group on Prism and WF 4.

It’s always fun to give talks to user groups, but it is extra special fun to get to give user group talks in other countries. Really looking forward to both, as well as the classes. And spending two weeks in Australia doesn’t suck one bit either. :)

Sunday, October 11, 2009 5:02:10 AM (GMT Standard Time, UTC+00:00)
Comments [2]  | 

I had some good follow on discussions from my recent post on Graceful Shutdown with Ward Bell and Jeremy Miller about how “graceful” my shutdown example really was. They argued a point that I agreed was a big weakness with the approach: sending information back to the shell about whether to shutdown through a command parameter is not a very clean path of communication. Also, my arguments about using a command vs a pub-sub event were difficult to defend. Either one would work fine, but both suffer this same problem of obscure communication paths.

Jeremy also pointed out that the use of Prism CompositeCommands is always a little dirty and hazardous for two reasons. First, they are typically used as globals – a static singleton instance of the CompositeCommand that any control can source and any other part of the app can hook up to through the CompositeCommand.RegisterCommand method. And we all know that globals are evil.

The other problem with CompositeCommands is that it is too easy to have some chunk of code register a child command with the RegisterCommand method and then forget that now the CompositeCommand holds a reference chain back to the child command, the object on which the child command is a member, and the object on which the child command handler method exists.

In my simple example, there was the smell of a potential memory leak – an app that lets you open multiple documents, each document gets its own view and view model, and the view models are the command handlers for composite commands. Since those views are being dynamically created (in this case in response to another composite command for “New”), the registration is being done on the fly as their view models are initialized. So this begs the question of when do they get unregistered so that you don’t leak memory (in the form of residual command references into view models that are no longer being used). Prism commands do not currently use weak references like the Prism events do, although you could modify them to do so without too much difficulty.

You can get the updated code for this post here.

With the original sample code from my last post, it turned out this was not really a problem because the sample provided no way to close a view once opened. But it was just a sample focusing on the communication path for the Closing event after all. But say it was a real app and you were going to allow the user to close a document. I’ve modified the sample to allow closing a document through an X button on the tabs that the documents get opened in.

I didn’t take the time to beautifully style it, so forgive me my artistic ineptitude. But now that there is a mechanism to close the views, presumably the references to the views and view models are released when their document is closed, but if we don’t make sure we call UnregisterCommand in that process, we will have an effective memory leak – the CompositeCommands for Shutdown and Save will be holding references to the view models keeping them from being garbage collected. Each new document we open gets a new view and ViewModel instance, registers it, and over time we would see the memory of this app grow and grow.

So the direct solution is to ensure through whatever means practical to call UnregisterCommand before all refs to the ViewModel go away. Lets take a quick look at the code for this sample to get that done.

I added a data template to the shell where the TabControl is defined to add the X buttons into the tab headers:

<DataTemplate x:Key="ButtonTabItem">
    <DockPanel>
        <Button DockPanel.Dock="Right" 
          Command="{Binding Path=Content.DataContext.CloseCommand, 
          RelativeSource={RelativeSource AncestorType=TabItem}}">X
        </Button>
        <TextBlock Text="{Binding Path=Content.DataContext.DocumentTitle,
           RelativeSource={RelativeSource AncestorType=TabItem}}" VerticalAlignment="Center"/>
    </DockPanel>
</DataTemplate>

You can see the binding code is expecting a CloseCommand to be exposed from the ViewModel which is the DataContext of the view, and the view is the Content of the TabItem. The DocumentEditorView did not have to be modified at all, but the CloseCommand was added to the ViewModel as a DelegateCommand, as well as a Closed event to notify the controller:

public DocumentEditorViewModel()
{
    SaveCommand = new DelegateCommand<object>(OnSave, OnCanSave);
    SaveCommand.IsActive = true;
    Commands.SaveCommand.RegisterCommand(SaveCommand);

    ShutdownCommand = new DelegateCommand<CancelEventArgs>(OnShutdown);
    Commands.ShutdownCommand.RegisterCommand(ShutdownCommand);

     ...
    CloseCommand = new DelegateCommand<object>(OnClose);
 }

public DelegateCommand<object> CloseCommand { get; set; }
public event Action<DocumentEditorViewModel> Closed = delegate { };

private void OnClose(object obj)
{
    // Prompt to save, save document, etc.
    Commands.ShutdownCommand.UnregisterCommand(ShutdownCommand);
    Commands.ShutdownCommand.UnregisterCommand(SaveCommand);
    Closed(this); // Notify controller through an event, could also use a Prism event if others might care...
}

In this case, since the command handling for closing can be collocated with the code that did the registration, it is easy to make sure that we UnregisterCommand as part of the closing process. The controller is the one that takes care of presenting the views in this case, so the event is fired so the controller can choose to do what is appropriate, which in this case is to just remove the view from the region. That takes a bit of convoluted code to locate the view that corresponds to the ViewModel since the two are loosely coupled.

private void OnViewClosed(DocumentEditorViewModel vm)
{
    vm.Closed -= OnViewClosed;
    IRegion region = m_RegionManager.Regions[Constants.DOCUMENTREGION];
    DocumentEditorView viewToRemove = null;
    foreach (var view in region.Views)
    {
        DocumentEditorView docView = view as DocumentEditorView;
        if (docView == null) continue;
        if (docView.DataContext == vm)
        {
            viewToRemove = docView;
            break;
        }
    }
    if (viewToRemove != null)
        region.Remove(viewToRemove);
}

So for this simple example, it was not too terribly hard to make sure a memory leak did not happen with the use of the CompositeCommand once I added the functionality to close a view. However, what you can see emerging here is that the complexity is growing disproportionate to the work that this little sample is really doing. With a large app with many views/ViewModels, lots of commands and cross module communications, etc. this could get out of control pretty quick, and it would be easy to miss a place where you are not unregistering correctly.

The net result of all this is that the use of CompositeCommand works, but is not completely satisfying here, and especially not in a large complex  app. Modifying CompositeCommand to use weak references would be one choice, or switching to Prism events for the communications would be another choice.

Coupled with this challenge of potential memory leaks is the scenario of the previous post – graceful shutdown communications – is a another responsibility relative to view management that really cries out for some centralized management. Then you have the view activation/deactivation that I will talk about in my next post that also requires some common handling, and it turns out that what you really need is a pattern/abstraction that Prism does not yet really provide – you need a screen conductor / director of some sort that keeps track of what views are being presented, when they are activated/deactivated, whether they can close, etc.

Jeremy is working on a chapter for his upcoming book  that will cover an approach to this problem. I and others are trying to wrap our heads around the best way to tackle this problem. Ward Bell has suggested a “Close Service” that is responsible for coordinating the shutdown and he spiked an implementation of this that definitely felt cleaner than doing the back-channel communications through command or event arguments. I’ll be sure to blog more about this as my thoughts gel on it and if I can get a decent implementation put together, or will link to whoever beats me to it publicly first.

But before I get there, I do want to explain the IActiveAware mechanism of Prism, since it was important in getting the application to work correctly as well and is severely under-documented in the Prism docs. So that will be my next post, stay tuned…

You can get the updated code for this post here.

Monday, October 05, 2009 1:22:17 PM (GMT Standard Time, UTC+00:00)
Comments [0]  | 

Part 2 of my interview on workflow foundation, past, present, future, and focus on workflow services is up and available for your listening pleasure (or torture as the case may be).

Wednesday, September 30, 2009 1:00:43 PM (GMT Standard Time, UTC+00:00)
Comments [0]  | 

A couple months ago I recorded an interview on the state of affairs of Windows Workflow Foundation, with the focus on Workflow Services, on Deep Fried Bytes. The recording has been broken into two parts because we talked for quite a while and part one has gone live. You can check it out here:

Monday, September 21, 2009 9:34:22 PM (GMT Standard Time, UTC+00:00)
Comments [0]  | 

When you start building applications the Prism way, your UI logic can be spread out across any number of loosely-coupled, independent modules and their supporting code. This is a good thing in terms of breaking up the functionality of your application into reusable components and being able to distribute the work across multiple developers or teams. However, the decentralizing of the UI logic can lead you to scratch your head frequently when you need to implement some piece of functionality that sort of naturally feels like the main window has to handle it all.

A common requirement that is one of these common head scratchers is what to do when you want to prevent the application from shutting down until all work in progress (unsaved documents, pending downloads, etc.) is complete. This came up (again) with a customer the other day, so I figured it would make a good post (thanks for the idea John :) ).

In a Prism app, the code that performs those actions and manages the state associated with them should be implemented within the modules that are loading into the application, and that code probably belongs in a ViewModel or Controller that is supporting the associated views.

So when the user clicks on the red X to close the application, or invokes some other command from the menu or toolbar that indicates it is time to close the application, you need a clean communication path from the shell down to all chunks of code that may need to vote on whether the application should be allowed to shut down right now.

Picking a Communication Option

Prism offers two loosely-coupled communication mechanisms: Prism events and commands. One approach that might occur to you is to use Prism events and have the shell publish a shutdown event, and have the module code subscribe and handle it. This could work, but part of the pattern of pub-sub events is that the publisher should not know or care if there are any subscribers out there, nor should it care what the subscribers do if they are there.

So if you just wanted to notify the module code that shutdown is happening, you could use a Prism event, but the problem is that you probably need to block the shutdown until they have all done their clean up, and you often need to be able to cancel shutdown if there is unsaved state or incomplete tasks.

One of the key differentiators between events and commands in my mind is that commands represent an action taking place for which there is an expectation that there will be some handling code out there. So for a shutdown communication to the modules, a command is a better way to go. And the way Prism CompositeCommands work, all of the contained command handlers will be invoked before the execution of the command is complete.

In general, a command invoker is not expecting any results back from the handlers. However, to support the cancellation of shutdown, we would need to effectively pass arguments back to the invoker to let it know whether to complete the shutdown. To do this, we can just piggy back on a well-established pattern in WPF and Windows Forms – pass a CancelEventArgs argument as the command parameter, and allow the handlers set the Cancel property of that parameter to true if they don’t want shutdown to happen.

Putting it Together

To demonstrate one way to put this together, I’ve put together a simple Prism application that is like a simple Wordpad of sorts. You can fire it up, open multiple documents in tabs, edit them, and save them independently. You can see the app running below. A few minor bells and whistles include setting the tab header to the document title, and showing “dirty” documents by making their tab header bold/italic. The New command in the toolbar is always enabled, but the Save command is only enabled if the currently active document is dirty. I’ll do a follow on post about this aspect, which uses the  IActiveAware facility of Prism.

The logic code for supporting an individual instance of an editor views is fully implemented in the ViewModel class for the view, DocumentEditorViewModel.

There is also a controller class that takes care of creating the instances of the view when the New command is invoked.

I’m not going to drill into all aspects of the application architecture, but you can take a look at it as a fairly well organized example of a Prism app if you download the sample code. The basic project structure is shown below. I have a ShellApp that is the WPF application project. It contains a bootstrapper like most Prism apps that gets things going by presenting the shell. The MainWindow class is the shell window, and has two regions in it: a MainToolbarRegion and a DocumentRegion. The toolbar is (not surprisingly) a Toolbar, and the document region is just a TabControl. There is also a StatusBar at the bottom to show an indication of why close is not happening if one of the documents needs to be saved.

The SomeApp.Common is just a class library that contains the shared types between the shell and the modules – specifically some constants and the commands in this case.

The SomeDocumentModuleLib is the only module in this example, and contains the SomeDocumentModule, the DocumentController, the DocumentEditorViewModel, and its supporting DocumentEditorView. The view class (DocumentEditorView) is very simple, just a TextBox and the IActiveAware implementation I’ll talk about in a subsequent post.

The controller is called by the module’s Initialize method to get things going, and it populates the toolbar with the New and Save command buttons using Prism regions, and also has the handling code for New, which simply creates a new instance of a view and a viewmodel and marries them (sets the view’s DataContext = viewmodel).

The ViewModel is where the action is at for both the Save command and the Shutdown command that I am really trying to focus on here.

Notifying ViewModels of Shutdown

To get the word out to the ViewModel instances for open documents when someone goes to close the application, you have to first start with the WPF Window.Closing event that is fired. That event passes a CancelEventArgs allowing you to prevent the closing of the Window. But first off we don’t want to do logic handling in a view (the Shell), and second, the Shell is supposed to be fairly stupid about what the app components want to do about the event anyway. So we need a clean way to dispatch the event out as a command and get results back to decide whether to let the close happen or not.

The way I chose to approach it is to use a Prism CompositeCommand as the form of communication. Each ViewModel (or other interested background code) can provide a command implementation for that command, and in that implementation they can decide and modify the argument that is passed to indicate whether they are OK with the shutdown or not.

So starting at the source, we first have to handle the Closing event at the Window level:

<Window x:Class="ShellApp.MainWindow"
    ... 
    Closing="OnWindowClosing"
     >

To dispatch the command to others, we need a command definition.

public static class Commands
{
    ...
    public static readonly CompositeCommand ShutdownCommand = new CompositeCommand();
}

The ShutdownCommand is the one we are focusing on here.

The code behind handler for the Closing event basically needs to execute the Shutdown event and pass along the CancelEventArgs as a command parameter, allowing the handlers of the command to potentially set Cancel to true:

private void OnWindowClosing(object sender, CancelEventArgs e)
{
    if (Commands.ShutdownCommand.CanExecute(e))
        Commands.ShutdownCommand.Execute(e);
    if (e.Cancel)
        m_StatusText.Text = "One or more documents need saving before you can shutdown";
}

The way the CompositeCommand works in Prism, it will go out to all command handlers that register with the command and invoke their handling code.

The DocumentEditorViewModel provides the implementation of that command, one for each instance of an open document:

public DocumentEditorViewModel()
{
    ...
    ShutdownCommand = new DelegateCommand<CancelEventArgs>(OnShutdown);
    Commands.ShutdownCommand.RegisterCommand(ShutdownCommand);
}

public DelegateCommand<CancelEventArgs> ShutdownCommand { get; set; }

private void OnShutdown(CancelEventArgs args)
{
    if (IsDirty)
    {
        args.Cancel = true;
    }
}

The view model also maintains the dirty state of the document and uses it to drive both the enablement of the Save command, as well as to decide whether to allow shutdown. If the document is dirty, it simply sets the CancelEventArgs.Cancel property to false. Since the same argument is passed by reference to all the handlers of the command, if any one sets it to true, Closing will not happen.

That’s all there is to it. Piece of cake, right? Clean, simple, loosely coupled communications that achieves the end goal. Shell doesn’t have to have any knowledge of what it takes to allow the app to shut down, and the individual chunks of code that care don’t have to know about each other.

Any questions or comments, please post a comment and I’ll get back to you.

You can download the full sample app code here.

Saturday, September 05, 2009 4:35:02 PM (GMT Standard Time, UTC+00:00)
Comments [2]  | 

I gave two talks in SoCal this week, one at the San Diego .NET User Group Connected Systems SIG in San Diego and one at the South Bay .NET User Group in Torrance.

The San Diego talk was titled Exercise WCF Best Practices and was a collection of practices with context and explanation on employing features and capabilities in the WCF stack in the best way. I talked about server side considerations including interface and layer separation, instancing model, exception handling, security model, and hosting, as well as client side considerations such as proxy creation, caching of proxies, and exception handling on the client side.

The slides and demos for this talk can be downloaded here:   Slides    Demos

The Torrance talk was A First Look at WF 4, which covered all the new features coming in WF 4. I covered the new designer, declarative XAML workflows, new activities in the base activity library, the flowchart workflow model, hosting of workflows, arguments, variables, and expressions, workflow services, and runtime improvements to name a few things.

The slides and demos for this talk can be downloaded here:   Slides    Demos

Sunday, August 16, 2009 3:47:13 PM (GMT Standard Time, UTC+00:00)
Comments [0]  |