Dec 23

I think I can safely say I finally “get” dependency injection (DI) and the need for a framework (such as StructureMap, Ninject, Windsor, or any other). More importantly, I think I finally get the best way to use it in an application. Its taken me a bit to get to this point, and almost everything I’ve read and heard on the subject was very hand-wavy, at least to me. So here’s my attempt at demystifying the subject along with a straight forward way to go about using it in your application, something I wish I could have heard a while ago.

What is it?

Many objects have an outside dependency of some sort. Instead of creating the dependency inside your class (by doing something like myDependency = new Dependency()), you want these dependencies to be “injected” in, usually by the constructor:

public class OrderProcessingService
{
	private readonly IRepository _repository;
 
	public OrderProcessingService(IRepository repository)
	{
		_repository = repository;
	}
}

That’s it. Seriously. It’s not hard to grasp, and you’re probably already doing it, but the trick for me was figuring out how to actually go about using this in any sort of sane and recommended way, as you’ll notice the requirement is now on the caller to provide an instance of IRepository. If you want more details on this pattern, there’s plenty out there.

Why should I bother using it?

  1. It takes handling the dependency’s life cycle out of your hands. Perhaps you want your database access class to stick around for a whole web request, another object to be a singleton, and another to be per thread when used in a Windows app, but per request in a Web app? Using a proper DI framework/container, you don’t have to worry about writing anything to support that, and changing the lifespan of a given object is a one line (and usually even enumeration value) change.
  2. It loosens up your code. You’re no longer “newing” up your data access or web service classes right in the middle of your operation. Swapping out implementations of, say, an interface, is a simple operation that’s located in one place. Just stick the dependency in your constructor, and you’re good to go. I’ve actually used this in quite a few places beyond the academic and largely unused-in-the-real-world “switching from Ms SQL to Oracle” examples, too.
  3. Greatly eases and simplifies unit testing. In many cases, using dependency injection is the only way to unit test portions of your code base (unless you use a certain tool to do it for you). By taking your dependencies in your constructor, you’re giving your unit tests a seam to inject fake implementation of these dependencies. This lets you skip actually hitting the database, web service, hard drive, or anything else that would kill the running time of a unit test or be almost impossible to setup and control in a repeatable manner.

If you’re looking for more detailed reasons, you’ll again want to refer to the gobs of information already out there.

How can I use it?

Ah, now for the juicy part I know you’re all dying to hear: how the hell to actually use the pattern in conjunction with one of the tools I mentioned at the beginning of the post. Before giving away the answer, let’s quickly go over the three primary ways to use a DI container in your app:

  1. Service locator: this pattern is generally considered a no-no, as it still burys your dependencies deep inside your code. Sure, you can swap them out when needed for unit testing, but they’re still very opaque and will almost certainly get very hard to work with, very fast:

    public void ProcessOrder()
    {
    	var repository = IoC.Resolve<IRepository>();
     
    	// Do stuff with repository.
    }

    In the above example, IoC.Resolve is a simple static method that delegates to whatever DI framework you’re using. Callers won’t know about this dependency, though, and without fully boot strapping your framework in your unit test (icky) or injecting a fake into your container, the call will either throw or return null, neither of which you want to be checking for everywhere.

  2. Poor-man’s dependency injection: This is a slight twist on normal constructor DI. You have one empty constructor for most of the program to use, which delegates to a “loaded” constructor that unit tests use. While making the dependencies clear, this removes lifetime management from the container’s hands, and also gets ugly when you start changing dependencies around. This is usually used in conjunction with the service locator pattern above:

    public class OrderProcessingService
    {
    	private readonly IRepository _repository;
     
    	public OrderProcessingService() : this(IoC.Resolve<IRepository>())
    	{
    	}
     
    	public OrderProcessingService(IRepository repository)
    	{
    		_repository = repository;
    	}
    }
  3. True dependency injection: Classes generally have only one constructor which takes in all the required dependencies (see the first code snippet at the top of the post).

