Overview

The Unit of Work is a common design pattern used to manage the state changes to a set of objects. A unit of work abstracts all of the persistence operations and logic from other aspects of an application. Applying the pattern not only simplifies code that possess persistence needs, but it also makes changing or otherwise swapping out persistence strategies and methods easy.

A basic unit of work has the following characteristics:

• Register New - registers an object for insertion.
• Register Updated - registers an object for modification.
• Register Removed - registers an object for deletion.
• Commit - commits all pending work.
• Rollback - discards all pending work.

Extensions

The basic design pattern supports most scenarios, but there are a few additional use cases that are typically not addressed. For stateful applications, it is usually desirable to support cancellation or simple undo operations by using deferred persistence. While this capability is covered via a rollback, there is not a way to interrogate whether a unit of work has pending changes.

Imagine your application has the following requirements:

• As a user, I should only be able to save when there are uncommitted changes.
• As a user, I should be prompted when I cancel an operation with uncommitted changes.

To satisfy these requirements, we only need to make a couple of additions:

• Unregister - unregisters pending work for an object.
• Has Pending Changes - indicates whether the unit of work contains uncommitted items.
• Property Changed - raises an event when a property has changed.

Generic Interface

After reconsidering what is likely the majority of all plausible usage scenarios, we now have enough information to create a general purpose interface.

public interface IUnitOfWork<T> : INotifyPropertyChanged where T : class
{
    bool HasPendingChanges
    {
        get;
    }
    void RegisterNew( T item );
    void RegisterChanged( T item );
    void RegisterRemoved( T item );
    void Unregister( T item );
    void Rollback();
    Task CommitAsync( CancellationToken cancellationToken );
}

Base Implementation

It would be easy to stop at the generic interface definition, but we can do better. It is pretty straightforward to create a base implementation that handles just about everything except the commit operation.

public abstract class UnitOfWork<T> : IUnitOfWork<T> where T : class
{
    private readonly IEqualityComparer<T> comparer;
    private readonly HashSet<T> inserted;
    private readonly HashSet<T> updated;
    private readonly HashSet<T> deleted;

    protected UnitOfWork()
    protected UnitOfWork( IEqualityComparer<T> comparer )

    protected IEqualityComparer<T> Comparer { get; }
    protected virtual ICollection<T> InsertedItems { get; }
    protected virtual ICollection<T> UpdatedItems { get; }
    protected virtual ICollection<T> DeletedItems { get; }
    public virtual bool HasPendingChanges { get; }

    protected virtual void OnPropertyChanged( PropertyChangedEventArgs e )
    protected virtual void AcceptChanges()
    protected abstract bool IsNew( T item )
    public virtual void RegisterNew( T item )
    public virtual void RegisterChanged( T item )
    public virtual void RegisterRemoved( T item )
    public virtual void Unregister( T item )
    public virtual void Rollback()
    public abstract Task CommitAsync( CancellationToken cancellationToken );

    public event PropertyChangedEventHandler PropertyChanged;
}

Obviously by now, you've noticed that we've added a few protected members to support the implementation. We use HashSet<T> to track all inserts, updates, and deletes. By using HashSet<T>, we can easily ensure we don't track an entity more than once. We can also now apply some basic logic such as inserts should never enqueue for updates and deletes against uncommitted inserts should be negated. In addition, we add the ability to accept (e.g. clear) all pending work after the commit operation has completed successfully.

Supporting a Unit of Work Service Locator

Once we have all the previous pieces in place, we could again stop, but there are multiple ways in which a unit of work could be used in an application that we should consider:

• Imperatively instantiated in code
• Composed or inserted via dependency injection
• Centrally retrieved via a special service locator facade

The decision as to which approach to use is at a developer's discretion. In general, when composition or dependency injection is used, the implementation is handed by another library and some mediating object (ex: a controller) will own the logic as to when or if entities are added to the unit of work. When a service locator is used, most or all of the logic can be baked directly into an object to enable self-tracking. In the rest of this section, we'll explore a UnitOfWork singleton that plays the role of a service locator.

public static class UnitOfWork
{
    public static IUnitOfWorkFactoryProvider Provider
    {
        get;
        set;
    }
    public static IUnitOfWork<TItem> Create<TItem>() where TItem : class
    public static IUnitOfWork<TItem> GetCurrent<TItem>() where TItem : class
    public static void SetCurrent<TItem>( IUnitOfWork<TItem> unitOfWork ) where TItem : class
    public static IUnitOfWork<TItem> NewCurrent<TItem>() where TItem : class
}

Populating the Service Locator

In order to locate a unit of work, the locator must be backed with code that can resolve it. We should also consider composite applications where there may be many units of work defined by different sources. The UnitOfWork singleton is configured by supplying an instance to the static Provider property.

Unit of Work Factory Provider

The IUnitOfWorkFactoryProvider interface can simply be thought of as a factory of factories. It provides a central mechanism for the service locator to resolve a unit of work via all known factories. In composite applications, implementers will likely want to use dependency injection. For ease of use, a default implementation is provided whose constructor accepts Func<IEnumerable<IUnitOfWorkFactory>>.

public interface IUnitOfWorkFactoryProvider
{
    IEnumerable<IUnitOfWorkFactory> Factories
    {
        get;
    }
}

Unit of Work Factory

