Do not use boolean method parameters

What!? Why not!?

The declaration of a method with a boolean parameter looks simple enough, what could be wrong with it?

void Dispose(bool disposing) { ... }

The problem is not in the declaration (I picked this example because it is horrible in more ways than one), it is in the readability of the calling code.

obj.Dispose(true);

It is not immediately obvious what this true means.Even if the method name had some meaning in it, it would still probably be vague at best.

A solution to this would be to make explicit what the boolean represents. That could either mean that you make two methods, one that behaves as if the boolean was false and one that behaves as if the boolean was true.

Another option is to create an enum that gives you two names to work with:

public enum DisposeOptions
{
    DisposeManagedAndUnmanagedResources,
    DisposeUnmanagedResourcesOnly
}

True, it is a bit more work, but it reads so much better when you see the calling code:

obj.Dispose(DisposeOptions.DisposeManagedAndUnmanagedResources);

There is no guessing what this does, is there.

Of course there may be exceptions. One I can think of is when the method name clearly explains the purpose of the boolean parameter – the only parameter for the method – this goes south with multiple parameters.

Enable(true);

Not something you would write in C# perhaps, but valid for C++.

The goal is to create code that reads nice, something you can understand when you saw it for the first time (or revisit it after 6 months). Arguments that it’s too much typing are completely invalid in my opinion. You read that code way more often than you write it, so make that a nice experience.

 

The context of anonymous methods/lambda’s is lost on async proxy calls in SL3 (Updated)

EDIT: This issue was caused by using cached singletons for each proxy (see comments). So the context of anonymous method works correctly, it just appeared it didn’t because multiple event handler (lambda’s) were registered to the same proxy instance.

We’re building an SL3 application that gets its data from a WCF (Ria) Service. The application uses a standard generated proxy (SlSvcUtil.exe) and all calls are done using the familiar async pattern: call a begin method and wait for the completed event. In our SL3 application we have some layers on top of this Proxy:

1) The ServiceAgent – manages the service proxy and transparently recreates it when it is in a Faulted state. It subscribes to the completed event on the proxy and promotes this to the caller (repositories).
2) The Repositories – exposes centralized and cached data access divided bij functional area / domain.
3) The Model (per module) – Each module in the app implements the MVVM pattern and its model accesses the repositories and maps the data from service contracts to module-specific view entities.

Because all data fetching is async we use an eventing mechanism (similar to INotifyPropertyChanged and INotifyCollectionChanged) to communicate’the ‘completed’ event from the proxy upward through the application.

It was in the implementation of the repositories that I first discovered that something was wrong with the context in which our ‘completed’ events were raised. Our implementation looked something like this (pseudo code):

public DataEntity GetDataEntity(Guid Id)
{
    DataEntity retVal = new DataEntity();

    using(var proxy = _serviceAgent.GetProxy<RequestDataContract, ResponseDataContract>())
    {
        proxy.RegisterCompletedHandler( (response) =>
            {
                retVal.Property1 = Response.Property1;
                retVal.Property2 = Response.Property2;
                retVal.Property3 = Response.Property3;
            });
        proxy.BeginRequest(new Request(id));
    }
    return retVal;
}

Initially this method returns an empty object that gets mapped to an empty ViewEntity and bound to the UI. When the proxy reports the service call is completed the ‘CompletedHandler’ is called implemented by the lambda and provides access to the response of the service call. Now the empty DataEntity is filled and these changes are propegated to the ViewEntity (think INotifyPropertyChanged) and in turn the Viewentity notifies its changes to the UI (also INotifyPropertyChanged). This works, no problem.

Untill you place another call to the same repository method while the first is still ‘running’. Then the ‘context’ the lambda needs to fill the retVal is lost and ‘overwritten’ by the second call. So it may be very well that the result of the first call is written to the retVal of the second call. You can imagine the strange behavior you’ll get in your app (and how long it takes to figure out what the problem is ;-).