#3, true dependency injection, is the one I had no idea how to go about setting up in my app. Everyone said not to use the service locator pattern or poor-man’s dependency injection, but how was I supposed to not use them and still get everything injected in? It seems like I was never supposed to call my DI container’s Resolve method. So what gives? Every time someone got close to answering it, it seemed like they’d blow off the question. Ugh.

After enough playing around, reading, and looking at other open source projects, though, it finally clicked: only call Resolve at the furthest edges of your application, and as few times as possible. So what does that mean and where should you be calling it in your app? Well… it depends.

Wait, isn’t that just another cop-out?

Well, yes and no. Yes in the fact that I’m not giving a solid answer, no in the sense that it really does depend on your application: what frameworks you’re using, how you have its architecture setup, etc.

Just so you can’t say I’m not providing anything solid, here’s how I’m using it in our current app:

  1. We’re using ASP.NET MVC & StructureMap, so we’re using a custom controller factory that creates controllers from the container. This means we can create an EmployeeService, extract an interface for it named IEmployeeService, put it as a requirement in the controller’s constructor, and it’s satisfied magically at run time. Even cooler, everything down the object graph from EmployeeService (say, an EmployeeRepository, or LoggingService, or EmailService, or anything else you need) gets their dependencies all satisfied automagically, too. We can stick a constructor argument in virtually anywhere and it’s taken care of for us, without giving it a second thought! Each web request, this all gets built out.
  2. We have a basic home brewed scheduled task framework that, given the name of a task you want to run (say /run Emailer runs the EmailerTask), instantiates the requested task class, and runs it. We use the container at the point of instantiation, effectively treating each “task” class as a controller from above, filling all the dependencies it needs down the object graph.
  3. We also fire off the scheduled task app by doing an IoC.Resolve<IApplication>().Run() in the console app’s Main method, giving the app everything it needs.

In all, we call IoC.Resolve only 4 times in our app, and it handles everything for us. We usually forget it’s even there, and take its services for granted when working with legacy applications that don’t have it.

Now, what if you’re using WebForms? Well, you’re not *completely* out of luck. It’s a pain, to be sure, but still doable.

Wrapping up

I hope this helped cleared up dependency injection for you a bit. Just remember to use the actual Resolve call of your container in as few places as possible in your application, and only on the “outside edges” of the app. Look at where you do all your main object creation (your web forms, Windows forms, controllers, WCF factories, Silverlight pages, etc). Stick the call in there, and forget about it.

Good luck.

Dec 4
Branch-Per-Feature in Subversion
icon1 Darrell Mozingo | icon2 Source Control | icon4 December 4th, 2009| icon38 Comments »

Preamble

Branch-Per-FeatureDisclaimer: My team and I have only been doing this for a short time, so please, for the love of all that is holy, don’t take my word as gospel on any of this. We’re learning more about this each day, but we’re still far from proficient or experienced. I’m just putting what we do and what we’ve learned out there to possibly help others, as I know we would have loved to hear this when we started. If you blow up your repository and lose all your code, it’s not my fault.

That said, lets discuss what Branch-Per-Feature is and how it typically works. I won’t get into much detail on why you should do it or what it is here, as Derick Bailey has an excellent, though unfortunately unfinished at the moment, series of posts on the subject and they’re a must read to get a solid background on this. In a nut shell, though, Branch-Per-Feature is basically what the name implies – you create a branch in your source control system for each “feature” you work on (where the “feature” can be defined as big or as small as you want – we’ll skip doing this for typos and the like). You can then work on that feature in isolation in your own branch, committing your changes as often as you like and not screwing up your other teammates or being affected by them, until you’re all finished, at which point you merge the completed feature back into the trunk. Using this methodology, the trunk should always be kept in a “shippable” state.