The IUnitOfWorkFactory interface is used to register, create, and resolve units of work. Implementers have the option to map as many units of work to a factory as they like. In most scenarios, only one factory is required per application or composite component (ex: plug-in). A default implementation is provided that only requires the factory to register a function to create or resolve a unit of work for a given type. The Specification pattern is used to match or select the appropriate factory, but the exploration of that pattern is reserved for another time.

public interface IUnitOfWorkFactory
{
    ISpecification<Type> Specification
    {
        get;
    }
    IUnitOfWork<TItem> Create<TItem>() where TItem : class;
    IUnitOfWork<TItem> GetCurrent<TItem>() where TItem : class;
    void SetCurrent<TItem>( IUnitOfWork<TItem> unitOfWork ) where TItem : class;
}

Minimizing Test Setup

While all of factory interfaces make it flexible to support a configurable UnitOfWork singleton, it is somewhat painful to set up test cases. If the required unit of work is not resolved, an exception will be thrown; however, if the test doesn't involve a unit of work, why should we have to set one up?

To solve this problem, the service locator will internally create a compatible uncommitable unit of work instance whenever a unit of work cannot be resolved. This behavior allows self-tracking objects to be used without having to explicitly set up a mock or stub unit of work. You might be thinking that this behavior hides composition or dependency resolution failures and that is true. However, any attempt to commit against these instances will throw an InvalidOperationException, indicating that the unit of work is uncommitable. This approach is the most sensible method of avoiding unnecessary setups, while not completely hiding resolution failures. Whenever a unit of work fails in this manner, a developer should realize that they have not set up their test correctly (ex: verifying commit behavior) or resolution is failing at run time.

Examples

The following outlines some scenarios as to how a unit of work might be used. For each example, we'll use the following model:

public class Person
{
    public int PersonId { get; set;}
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

Implementing a Unit of Work with the Entity Framework

The following demonstrates a simple unit of work that is backed by the Entity Framework:

public class PersonUnitOfWork : UnitOfWork<Person>
{
    protected override bool IsNew( Person item )
    {
        // any unsaved item will have an unset id
        return item.PersonId == 0;
    }
    public override async Task CommitAsync( CancellationToken cancellationToken )
    {
        using ( var context = new MyDbContext() )
        {
            foreach ( var item in this.Inserted )
                context.People.Add( item );

            foreach ( var item in this.Updated )
                context.People.Attach( item );

            foreach ( var item in this.Deleted )
                context.People.Remove( item );

            await context.SaveChangesAsync( cancellationToken );
        }
        this.AcceptChanges();
    }
}

Using a Unit of Work to Drive User Interactions

The following example illustrates using a unit of work in a rudimentary Windows Presentation Foundation (WPF) window that contains buttons to add, remove, cancel, and apply (or save) changes to a collection of people. The recommended approach to working with presentation layers such as WPF is to use the Model-View-View Model (MVVM) design pattern. For the sake of brevity and demonstration purposes, this example will use simple, albeit difficult to test, event handlers. All of the persistence logic is contained within the unit of work and the unit of work can report whether it has any pending work to help inform a user when there are changes. The unit of work can also be used to verify that the user truly wants to discard uncommitted changes, if there are any.

public partial class MyWindow : Window
{
    private readonly IUnitOfWork<Person> unitOfWork;
    public MyWindow() : this( new PersonUnitOfWork() ) { }
    public MyWindow( IUnitOfWork<Person> unitOfWork )
    {
        this.InitializeComponent();
        this.ApplyButton.IsEnabled = false;
        this.People = new ObservableCollection<Person>();
        this.unitOfWork = unitOfWork;
        this.unitOfWork.PropertyChanged +=
            ( s, e ) => this.ApplyButton.IsEnabled = this.unitOfWork.HasPendingChanges;
    }
    public Person SelectedPerson { get; set; }
    public ObservableCollection<Person> People { get; private set; }
    private void AddButton_Click( object sender, RoutedEventArgs e )
    {
        var person = new Person();
        // TODO: custom logic
        this.People.Add( person );
        this.unitOfWork.RegisterNew( person );
    }
    private void RemoveButton_Click( object sender, RoutedEventArgs e )
    {
        var person = this.SelectedPerson;
        if ( person == null ) return;
        this.People.Remove( person );
        this.unitOfWork.RegisterRemoved( person );
    }
    private async void ApplyButton_Click( object sender, RoutedEventArgs e )
    {
        await this.unitOfWork.CommitAsync( CancellationToken.None );
    }
    private void CancelButton_Click( object sender, RoutedEventArgs e )
    {
        if ( this.unitOfWork.HasPendingChanges )
        {
            var message = "Discard unsaved changes?";
            var title = "Save";
            var buttons = MessageBoxButton.YesNo;
            var answer = MessageBox.Show( message, title, buttons );
            if ( answer == DialogResult.No ) return;
            this.unitOfWork.Rollback();
        }
        this.Close();
    }
}

Implementing a Self-Tracking Entity

There are many different ways and varying degrees of functionality that can be implemented for a self-tracking entity. The following is one of many possibilities that illustrates just enough to convey the idea. The first thing we need to do is create a factory.

public class MyUnitOfWorkFactory : UnitOfWorkFactory
{
    public MyUnitOfWorkFactory()
    {
        this.RegisterFactoryMethod( () => new PersonUnitOfWork() );
        // additional units of work could be defined here
    }
}

Then we need to wire up the service locator with a provider that contains the factory.

var factories = new IUnitOfWorkFactory[]{ new MyUnitOfWorkFactory() };
UnitOfWork.Provider = new UnitOfWorkFactoryProvider( () => factories );

Finally, we can refactor the entity to enable self-tracking.

public class Person
{
    private string firstName;
    private string lastName;