The solution that I’ve found is to use the userState that the proxy allows you to sent with a method call. The pseudo code will look something like this:

public DataEntity GetDataEntity(Guid Id)
{
    DataEntity retVal = new DataEntity();

    using(var proxy = _serviceAgent.GetProxy<RequestDataContract, ResponseDataContract>())
    {
        proxy.RegisterCompletedHandler( (response, userState) =>
            {
                DataEntity de = (DataEntity)userState;
                de.Property1 = Response.Property1;
                de.Property2 = Response.Property2;
                de.Property3 = Response.Property3;
            });
        proxy.BeginRequest(new Request(id), retVal);
    }
    return retVal;
}

Now the correct retVal is passed as userState allong with the service call to the proxy and the completed (event) handler will now have access to it when it is called and will be able to set the property values.

I was very suprised that this occurred in my code and it may very well be that I’m doing things wrong, but I don’t see it. Any suggestions are welcome.

Hope it helps.

Services with a twist

On the project I am currently working on we have several layers of processing going on:

  • External Systems (silos)
    These are the legacy systems that contain all the information.
  • A service layer (WCF)
    These Domain Services expose the legacy systems transparently. Talking to these services gives you no clue which legacy system is used. Sometimes its more than one.
  • An Enterprise Service Bus (BTS2006R2/ESB)
    Positioned as messaging middle ware. For the most part completely transparent to the clients.
  • Client / Front end applications (SL3)
    User applications that consume domain services through the ESB.

In order to let our domain services perform optimal with the many calls that they’ll receive and to make them as versatile as possible, we’ve decided to do two additional things:

  • Support Batching
    Most service methods can handle multiple requests at a time. Its like taking your normal service operation contract and putting a collection around it. This enables the client to (for instance) resolve multiple IDs in one single call / round trip. It is the classical choice between multiple calls with small messages or less calls with larger messages. The client can now choose how it wants to interact with the service.
  • Support Prefetching
    We define a rich data model that each of these domain services work with. These services go beyond just ‘Customers’ or just ‘Orders’. Because all data within a domain service is so related / connected we felt that it would be best to keep it all in one service. But you do not always want all ‘Orders’ and all ‘OrderItems’ and all ‘Product’ for a ‘Customer’. So we allow most service operations to specify what we have called ‘Prefetch paths’. Basically you call the service operation and you specify what relations of the root entity that operations serves up you want also to be included in the response. So you could call GetOrders with only  the ‘OrderItems’ prefetch key. That would result in all Orders and OrderItems for a Customer. The client once again is in control of what data is retrieved to suit its needs.

We understand that implementing services this way is somewhat non-standard (I have never seen it done before), but we feel that it provides a lot of flexibility to its clients. For a service to be reusable in a number of different contexts, we believe it should be more flexible that your normal, plain vanilla service. Nontheless, we really like some community feedback on this design and would appreciate any suggestions you might have.

How to implement catch (Exception e)?

How often did you see a C# catch(Exception e) statement in code? How often did you write it yourself?

I know I do it, even when I know I shouldn’t. Why?

Because its so easy! Doing it right is hard(er) or at least take much more code you have to repeat over and over again.

But its not something that you’d be proud of (I’m not).

So, I thought it was time to change that. But how? I definitely don’t want to rewrite a lot of code for each try-catch-finally block.

First lets take a look at error handling. When do you really handle an error? Almost never I dare to say. I’ve only encountered one occasion where I really handled an exception (a dead-lock exception from SQL-Server: I waited a random amount of time a retried – three times. After that I just let the exception bubble up).

What does your error handling code look like? I bet it looks something like this:

    try
    {
        // real code here…
    }
    catch(Exception e)
    {
        Logger.LogException(e);
    }

I don’t see the handling part in this 😉 why do we call this error handling? BTW don’t call throw e in the catch block. I rewrites the call stack and you loose the original call stack.