Sounds easy enough, right? As is often the case, however, the devil is in the details. I’m sure the first thing that jumps out at you in reading about this is “how the hell does this work with multiple developers?”. Well, the theory goes that as you’re working on your feature branch, you continuously merge changes from the trunk (i.e. features other developer’s have finished) into your branch. This means instead of merging after 2 weeks of work and finding a crap load of conflicts, you have a few here and a few there. In practice it generally works out that way, too, unless you or a team mate goes on a refactoring rampage and you need to merge those changes in (I’m usually guilty of this myself – sorry guys!). Following SRP and the small class sizes that result from it helps in the fact that multiple people usually aren’t working in the same class, too.

Simple scenario

I’ll walk through the steps of a simplified “feature” branch from start to finish. Simplified here means you’re either working by yourself, or you know nobody else has changed the trunk while you’re working on your feature. As the title of this post alludes to, I’ll be showing this using Subversion coupled with TortoiseSVN, so I’m not terribly sure how it’ll work with similar source control systems. Also, while all the tools and practices that I’m going to show here do help with merge problems and the like, they’re not a substitute for using actual communication on your team inorder to avoid problems. Sorry, but you just can’t get away from talking to people 🙂

Note: all of this is shown with a version of Subversion & TortoiseSVN > 1.6, as many of these features have only been included since then. Make sure the server, client, and your repository are upgraded to at least this version (especially check the repository, which needs upgraded separate from the server, which we learned the hard way). Ask your admin if you’re unsure about any of this.

Now, say we have a repository named BranchPerFeature with the standard /trunk, /branches, and /tags folders. It has a simple console app that displays a welcome message. Call me weird, but I’ve never liked the SVN switch command, so I just setup a local directory structure similar to the repository’s:

Local folder structure

We’ll start by creating a branch for our new feature. Right-click your checked out trunk folder, then select TortoiseSVN, then Branch/Tag. In the To URL field, we’ll enter a path in the branches folder in the repository, usually named after the feature we’re working on. In this case we’ll create a branch in branches/AddUserInput (we’re adding a Console.ReadLine() in this feature – exciting, huh?):

Creating feature branch

Now you can checkout that new branch in your local branches folder and start working on the feature, committing as often as you’d like knowing you’re not affecting anyone else. When you’re all done and everything is committed to it, we’ll merge it back into the local copy of your trunk. Go to where you have the trunk checked out, right-click and select TortoiseSVN, then Merge. Of the three options you’re presented with, select the second, Reintegrate a branch:

Integrating branch

We’re merging from our branch, so enter its repository URL in the From URL and hit next:

Integrate branch #2

Hit Merge on the final screen (or use the Test Merge button to do a dry-run that won’t affect anything). Remember, at this point all changes made from your branch, and applied to the trunk, are only local. Now open the updated trunk, run all your unit tests and whatnot, then commit these changes to the repository:

Commit merged branch

Congrats! Your first feature branch is finished and merged back into the trunk, hopefully with no problems. One major caveat of this procedure is you must not use your branch again after it’s merged back into the trunk. Why? Well, Subversion keeps some properties set on all your files/folders so it knows what revisions have been merged back into them, and continuing to work on your now stale branch and trying to merge it back into the trunk again at a latter point would be bad ju-ju. To make sure nobody accidentally uses your branch, be sure to “delete” it from your repository (don’t worry, the history is still available, just not readily available). To delete the branch, right-click on your checked out trunk folder, select TortoiseSVN, then Repo-browser. Navigate to your branches folder in the left pane, then right-click and delete your old branch:

Deleting old branch

A bit more complicated scenario

So you created your branch and you’re happily committing away when you see someone else committed to the trunk. Uh oh. Fortunately, it’s really not a big deal. We’ll just merge the new revisions from the trunk into our branch every now and then to keep it “current” with the trunk. Then when you’re done with your branch and go to merge it back into the trunk, it should theoretically merge without problems, as it’s the same as the trunk except for the changes you’ve made.