    public int PersonId
    {
        get;
        set;
    }
    public string FirstName
    {
        get
        {
            return this.firstName;
        }
        set
        {
            this.firstName = value;
            UnitOfWork.GetCurrent<Person>().RegisterChanged( this );
        }
    }
    public string LastName
    {
        get
        {
            return this.lastName;
        }
        set
        {
            this.lastName = value;
            UnitOfWork.GetCurrent<Person>().RegisterChanged( this );
        }
    }
    public static Person CreateNew()
    {
        var person = new Person();
        UnitOfWork.GetCurrent<Person>().RegisterNew( person );
        return person;
    }
    public void Delete()
    {
        UnitOfWork.GetCurrent<Person>().RegisterRemoved( this );
    }
    public Task SaveAsync()
    {
        return UnitOfWork.GetCurrent<Person>().CommitAsync( CancellationToken.None );
    }
}

Conclusion

In this article we examined the Unit of Work pattern, added a few useful extensions to it, and demonstrated some common uses cases as to how you can apply the pattern. There are many implementations for the Unit of Work pattern and the concepts outlined in this article are no more correct than any of the alternatives. Hopefully you finish this article with a better understanding of the pattern and its potential uses. Although I didn't explicitly discuss unit testing, my belief is that most readers will recognize the benefits and ease in which cross-cutting persistence requirements can be tested using a unit of work. I've attached all the code required to leverage the Unit of Work pattern as described in this article in order to accelerate your own development, should you choose to do so.

UnitOfWorkExpanded.zip

In this article, I'll describe how to improve upon the classic Repository pattern by maintaining the fidelity of the original design, while adding asynchronous support and providing LINQ query composition for more complex scenarios.

The Read-Only Repository

When I first began evaluating whether a generic interface could be extracted from the numerous, existing scaffolding examples I found, two things became abundantly clear. First, it was definitely possible to extract a simple, reusable interface. It also occurred to me that there are a number of scenarios where you might want a read-only repository; thus, the IReadOnlyRepository<T> interface was born.

The idea behind this interface is analogous to IReadOnlyList<T>. I also had the goal of making the required implementation as minimal as possible.

The method signatures might seem a little strange at first, but it will make sense soon enough. I attempted many variations, but this was the only one that retained LINQ query composition without requiring the repository to be disposable. It also made creating a repository for the Per-Request model easy.

You might think that only one method is needed, but as we'll see in an example later, there is a subtle difference. The first signature will match most query operations, while the second signature is used primarily for query projections to scalar results, such as an asynchronous count.

Asynchronous Queries

To further explain the method signatures, we first need to examine what it takes to execute a LINQ query asynchronously. LINQ is based on IQueryable<T>, which is based on IEnumerable<T>. Since IEnumerable<T> is not asynchronous, neither is IQueryable<T>. To solve this problem and maintain query capabilities, we use a callback function to shape the query just prior to execution. This also provides a lot of flexibility in how the query is executed. For example, if the repository is backed by the Entity Framework 6.0 or above, you can simply leverage its intrinsic asynchronous extensions. However, if you're using another queryable source, such as a DataServiceContext, you'll have to wrap and execute the query with a Task on your own. Ultimately, this approach enables asynchronous query execution regardless of whether the underlying query provider supports such operations. In a follow up post, I'll illustrate how take the concepts from the Entity Framework to make any IQueryable<T> asynchronous, even when underlying query provider doesn't directly support it.

Sample Implementation

To illustrate pulling all the pieces together, let's create a repository that is backed by the Entity Framework. Also note that this approach can work for versions earlier than 6.0, but you'll have to execute the query in your own Task.

Extension Methods

Up to this point, you may be wondering where all the other standard operations for a repository are. Since we now have a way to generically create and execute asynchronous LINQ queries, adding extension methods to fill in the gaps is straightforward. I chose to use extension methods because my objective was to minimize the effort required to implement the interface.

The following outlines the provided extension methods that support the standard repository operations:

Sample Usage

By now, the overall picture is solidifying; however, to really drive the point home, let's examine some sample usage scenarios of our implementation. For brevity, all of the examples will use the non-cancellable extension methods.

Retrieving All Data

The following example demonstrates how all data from the repository can be retrieved. In almost all scenarios, I'm not sure why anyone would want to allow returning all data without pagination, but since most repositories have this capability, I preserved it for consistency.

Retrieving a Single Entity

The following example demonstrates retrieving a single entity. Since each entity should be matched by a unique key and it is not an error if the repository does not have a match, the execution behavior is the same as the LINQ extension method SingleOrDefault.

Searching for Entities

The following example demonstrates how to search for entities. Unlike GetSingleAsync, this method will return a sequence of all matches.

Paging

The following example demonstrates how to paginate entity queries. The PagedCollection<T> isn't anything special; it is simply a ReadOnlyCollection<T> that also includes a TotalCount property.

Complex Queries

All of previous examples illustrate a strong affinity to the typical definition and implementation of the Repository pattern. However, what happens when you encounter a query scenario that isn't addressed? Common situations include sorting, composite predicates, and so on. In some cases, this could be internally handled by the repository implementation, but this would be limiting to the implementation and not very clear in usage. Other alternatives are possible, but many of them result in changing the signature of the interface or concrete class that is used. Since this design still incorporates the fundamental query capabilities of LINQ, we can use it to solve these issues.

While some of these complex query scenarios are undeniably verbose, you could easily create your own succinct extension methods to suit your needs without changing the core interface.

Web API and OData

Another great, real world example is using this style of repository with an OData-based ASP.NET Web API controller. Enabling an asynchronous, queryable action method for the controller is now very simple.

Writable Repositories

Before wrapping up this article, it's worth discussing a writable repository. According to Fowler, "Objects can be added to and removed from the Repository". While Fowler doesn't explicitly discuss updating items stored in a repository, it is almost certainly implied. Furthermore, if you can add, remove, and update items within a repository, then you'll need a way to persist those changes.

There is already a design pattern that is dedicated to managing the changes that must be persisted to a data store - unit of work. I'll cover the unit of work in an upcoming post, but I'll briefly describe its relationship here. A writable repository should have a collaborating unit of work that manages the underlying state changes. I could have had this interface implement the unit of work interface, but a repository is not a unit of work; rather, it uses a unit of work. Furthermore, the vernacular of the two patterns is different. For example, you commit a unit of work, but you don't commit a repository; you save the changes within a repository. For this reason, although the behaviors are similar, the repository interface does not directly implement a unit of work interface.

While Fowler does describe rolling back changes in a unit of work, he doesn't mention exposing whether it contains any changes and you may be wondering why it is here. For mostly stateless applications, such as web applications and services, it is not particularly useful. However, for stateful applications such as Windows Store applications, Windows Phone applications, and so on, this capability is particularly useful. It enables you to detect and expose when there are user changes; for example, to enable or disable a save button. When a user cancels an operation you can discard or roll back the changes.

Conclusion

In this article we examined a reimaging of the classic Repository pattern with a breath of fresh air to support asynchronous operations and complex query composition. There are many implementations of the Repository pattern and the ideas presented here are in no way anymore correct than any other. My objective was to present new ideas that, hopefully, provide more flexibility in your applications. Feel free to provide questions, comments, or feedback. In two upcoming, related posts, I'll dive into the unit of work pattern and making IQueryable<T> asynchronous.

AsyncRepositories.zip

As it turns out the DefaultODataBatchHandler will only accept the POST method when the request is for a change set. Since an OData action could have side effects, they are required to be requested via the POST method. This clearly causes a problem if we want to support batching and actions. What can we do about it?

Extending the Default OData Batch Handler

HTTP batching has become an intrinsic capability in ASP.NET Web API and OData. Altering or otherwise extending the default behavior is now very straight forward – almost.

While it's true that we can easily subclass DefaultODataBatchHandler and override its behaviors, we are not able to change how the OData APIs parse the batch request. As a result, we are not able to influence the batch parsing process - or are we?

One solution would be to completely supplant the default OData parsing routines and replace them with our own. This approach is highly undesirable because we don't want to change any of the inherent query or change set behaviors. What other options do we have?

Applying Pipes and Filters

A batch request is nothing more than a multipart MIME encoded document that contains nested HTTP requests. All we need to do is evaluate each nested request, determine if it represents an OData action, and filter those requests from the requests that you would normally provide to the OData parsing routines. For each action we identify, we need to create and return an OperationRequestItem from our batch handler. For all other requests, we'll just let them flow through to the base implementation and combine the returned items with our action items.

There's just one caveat that we've overlooked. The OData specification has stringent rules about how batch requests are to be processed. Specifically, it states that requests must be processed in the order that they are received. This requirement doesn't derail our solution, but now we need to ensure that the items we create for actions are merged with the normally created items in the same order as they appear in the request.

The following diagram provides a visualization of the process:

Identifying an OData Action Request

We now have a workable design to support actions in a batch request, but how do we identify that an item in the batch represents an action? The answer is surprisingly easier than we might think. There are three criteria we can use to concretely identify an OData action:

1. The request is a POST    
2. The request is not nested multipart MIME content (e.g. a change set)
3. The request URL matches an ActionPathSegment

The first two criteria are easy to implement using the ReadAsHttpRequestMessageAsync and IsMimeMultipartContent extension methods provided by Web API.

We'll satisfy the third criterion by creating our own extension method – IsODataAction. In order to determine whether the nested request is an action, we'll use the path handler associated with batch request to parse the OData path. If the path parses successfully and the last segment is an ActionPathSegment, then we know we have a match.

Custom Batch Handler Landmines

While poking around in the source code for the DefaultODataBatchHandler, I realized that the OData batch processing does not use the Web API libraries to parse the request. This really isn't a big deal and in all likelihood the code is the same as it is in WCF Data Services. The surprise and initial frustration to me was the fickleness of the HttpRequestMessage class when you try to read it from HttpContent using the ReadAsHttpRequestMessageAsync.

First, the HttpRequestMessage class enforces the HTTP 1.1 requirement for the Host header. Under most scenarios this would be completely reasonable; however, in a batch request the client must already provide the Host header in the root request, which makes it unlikely or easy to forget to specify in the nested requests. To be tolerant of this potential issue, I had to programmatically inject the Host header from the main batch request to each child request before it is deserialized – if it's not already present.

The second issue is similar in nature. The URL specified for each of the nested requests in the batch will almost certainly be relative. The examples for batch requests you can find online vary, where some show the relative URL with a leading '/' and others do not. It turns out that the relative URL will fail to build properly using ReadAsHttpRequestMessageAsync if it does not have the leading '/'. If you examine the implementation of the private CreateRequestUri method within HttpContentMessageExtensions, you'll see that it fails because the URL is constructed as an absolute URL using String.Format. I'm not quite sure I would qualify this as a bug, but at a minimum the code should be more tolerant of this behavior or use Uri to combine the URLs. A comment in the source code does mention why it doesn't use UriBuilder, but it doesn't explain why it doesn't use Uri.

Ultimately, these were not huge issues to overcome, but they were certainly unexpected. I could have written all my own parsing as needed (and in some cases I still had to), but my objective was to make the Web API libraries do as much as that work for me as possible.

Putting It All Together

One of the greatest strengths of how batching is supported in ASP.NET Web API is that it is completely orthogonal to everything else. Why should a controller know it's executing something from a batched request? It is a cross-cutting concern after all. To enable OData batching in your application, you only need to add the following Web API configuration:

This will light up a new endpoint at [route prefix]/$batch, which is the out-of-the-box route mapping for OData. A batch request can be made to any entity controller operation and, now, to any action. Also keep in mind that batch requests do not need to target the same controller. This means a client can issue a query, change set, or execute an action against any combination of services!

Making a Batch Request with JavaScript

There are countless ways to make a HTTP batch request to one or more of your services. If you're using .NET, the web client APIs make it really easy to compose a MIME encoded document with nested HTTP requests. However, if you're using some other client – say JavaScript – it's not so trivial to build up the request correctly; enter DataJs. DataJs is a JavaScript library (available on NuGet), which has rich support for OData, including batching.

I've excluded much of the HTML page for brevity, but the following demonstrates how to compose an OData action and query in a batch request and then display the results in the page. The complete example is included in the sample code.

Conclusion

Although we had to jump through a few hoops, it is possible to support OData batching with actions. Hopefully, you'll find this useful in expanding batching support in your applications. As always, the full source code is provided with all of the relevant unit tests. The solution was built with Visual Studio .NET 2013, .NET 4.5.1, ASP.NET MVC 5.0, and ASP.NET Web API 2.0 for OData.

ODataBatchingWithActions.zip

Fortunately, the team was kind enough to provide an example of the world's simplest implementation of a bare-bones controller with support for Media Resources. With a naïve, but functional example in-hand, I've been able to take their example and refactor the bits into something that can be reused by all. In this post, I'll illustrate the pieces that you need to configure in order to enable OData streaming and I'll discuss the MediaResourceController base class that will allow you to quickly enable Media Resources in your application.

Required Components

In order to enable streaming in accordance with the OData specification, there's a couple of things we must create:

• A custom OData routing convention
• A custom OData path handler
• A custom OData entity type serializer
• An OData MediaResourceController

That might seem like a lot to create, but most of the work relies on just extending the base classes already available in the OData assembly for Web API. I'll leave a deep analysis of the code to the reader, but I'll highlight the important segments in the sections to follow.

Media Resource Entry Routing Convention

The first thing we need is a way to select a controller to dispatch Media Resource related links to. Since the mapping and semantics of OData are more well-defined than a basic Web API controller, we can't simply decorate a method such as GetMediaResource with the HttpGetAttribute and expect it to light up. However, since the operations for a Media Resource will intrinsically be CRUD operations for the resource and queries would never be supported for a stream, it is relatively straightforward to define a generic routing convention.

We begin by inheriting from the EntityRoutingConvention. Our routing convention only needs to override the SelectAction method. We'll be looking to see if we get an OData path template that matches ~/entityset/key/$value. If we get a match, then we'll use the Convention-Over-Configuration semantics commonly used in ASP.NET MVC and Web API to match the HTTP method to one of four expected actions: GetMediaResource, PostMediaResource, PutMediaResource, or DeleteMediaResource.

Media Resource Entry Path Handler

Creating a custom path handler to process the Media Resource OData segment is one of the easiest tasks. We start by inheriting from the DefaultODataPathHandler and override the ParseAtEntity method. The only thing we need to do is return the ValuePathSegment if the segment equals $value; otherwise, we just let the base implementation work its magic.

Media Link Entry Entity Type Serializer

The secret to rendering the Media Link Entry in OData responses is to override the CreateEntry method in the ODataEntityTypeSerializer. In this method, we need to detect whether the entity being serialized has a Media Resource (e.g. stream) associated with its model. If it does, then we need to add a Media Link Entry for the Media Resource. If there is no associated Media Resource defined, then we just let the base implementation run its course.

The one challenge we face with this solution is that the way the Media Link Entry is created can vary by controller and entity. Hard-coding or otherwise having to create a new serializer for each variant simply will not do. To solve this problem, as illustrated in the above example, we'll define an IMediaLinkEntryProvider interface and connect it to the current request using the extension methods GetMediaLinkEntryProvider and SetMediaLinkEntryProvider. The interface itself only contains one method - GetMediaLinkEntry, which provides a callback mechanism for a controller to decide how or if a Media Link Entry should be created. A controller might be read-only or the current entity might have a Media Resource, but it is currently unset. There is no clear way for the serializer to be cognizant of this information.

Media Resource Controller

We now have all the constituent components required to create a reusable Media Resource controller. We start by extending the AsyncEntitySetController. The MediaResourceController has the following, basic signature:

There are three things you must do in addition to what is normally required to set up an AsyncEntityController.

• Override the GetStream method to retrieve a stream from an entity. The way the stream is retrieved can vary as your entity may have an associated Stream, a byte array, or may use some other mechanism to retrieve the stream.
• Override the GetContentTypeForStream method to retrieve the stream media type. The media type cannot be derived directly from the Stream; however, your entity should have an attribute that can provide it.
• Override the GetMediaLinkEntry method to create a Media Link Entry for an entity. This will provide the implementation for the IMediaEntryLinkProvider interface.

As is the case with the AsyncEntityController, the default implementation of the PostMediaResource, PutMediaResource, and DeleteMediaResource will return HTTP 501 (Not Implemented). By overriding the Initialize method, the MediaResourceController will assign itself as the IMediaEntryLinkProvider associated with the current request; therefore, there is nothing for you to do to set this up in your controllers.

Batching and Partial Content

Depending on the size of your Media Resources, it may be desirable to support batching and partial content. Fortunately, this is really easy to support in ASP.NET Web API using the Range HTTP header and the ByteRangeStreamContent class. The partial stream behavior is baked into the default implementation of the GetMediaResource method, so there is nothing extra for you to do in order to take advantage of this capability.

Creating Your First Media Resource Controller

To demonstrate all the pieces coming together, we'll create a simple, read-only Media Resource controller for an entity set of images. The first thing we need is our entity definition for an Image.

Creating a controller with our defined entity is now a cinch. In the spirit of keeping the demonstration simple, we'll just enumerate the images in a folder hosted on the website. In this example, we also build up the entity and its corresponding stream in a single pass. To prevent unnecessarily opening a FileStream, we'll use the provided LazyStream, which enables a lazy-loaded stream. As noted previously, this technique is only one of several possibilities for returning the Stream in the GetStream method.

The majority of the controller's implementation shouldn't require much explanation. The GetMediaLinkEntry is the only part that isn't entirely straightforward. To ensure developers have the maximum fidelity over how the Media Link Entry is created, you are provided the entity and the serializer context being used. Given this information, we are able to create a Media Link Entry with a read link and its media type. We could optionally add an edit link and ETag. The edit link would typically be the same as the read link, but will be routed based on the POST, PUT, or DELETE verb.

Setting Up the Web API Configuration

The final step that must be completed before we can reap the rewards of our efforts is to update the Web API configuration. First, we need an EDM model to provide to the OData route.

The last thing we need to do is update the Web API registration with the required OData configuration. We override the default OData routing conventions, path handler, and serializer provider with our extended implementations that support Media Link Entries.

Viewing the Results

At long last we can hit F5 and view the results. A single entity result in JSON now looks like:

If we following the Media Link Entry, we'll get the associated Media Resource as an image:

Conclusion

Ultimately this post ended up being longer than I wanted; however, I felt it was important to outline all of the moving parts required to enable Media Resources and Media Link Entries. I didn't demonstrate a controller that writes Media Resources, but it's not much of a stretch to implement one by overriding the appropriate methods and reading the stream sent in a request. Hopefully you find that using the sample library provided, it is relatively quick and easy to setup any number of Media Resource controllers in your application.

Although omitted from the post for brevity, all of the code provided is well-documented to help guide you through it. Of course, no example would be complete without unit tests, so all of the related unit tests are also included with the source. I'm a big fan of XUnit.NET, so if you don't have the test runner installed, you'll need to grab it from the Visual Studio Extension Gallery. I'm also a fan of Design-By-Contract and Microsoft Code Contracts. The code contracts defined are unobtrusive, require no special tools, and can even be removed if you so desire; however, if you want to leverage the full Code Contracts toolset, you can also get it from the Visual Studio Extension Gallery. The solution was built with Visual Studio .NET 2013, .NET 4.5.1, ASP.NET MVC 5.0, and ASP.NET Web API 2.0 for OData.

ODataMediaLinkEntries.zip

The story begins when I wanted to create a custom SqlProfileProvider implementation. By default, the SqlProfileProvider does everything I needed except that it only allows for the connectionStringName attribute in the application configuration. Following the wisdom of my astute colleague, James Zimmerman, I'm in the habit of entering connection string information in UDDI. This is a cogent assertion as a data source can be thought of a type of service and the connection string is kind of binding for that service. I assumed it would be simple to subclass the SqlProfileProvider class and override the Initialize method to supply required connection string or IDbConnection object dynamically. I was wrong.

Unfortunately, the SqlProfileProvider will only work if the connection string is present in the <connectionStrings/> section in the application configuration. This is obviously a problem since the desired result is to resolve the connection string dynamically. The next idea was to resolve the connection string and add the expected item into the ConfigurationManager.ConnectionStrings collection. Again, I was stopped in my tracks; the collection is read-only. At this point, I had pretty much given up, but I thought it was also worth adding an empty connection string entry and subsequently updating the value at run-time. Once more, I was quickly met by epic failure.

Most people probably would have concluded that dynamically adding the connection string is not possible and moved on. In a last ditch effort, I began to research the feasibility of performing invasive surgery on the configuration system - enter Reflector. Using Reflector, I was able to perform a biopsy that confirms that the connection strings settings collection is made read-only as soon as it is parsed. Fortunately, the read-only state is governed by the simple toggling of a private Boolean field. One caveat is that the ConfigurationElement and ConfigurationElementCollection have different read-only flags. Since the ConfigurationElementCollection inherits from ConfigurationElement, both values must be set to false in order to make any changes. Armed with this information, I was able to use Reflection to perform a bypass and dynamically insert a connection string.

The first step to implement this solution is to resolve the fields via Reflection.

private static FieldInfo elementField;

private static FieldInfo collectionField;

private static void EnsureFieldInfo()

{

if ( elementField != null )

return;

new ReflectionPermission( ReflectionPermissionFlag.MemberAccess | ReflectionPermissionFlag.RestrictedMemberAccess ).Assert();

var flags = BindingFlags.Instance | BindingFlags.NonPublic;

try

{

elementField = typeof( ConfigurationElement ).GetField( "_bReadOnly", flags );

collectionField = typeof( ConfigurationElementCollection ).GetField( "bReadOnly", flags );

}

finally

{

CodeAccessPermission.RevertAssert();

}

if ( elementField == null )

throw new MemberAccessException( string.Format( null, "The operation to access field '{0}' failed.", "_bReadOnly" ) );

if ( collectionField == null )

throw new MemberAccessException( string.Format( null, "The operation to access field '{0}' failed.", "bReadOnly" ) );

}

Now that we have the fields, we can build a couple of simple methods to do the work.

private static void SetElementIsReadOnly( ConfigurationElement element, bool readOnly )

{

elementField.SetValue( element, readOnly );

}

private static void SetCollectionIsReadOnly( ConfigurationElementCollection collection, bool readOnly )

{

SetElementIsReadOnly( collection, readOnly );

collectionField.SetValue( collection, readOnly );

}

We now have everything we need to dynamically add a connection string.

protected virtual void AddConnectionString( ConnectionStringSettings settings )

{

if ( !ConfigurationManager.ConnectionStrings.IsReadOnly() )

{

ConfigurationManager.ConnectionStrings.Add( settings );

return;

}

EnsureFieldInfo();

new ReflectionPermission( ReflectionPermissionFlag.MemberAccess | ReflectionPermissionFlag.RestrictedMemberAccess ).Assert();

try

{

SetCollectionIsReadOnly( ConfigurationManager.ConnectionStrings, false );

ConfigurationManager.ConnectionStrings.Add( settings );

SetCollectionIsReadOnly( ConfigurationManager.ConnectionStrings, true );

}

finally

{

CodeAccessPermission.RevertAssert();

}

}

I'll leave you to your own devices with regard to how you resolve your connection strings. The implementation of Initialize will look something similar to the following:

public override void Initialize( string name, NameValueCollection config )

{

var key = config["connectionStringName"];

// TODO: your method to get a ConnectionStringSettings object

var settings = new ConnectionStringSettings( key, string.Empty, string.Empty );

this.SetConnectionString( settings );

if ( string.IsNullOrEmpty( name ) )

name = this.GetType().Name;

base.Initialize( name, config );

}

While this is solution is analogous to lighting a hula-hoop on fire while diving through it, it does demonstrate that if we carefully use a scalpel, we can perform cosmetic surgery to make the configuration system look the way we want. The ultimate goal of this implementation was to resolve the connection string for the profile service dynamically, but it could be used any number of additional ways. I'll let you use your imagination. Enjoy!

CustomSqlProfileProvider.cs

One of the key challenges I have faced has been coming up with ways to simplify asynchronous code and make it have the appearance of traditional synchronous code. A pivotal piece of the puzzle that helped solve that problem was the Reactive Framework (Rx). While Rx doesn't solve everything, it certainly goes a long way in simplifying the problem. Another aspect that significantly simplified the code was to provide a façade over WCF service proxies. I call this type of service a local service.

A local service doesn't have to be WCF service proxy. The word service is exceptionally overloaded. A local service can be any type of service that is local to a domain such as a spell checker, event broker, WCF service proxy, etc. For those of you who are familiar with Inversion of Control (IoC) design patterns, you'll appreciate providing a level of indirection against service proxies. This approach is also easy to test, even if you replace the WCF service proxy or don't have an actual service proxy to work with. After all, a test doesn't care if you have a real WCF service to communicate with.

The final challenge in creating a local service that is a façade for a WCF service proxy is retrieving and setting the endpoint address. Service endpoints will change; it's an absolute certainty. The ServiceReferences.clientConfig is exceptionally limited and can't be easily changed once you've deployed an application. There are a number of ways to overcome this problem, but my team has chosen to use UDDI to have the Silverlight client resolve the endpoint address.

In an asynchronous programming model, here's where we get into trouble. If my local service needs to locate a URL dynamically from UDDI, but some other code calls it before that endpoint address is returned, what do I do? Blocking the thread is not an option as that will just hang the entire application. Enter the deferred action queue.

The deferred action queue is exactly what it sounds like; a Queue<Action> deferred for execution. If the service isn't ready, it can use the DeferredActionQueue to enqueue a callback to itself. This seems odd at first, but when we combine it with an IObserver<T> from Rx, the caller never knows the difference.

Let's assume we have an interface IMyService that has just a single method void DoWork( IObserver<string> observer ). Let's also assume that the concrete implementation MyService will create a WCF proxy as needed and have a dependency on an IUrlLocator object whose only method is void Locate( string key, Action<Uri> located ). In order to not block the current thread and still allow callers to invoke the service, we'll use the DeferredActionQueue. The complete implementation would look something like this:

public class MyService : IMyService

{

private readonly MyWcfProxy proxy;

private readonly DeferredActionQueue callbacks;

public MyService( IUrlLocator locator )

{

this.callbacks = new DeferredActionQueue( () => this.proxy == null );

locator.Locate(

"MyWcfServiceKey",

url =>

{

lock ( this.callbacks.SyncLock )

{

this.proxy = new MyWcfProxy();

this.proxy.Endpoint = new EndpointAddress( url );

this.callbacks.DequeueAll();

}

} );

}

public void DoWork( IObserver<string> observer )

{

if ( this.callbacks.Enqueue( () => this.DoWork( observer ) ) )

return;

this.proxy.BeginDoWork(

ar =>

{

string result;

var dispatcher = System.Windows.Deployment.Current.Dispatcher;

try

{

result = this.proxy.EndDoWork( ar );

}

catch ( System.ServiceModel.CommunicationException ex )

{

dispatcher.BeginInvoke( () => observer.OnError( ex ) );

return;

}

dispatcher.BeginInvoke(

() =>

{

observer.OnNext( result );

observer.OnCompleted();

} );

}, null );

}

}

The DeferredActionQueue does the work of managing all, if any, deferred actions. The constructor accepts Func<bool> which is used to determine whether an action should be deferred. The Enqueue method accepts any Action and enqueues it into an internal queue as necessary. The method returns false if the operation does not need to be queued (and ultimately results in no operation). In this example, the DeferredActionQueue is used to coordinate requests while the underlying WCF service proxy endpoint address is being resolved. Once the endpoint has been resolved, all enqueued actions are dequeued. The DeferredActionQueue exposes a SyncLock property that can be used for synchronization to avoid race conditions. Another thing to note is that the callback automatically calls the supplied observer via the dispatcher. This absolves the caller from the responsibility of having to marshal callbacks to the correct thread.

Let's quickly take a look at how this might be used.

var locator = new UddiUrlLocator();
var service = new MyService( locator );

var observer = Observer<string>.Create( m => this.MyTextBox.Text = m, ex => MessageBox.Show( ex.Message ), null );
service.DoWork( observer );

Although the code is asynchronous, it now has a more synchronous feel to it. If the service is still initializing when DoWork gets called, the observer has no idea. The observer intrinsically expects the operation to be asynchronous and still functions as advertised, even if it gets privately deferred for later processing. This is particularly important and useful when a complex hierarchy of objects is being constructed from Unity or any other IoC container.

These examples are obviously simple and naïve; however, in practice this approach has worked very well in programming against a purely asynchronous model. Hopefully, I've demonstrated how this concept could be extended into your own work.

DeferredActionQueue.cs

Once generics where introduced in .NET 2.0, I often wondered why there was never a generic implementation for ICloneable<T>. At first glance, it seems impossible because methods cannot vary by return type alone. However, if we use a constrained type argument on the Clone method that restriction can be overcome.

public interface ICloneable<T>

{

TClone Clone<TClone>() where TClone : T;

}

This contract allows a generic Clone implementation where the cloned return type is compatible with the original type. This provides the benefit of a strongly-typed return type. We can also now create a generic, cloneable base class.

public class Cloneable<T> : ICloneable<T>, ICloneable

{

public virtual TClone Clone<TClone>() where TClone : T

{

return (TClone) this.MemberwiseClone();

}

object ICloneable.Clone()

{

var type = this.GetType();

var method = type.GetMethod( "Clone" ).MakeGenericMethod( type );

return method.Invoke( this, null );

}

}

This class provides a simple (and naïve) cloning strategy, but can be overridden and still retain the strongly-typed benefits. In addition, we can write a single implementation of ICloneable that uses Reflection to always invoke the current generic implementation. When we put it all together, we get the following:

public class Person : Cloneable<Person> {}
public class User : Person {}

var user = new User();
var clonedUser = user.Clone<User>();
var clonedPerson = user.Clone<Person>();

Unfortunately, there is one scenario where this strategy fails; a clone of a super type cannot be created for a subtype. This limitation is probably why such an interface was never added to the BCL. For example, the following will compile, but fails at runtime:

var person = new Person();
var clone = person.Clone<User>(); // fails because Person cannot cast down to User

In my opinion, this limitation is acceptable for two reasons. Although not guaranteed, it's unlikely that developers would write code in this manner. If you've written object-oriented code for any length of time, common sense tells you that a super type cannot be cast down to a subtype. Second, the runtime failure has same effect as writing code with an invalid cast. Consider the following:

var person = new Person();

var user = (User) person;

This code also compiles, but will fail at runtime. Both of these scenarios have logic defects that cannot be guarded against by the compiler. The benefits of a strongly-typed Clone implementation outweigh this single shortcoming in my opinion.

While this implementation certainly doesn't address the need for every cloning scenario, it does provide a single non-generic implementation, virtualized generic implementation, and the benefits of strong-typing.

GenericCloneable.zip