But there’s a whole range of exceptions you don’t want to catch. AccessViolationException? ExecutionEngineException?

Those indicate situations you can’t fix anyway.

How about InvalidCastException and NullReferenceException?

Those exceptions indicate some technical error and are an indication of plain bugs. I wouldn’t want to catch those in my code (only at AppDomain level to log them).

The good news is that the BCL team is doing something about this in .NET 4.0. But even in .NET 4.0 catch(Exception e) is still not a good idea.

But how do we handle exceptions the easy way (the catch(Exception) way) but filter on the really important exceptions? We can take the solution of the BCL team one step further.

The following code is not production code but it demonstrates an idea to handle exceptions correctly once and for all.

    public class ErrorHandler
    {
        public delegate void TryCallback();
        public delegate void ExceptionCallback(Exception e);
        public delegate void FinallyCallback(bool? exception);

        public ErrorHandler()
        {
            // add "really" fatal exceptions by default.
            FatalExceptions.Add(typeof(AccessViolationException));
            FatalExceptions.Add(typeof(ExecutionEngineException));
        }

        private List<Type> _fatalExceptions = new List<Type>();
        public IList<Type> FatalExceptions
        {
            get { return _fatalExceptions; }
        }

        public bool IsFatalException(Type exceptionType)
        {
            if (!typeof(Exception).IsAssignableFrom(exceptionType))
            {
                throw new ArgumentException("Specified type is not (derived from) System.Exception.", "exceptionType");
            }

            return (_fatalExceptions.FindIndex(e => e.GetType() == exceptionType) != -1);
        }

        public bool? TryCatchFinally(TryCallback @try, ExceptionCallback @catch, FinallyCallback @finally)
        {
            bool? handleException = null;

            if (@try == null)
            {
                throw new ArgumentNullException("@try");
            }

            try
            {
                @try();
            }
            catch (Exception e)
            {
                handleException = HandleException(ref e);

                if (@catch != null && !IsFatalException(e.GetType()))
                {
                    @catch(e);
                }

                if (handleException != null)
                {
                    if (handleException == true)
                    {
                        throw e;
                    }
                    else
                    {
                        throw;
                    }
                }
            }
            finally
            {
                if (@finally != null)
                {
                    @finally(handleException);
                }
            }

            return handleException;
        }

        public bool? HandleException(ref Exception e)
        {
            bool? result = null;

            if (e != null)
            {
                if (IsFatalException(e.GetType()))
                {
                    // throw
                    result = false;
                }
                else
                {
                    // TODO: call EntLib exception policy

                    result = false; // for now
                }
            }

            return result;
        }
    }

The HandleException method is where it gets decided whether an exception is handled and how. This is also the place to integrate EntLib if you desire. The return value of the HandleException can be null (do nothing), false (call throw) or true – meaning the exception has been replaced (exception wrapping) and throw e should be called. You could elaborate the catch callback to include retries of the @try code when you actually handle an exception (like the dead lock example earlier).

You could use this code as follows:

    public void MethodThatCouldGoWrong(string someParameter)
    {
        ErrorHandler errorHandler = new ErrorHandler();
        errorHandler.FatalExceptions.Add(typeof(InvalidCastException));
        errorHandler.FatalExceptions.Add(typeof(NullReferenceException));

        errorHandler.TryCatchFinally(
            delegate()  // try
            {
                // do something here that causes an exception
            },
            delegate(Exception e) // catch
            {
                // handle the exception e
            },
            null    // finally
            );
    }

This code will not call the catch callback on AccessViolationException, ExecutionEngineException, InvalidCastException and NullReferenceException.

You probably don’t want to instantiate the ErrorHandler class each time you need it – you could make it static as long as you add all fatal exception during initialization of that static instance. Then its a matter of calling the TryCatchFinally method and doing your processing using anonymous delegates (I think in this case its more readable than lambdas). You can even pass null to the @catch callback if you don’t have any custom handling to perform but still get your exceptions ‘handled’.