To show this, we’ll create a new branch to add a prime number calculator to our app. Same steps as above. After we’re working on the branch, though, we’ll commit a change to the trunk to simulate it being a co-worker’s change (it can be anything, even a conflicting change if you want). Now it’s time to update you branch!

First, check-in any changes you’ve made on the branch (this allows you to roll back the coming updates if they blow up, among other things). Then right-click on your checked out branch folder and select TortoiseSVN, then Merge. Choose the first option this time, Merge a range of revisions:

Updating branch

Make sure the trunk is specified in the URL to merge from field on the next screen. Leave the Revision range to merge field blank, as Subversion tracks which revisions it already merged in automatically and won’t try to re-merge them (which is new in version 1.6 – for older versions you’ll have to track this and specify revision ranges by hand, and trust me, it gets messy real quick):

Updating branch #2

If you hit the Show Log button on this screen, it should show revisions that have already been merged in gray:

Showing merged revisions

As a quick side note, when everything is done, you can do a diff on the files and see how Subversion tracks previously merged revisions on each file & folder:

Diff on updated file

After hitting next, you can hit either Merge or Test Merge (just like before), and make sure everything gets updated. Deal with any file or tree conflicts here, and run all your unit tests to make sure these new changes are still hunky-dory with your stuff. Then simply commit these new updates to your branch:

Committing updated branch

Keep up on these trunk updates while you’re working on your feature, and when you’re done and it’s time to merge back into the trunk, you shouldn’t have any (or at least not many!) issues or conflicts with it.

Monitoring the trunk

How can you know when changes are made to the trunk? Well, you can have everyone yell out when they commit to the trunk if you work close enough, you can email everyone, or you can get a tool to monitor the repository for you, such as SVN-Monitor which is quite awesome and totally free.

I set this up to monitor our trunk so I know when changes are made, with both a nice pop-up balloon and an email. Here’s a view of this sample’s trunk:

SVN-Monitor

Complex scenarios

You’re bound to run into issues now and again with this workflow, especially on larger teams, having a more complicated branching setup, or if you’re doing a lot of file shuffling in the trunk or your branch (as its been my experience that, in general, SVN doesn’t deal well with file moves/renames beyond the simple cases). I’m also working on a 3 person team, so I can’t speak as to how well this scales up to a 15 person team size.

I’m not pretending to cover every scenario or issue you’ll run into in this post, either, so accept that fact that you might, and probably will, have to either Google around for an answer to some weird error and drop down to the command line to fix something. You might as well know that going in.

Issues?

The biggest issue I have with this workflow so far is the time taken to create a new branch, mostly comprised of the time spent checking-out and updating R#:

  • Check-out time: as I mentioned, I don’t like the switch command (though it would probably solve this issue). We’re work on a large, and rapidly expanding, code base with over two dozen dependencies and lots of code files. It simply takes a while to check out a new branch (ok, in reality it’s only a few minutes, but still annoying).
  • Updating R#: I love the solution wide analysis R# offers, but it takes a while to scan everything when you open a newly created & checked out branch. This is on a quad-core machine with 15k RPM drives, too.

These issues, while not show stoppers by any means, are still annoying to me none-the-less, and I thought I’d mention it.

Wrapping up

So there you go. Common usage scenarios when using a branch-per-feature workflow with Subversion. Not too complicated. As I noted in the begining, we’ve been doing this for a short while now and it’s working quite nice, as before we’d just make one branch for each iteration, all work in that, and merge with the trunk when done. That meant if one of us was making breaking changes, we’d simply not commit until we were all done. That’s pretty risky. What happens if our machine crashes after 4 days of work, or we wanted a file back from a few days ago? Not cool.

It’s worth noting that, from what I understand, Git‘s workflow follows this pattern by default. I’m planning to dive into that soon.

If I messed anything up in here, or you know a better way of doing it, please let me know!