So its a start. Maybe not perfect.

Thoughts?

Why do we not design a class like this?

I started learning WPF some time ago and the first thing that struck me was the sheer number of properties available on these classes. It turns out that those properties are mainly there to make support for Xaml (declaritive programming) easier/better. But even before WPF, WinForms too had its share of properties on its classes.

 

So I wondered why would we want to have so many Font-properties on a class in WPF; at least in WinForms its on a Font object and the Form/Control only has a Font property (the answer has probably to do with Xaml -again).

 

To be more generic: why do we not (in general) design our class properties to be grouped in functional related groups and make these groups class properties themselves?

 

So instead of (public fields used for clarity):

 

public class MyClass
{
public int MinWidth;
public int MinHeight;
public int MaxWidth;
public int MaxHeight;

// …more properties
}

 

Why don’t we make code like this:

 

public class MyClass
{
public Dimension Dimension = new Dimension();

public struct Dimension
{
public int MinWidth;
public int MinHeight;
public int MaxWidth;
public int MaxHeight;
}

// …more property groups
}

 

For classes with a lot of properties this would make things a little more navigatable for the user of that class (i would think). When there are several pages of intellisense worth of properties (in the first example) you would be able to reduce that to only a handfull of groups. Note that I propose a property group as a struct: its merely a container for properties and has no functionality of its own.

 

One of the downsides of this approach could be that accessing the main class from a property implementation in a property group requires passing that reference to all property groups. On the otherhand: most property implementations are pretty simple anyway…

 

Thoughts?

Double check locking optimization

While I was looking for something completly different I stumbled upon the threading best practices on msdn(2).
http://msdn2.microsoft.com/en-us/library/1c9txz50.aspx


I noticed an optimization for the double check locking pattern that I use a lot. Instead of:


if (x == null)
{
    lock (lockObject)
    {
        if (x == null)
        {
            x = y;
        }
    }
}


you can also write


System.Threading.Interlocked.CompareExchange(ref x, y, null);


It performs better but is a bit less readable (in my view).
One of those “nice to know”s.

DataSet Manager

Why are OR-mappers cool? I dont know? My experience with them has been limited and the time I did use them the support for common constructs was very poor (at best): I don’t think its a good idea for a OR-mapper to caugh up a SQL select query for each instance that needs to go in a collection. The framework should be able to retrieve any hierarchy of data in one round trip (not counting the sceanrio where you have to decide how big the data packet may get versus how many roundtrips are optimal). Also I believe the OR-Mapper problem domain is two fold: 1) you need a good data access layer that supports all the features the required for a "good" OR-mapper and 2) you need the OR-mapping itself, map relational data to objects and back, which is a relatively simple problem to solve.

So I started thinking about the data access layer. I’m a big fan of typed DataSets. If you know your VS.NET you can whip up a typed DataSet within 5 minutes. My assumtion is that the data access layer works with (typed) DataSets. Also I propose to put your application data model in one type DataSet. For instance, You put the complete datamodel of Northwind into one typed "Nortwind" DataSet. If you have a really big solution you could work with subsets for each sub-system.

Now I want to be able to express my data queries in the same ‘entities’ defined in my application typed DataSet (Northwind). Why would an application programmer have to express his data requests in a different "language" than his application data model? Now we need an entry point that will handle our data requests and knows about our application data model. Enter the DataSet Manager.

The way the DataSet Manager retrieves data is by using the structure defined in the (typed) DataSet. It needs a copy of this structure as its data model. For now we assume that this application model reflects the physical data model in the database. A "Real" mapper would allow a certain abstraction here, allowing your application business entities to be subsets (or combined) database entities. The DataSet manager would have (overloaded) methods to fecth data for a (running) typed application DataSet. For instance "Fill up the (Northwind.)Empoyees table", "Fetch all orders handled by this Employee", make changes to the dataset and save.

In the following code examples we assume we have a typed DataSet named Northwind with the complete Northwind database schema.

// create the DataSetManager and initialize the DataModel
DataSetManager mgr = new DataSetManager();
mgr.CreateDataModel(new Northwind(), "Initial Catalog=Northwind");

This code creates a new DataSetManager and initializes the instance with the application data model to use and a connection string to the physical database. Inside the DataSetManager the schema of the (typed) DataSet is analysed and the DataSetManager creates DataAdapters (in this prototype) for each DataTable. The DataSetManager is ready.

// load all Employees data into an empty dataset
Northwind dataSet = new Northwind();
mgr.Fill(dataSet, dataSet.Employees);

Notice the second Northwind DataSet instance. The first was passed to the DataSetManager as a schema, this one is used (by the application programmer) for actually storing data. We ask the DataSetManager to fill up the Employees table and pass it the running DataSet and a reference to the table definition. Because we use typed DataSets both are contained in one instance (thats what makes a DataSet typed). All methods of the DataSetManager take a DataSet as a first parameter. This allows for seperation of data holder and data definition. The DataSetManager will build a "Select * from Employees" query for this method call and writes the results back to the (running) DataSet.

But wait a minute. If EnforceConstraints is set to true this won’t work. The lack of data in the other tables the Employee table has a DataRelation with will cause the contraints to fail. Not quite so. The DataSetManager knows about the schema and therefor knows about these relations too. It examines the content of the passed dataset and dissables these contraints that ‘point’ to empty tables. If you pass in a dataset with its EnforceConstraints set to false, the DataSetManager does nothing.

// find all Orders for the first Employee
Northwind.EmployeesRow employee = dataSet.Employees[0];
mgr.Expand(dataSet, employee, DataSetManager.FindRelation(dataSet.Employees, dataSet.Orders));

We retrieve a reference to an Employee and ask the DataSetManager to expand for this Employee instance (DataRow) using the relation between Employees and Orders. We use a helper method to find the DataRelation between these tables. Again the order data concerning the employee is placed in the passed dataset.

// change some data
employee.Notes = String.Format("Handled {0} orders.", dataSet.Orders.Count);
// update all changes made to the dataset
mgr.Update(dataSet);

Now we change some data in the dataset (on the employee) and ask the DataSetManager to persist the changes back to the database. Using the standard DataSet.GetChanges method and using a DataAdapter the empoyee is updated in the database.

These are the method (overloads) the DataSetManager supports:

public DataSet DataModel{get;}
public void CreateDataModel(DataSet dataModel, string
connectionString)
public int
Fill(DataSet dataSet)
public int
Fill(DataSet dataSet, DataTable table)
public int
Fill(DataSet dataSet, DataRelation relation)
public int
Expand(DataSet dataSet, DataTable table)
public int
Expand(DataSet dataSet, DataRow row)
public int
Expand(DataSet dataSet, DataRelation relation)
public int
Expand(DataSet dataSet, DataRow row, DataRelation relation)
public int
Update(DataSet dataSet)
public int Update(DataTable table)

This prototype was written using .NET 1.1 and therefor no generics are used. But in a future version this would certainly be an option for added type safety. One thing thats missing from this prototype is where-clauses. This is one of the problems i’m still wresteling with. How would you express filter criteria using application entities? I’ve considered Query by example but abandoned that path. The problem with QbE is that you would introduce yet another instance of the application typed DataSet used for holding the filter criteria. And the other problem is that complex filters are difficult to express using QbE. The only other option would be to define yet another proprietary object model for expressing filter criteria.

Also notice that this is no OR-mapper (yet). Its just a really intuitive way to work with your application data. The OR-bit would map back and forth between your application typed DataSet and your (domain) objects. The real power of OR-mappers is not in the mapping part but in the data access layer.

So I would really like to hear your comments, suggestions and objections and if you want to see the DataSetManager internals drop me a line at obiwanjacobi@nospam_hotmail.com (remove the nospam_ ;-).

Service Container

Now the Service Container (Inversion of Control and Dependency Injection) concepts are being adopted by the Microsoft Pattern & Practices group in their CAB and EntLib frameworks, maybe I can talk about a service container implementation I made a few months ago (BTW: A service is a course-grained piece of reusable functionality and not -necessarily- a web service!).

I noticed that everyone who has made a service container (or service locator) framework implemented a custom container interface. But the System.ComponentModel contains a decent IServiceProvider interface that is a suitable client interface. It defines one method GetService that takes a Type parameter to specify the service (interface) type. Visual Studio uses a service container when (form/web) controls are hosted on a designer surface.

So I set out to design the basic structure that is needed for building a service container. After examinig the System.ComponentModel namespace further an IComponent, IContainer and an ISite interface came to light. It appears that these interfaces are used in the standard service container mechanism that is already present in the .NET framework.

The (I)Container manages a collection of (I)Component instances (the Container is NOT a ServiceContainer). When a Component is added to a (and only one) Container it is ‘sited’. A (I)Site is what ties a Component to its Container. Notice that the ISite interface is derived from IServiceProvider interface. So, whenever the Component needs a service it only needs to ask its Site using the GetService method for the service it requires.

The default .NET implementation creates a no-functionality Site instance for each Component that is added to a Container. Luckily for us there’s a virtual method on the Container class (CreateSite) we can override to create a Site of our own making. We need to because we still have no ServiceContainer so far and the default implementation provider by the System.ComponentModel doesn’t provide in one, either.

The way I see it is that the Site provides a way to give each Component a unique context and because the Site already implements the IServiceProvider interface it is the logical place to place the ServiceContainer. My design explicitly defines a ServiceContainer class but logically the Site and ServiceContainer could be thought of as one and the same. This means that it is possible to regulate the service implementations each component has access to through its Site.

This means, for example, that if you have a WebPart page and you bootstrap each WebPart (=Component) to a Container, you can control what services are provided to each WebPart. Or if you have a Domain Object Model (=Component) and bootstrap each instance to a Container, you could control the way these instances perform their tracing, because you control the actual Trace Service implementation used for these objects. Must be said that I assume that only a Service interface is published to the clients (Components) not its implementation class.

But how does the framwork know what services to load for a specific component? The framework looks in the .config file for that. The .config file contains a section that describes services. What classes to use and maybe some service specific configuration settings. It also contains a service profile section. A service profile is a list of services that is loaded into a ServiceContainer. At this point there’s also room to specify custom service config settings. Finaly there’s a context binding section. This section maps (for instance) a Component’s name to a service profile that describes the services available for that Component. Future implementations of the framework will probably also include a service policy section to describe settings like lifetime management and other runtime aspects. Lifetime management of the Service instances is not implemented yet. At the moment the Service instance is created (on demand) and cached in the ServiceContainer. Singleton or PerCall (or custom) instance management is something you’ll want to have eventually.

What will happen if a Component requests a service that is not available in its Site/ServiceContainer. The framework  allows for a Component hierarchy, where a Component may host a Container that contains their child Component instances. So, if a service request can not be satisfied, it is passed to the parent ServiceContainer and so on, untill the root ServiceContainer is reached. This also implies that service clients (Components) can handle the absence of a service they request (handling this scenario can involve throwing an exception ofcourse ;-).

The root ServiceContainer also contains the Services used by the framework itself. The way the framework obtains its configuration settings is implemented as a service, which gives you the option to replace the configuration source.

Take a look at the gotdotnet workspace (if you’re still interested 😉 where you can download a short ppt and access the source code.Future plans for this framework include incorporating the ObjectBuilder (providing a free DI framework) and providing an alternate Configuration Service for the EntLib configuration app block.

Any thoughts, suggestions or comments are most welcome.