If you’re a consultant or just do a lot of coding on the side either for profit or to keep your skills sharp, it’s often nice to be able to store your code in a source code repository. The benefits of a personal repository are almost the same as what you get with a repository shared by a team of developers (history-tracking of your code, the ability to branch and merge, easy roll-back of uncommitted changes), the only different is that you’re the only user.
But setting up a reliable source code repository is not trivial, especially if you want to be able to access it while on the go. The easy route is to pay for a hosted solution, but that requires an internet connection (at least for doing source code operations) and they usually cost money if you want something decent.
I’ve come up with a couple simple approaches that allow you to have a personal repository that you control, that can be accessed from anywhere whether you have an internet connection or not, and that can get backed up in the event of data corruption.
Before I jump into the details, I’d like to say a couple things about virtualization since it is a big component of the solutions I came up with (especially the second). While you can easily code using tools installed directly on your host OS, I highly recommend isolating your software development environments on one or more virtual machines (VM’s). There are several reasons for this:
Which virtualization option you go with is pretty irrelevant. For the longest time, I was a big user of Microsoft’s Virtual PC. It was free and it worked great. Since then I’ve moved to VMWare’s Workstation and Player on Windows and Fusion on the Mac. VMWare seems to have a slightly more superior product at the moment, but Microsoft’s virtualization offering is not too far behind, especially when you consider the new functionality available in Windows 7.
There are a few good choices out there for source control. Personally, I like Subversion (SVN) the best. It’s free (open source) and a lot of very useful third-party tools are out there. TortoiseSVN is an excellent Windows GUI client and is free. AnkhSVN (now being developed by Collabnet, the company that hosts the SVN source control itself) provides source control integration into Visual Studio and is also free. Finally, there’s VisualSVN. They make a free server application called VisualSVN Server that allows you to get a Subversion repository up and running in minutes on a Windows server, complete with HTTPS access over Apache. VisualSVN also makes a Visual Studio source control add-in that’s comparable to AnkhSVN, although arguably more robust.
The two solutions I came up with (Method 1 and Method 2 below) both use VMWare Workstation for the virtualization platform and Subversion for source control. I’m sure one could adapt these steps fairly easily to work with other systems since the concepts behind them are what are important.
When I first had the need to manage my own source control, I had a single VM I used to work on my code.
The source control solution in this case was quite simple since I could pretty much put everything on that VM.
First I used TortoiseSVN to create a local file-based repository. You can use the command-line Subversion tool to do this as well, but TortoiseSVN makes it easy:
I usually put the repository itself in a standard location (like C:\SVN) so the repository URL in my Working Copy becomes something like file:///C:/SVN/my-repository:
You can do this a number of ways, but you want to make sure that whatever is backing up the repository is doing it automatically on a scheduled basis, so you don’t have to think about it. An online backup service (like Mozy.com) works well, but there’s a monthly service charge. I do all my backups on my wife’s computer, which is a MacBook. Therefore I can use TimeMachine, which is integrated into Mac OS, to backup everything important, including my source code repository.
However, my repository is still sitting in the file system of my VM which isn’t hosted on the MacBook – it’s on my laptop, which is running Windows. To sync the repository files to the MacBook so they can get backed up I use Windows Live Sync (used to be called FolderShare). It’s a free file syncing tool from Microsoft that can sync between multiple PC’s and Mac’s via your local network or over the internet and even through firewalls. All you need is a Windows Live ID to get started.
So as long as all my source code is developed on a single VM, I can keep the source control repository locally on that VM as a simple file-based SVN repository and use Live Sync and TimeMachine to keep my repository files backed up. Also, if I go mobile and/or the MacBook isn’t connected to the internet (so Live Sync can’t sync) I still have access to the repository so I can do all the source control operations I may need to keep developing code. Then the next time my VM is able to connect the Mac, it will sync the repository files so they can be included in the next backup.
The above solution works great until you decide to write your code on more than one VM. Perhaps you have a couple projects going that require different development stacks. Maybe one is an ASP.NET application running on IIS6 (Windows Server 2003) and another is on IIS7 (Windows Server 2008). In that case you really should develop your applications on separate VM’s, each running the correct version of Windows.
Of course, now the problem is accessing the file-based source control repository across multiple VM’s. One option is to move the SVN repository files to the host OS. Most virtualization solutions like Microsoft Virtual PC and VMWare Workstation have a file sharing feature where a VM can access files on the host OS. While this works, there’s a very noticeable performance hit. The other drawback to putting the SVN repository on the host OS itself is that it’s mixing a part of your development environment infrastructure into the host, which conflicts with why you moved everything to virtual machines in the first place.
A better approach is to move the repository to a dedicated VM that can act as a light-weight server and handle source control operation requests from all the client VM’s. Subversion can be run as a server in this way. It uses Apache to handle HTTP requests from clients and it seems perform nearly as well as with the local file-based repository.
Let’s take a look at how to set all this up.
The first step is to create this server VM which will host our shared repository and handle client SVN requests from the other VM’s. This VM won’t require a lot of RAM since it’s primarily just going to serve up request for source control operations. I created mine using Windows Server 2008, which has a minimum memory requirement of 512MB, so that’s what I went with.
Before we move on to installing additional software on the source server VM, we need to take care of some necessary networking infrastructure.
One of the other advantages of most virtualization systems out there is the ability to create virtual networks. If you have multiple VM’s that need to communicate with one another and especially if that communication needs to be private (or doesn’t need to occur over a public network), you can create a virtual network.
In my situation, I ended up using one of the available custom networks installed by VMWare Workstation (vmnet2 in my case). You don’t want to use the Host-Only, Bridge, or NAT networks as we need something that’s private that we can dedicate to these VM’s. In my case, to turn this on, I just added a network adapter to all the VM’s, including the server VM, and connected it to the vmnet2 virtual network:
This new network adapter showed up in the OS (Windows) of all the VM’s. To make them easier to manager, I renamed them from “Local Area Connection” and “Local Area Connection 2” to “Public LAN” and “Private LAN” in each VM:
Simply connecting the VM’s together with our new private network connection doesn’t make it so they can communicate (at least not very well) over the private network. It’s the equivalent to connecting a bunch of computers to a Ethernet hub or switch with network cables. Each host will default to a 169.254.x.x address and name resolution won’t work at all if each OS has their default firewalls turned on.
Ideally, we need some way of handing out IP’s and ideally having DNS name resolution to those IP’s (the most important one being the server). To do that we first need to pick an IP subnet and a static IP for the server VM. In my case I went with 192.168.76.x for the subnet and 192.168.76.1 for the static IP. I then set the IP address of the “Private LAN” network adapter on the server VM to that static IP, which is done in Windows itself:
Next we need to turn on DNS services on the server VM so it can resolve DNS names local to our virtual network. After installing the service, I created a forward lookup zone for a private DNS domain called “ts-local”. You can use whatever private DNS domain name you want as long as it isn’t something that might conflict with domain names on the internet or any other network you may connected to.
Then I added an A-host for the server VM itself whose hostname is “MCP”:
Next we need to enabled the DHCP server service on the server VM so we can hand out the IP’s in our subnet. Once you install the service, configure it to hand out IP’s to our subnet as well as specify the DNS server IP (same as the server VM) and the domain name (in my case “ts-local”):
Finally, we should be able to release and renew the IP address on each of the client VM’s and get an IP in our subnet. We should also be able to resolve the IP address of the server VM from the client VM’s using PING:
Now for the real reason we created this server VM in the first place. Setting up a Subversion server that uses Apache (the web server that SVN uses) by hand is no easy task (trust me, I’ve done it). VisualSVN Server makes this a snap. It will install Apache, configure HTTPS, and create a location for the repositories. By default, VisualSVN Server creates the repositories directory at C:\Repositories. I prefer C:\SVN.
After the install is complete, all you have to do is create a username for your client VM’s to use to access the repositories.
If you started with Method 1 like I did, you need to move the file-based repository from the single VM to our shiny new Subversion server VM. VisualSVN Server makes this easy with it’s import option:
Simply browse to where the repository files are and perform the import. You may want to copy them over to a temporary directory on the server VM first to make them easily accessible from the server’s file system.
Once the repository has been imported, you’ll want to set assign the user account you created earlier to have read/write access to the repository:
Your server is now ready to service source control requests!
If you already have Working Copies (the term Subversion uses for directories that are under source control) on your original development VM, you can point them at the new URL using TortoiseSVN’s Relocate function. For example, if you had a working copy connected to file:///C:/SVN/my-repository, you can now point it to http://mcp.ts-local/SVN/my-repository:
The final step to getting the multiple-VM source code repository operational is to configure the backup. The approach is the same as with the single-VM approach – you just have to back up the repository files on the server VM instead. In my case, that directory is C:\SVN. I point Live Sync there which syncs the files to my MacBook which in turn backs everything up via TimeMachine. Very nice!
The multi-VM solution also has the same disconnected benefits that the single-VM solution does. You can perform all your source code operations anytime you want, even if your host machine is disconnected from the network. The next time you are connected, Live Sync will sync any repository file changes to the MacBook so they can be backed up.
In my last post, we built an abstraction for a data access layer used by CSLA.NET business objects based on the Repository Pattern. We started by creating two base interfaces, IRepository<TContext> and IContext and then used them to define a set interfaces that abstracted the data access for a simple order entry system. Those interfaces were:
We then demonstrated how objects based on those interfaces would be called from the data access areas within actual CSLA.NET business objects (in the DataPortal_* methods). We also showed how the repository object was injected in via dependency injection. In our case, we used the Unity IOC Container but any IOC Container or dependency injection framework would do.
In this post we're going to build a concrete implementation of our abstract data access layer. In other words, we'll build classes that implement the above interfaces. In this case, we'll use LINQ to SQL as our actual data access technology. However, given the high level of abstraction of our repository pattern implementation, we could conceivable build concrete implementations in many other technologies such as LINQ to Entities, <insert your favorite ORM here>, or even plain old ADO.NET.
Before we jump into the implementation of our interfaces, we need to first build our LINQ to SQL classes. These classes will play an integral role in our concrete implementation.
LINQ to SQL requires that a physical database exist, so assume that we've started with a simple SQL Server database that contains an Orders table and a LineItem table with a one-to-many relationship between them. We can then add an Orders.dbml file (LINQ to SQL Classes item) to a Visual Studio 2008 project and drag both tables onto the design surface:
Visual Studio (actually LINQ to SQL) does a lot of work behind the scenes when we do this. It code generates a LINQ to SQL DataContext class called OrdersDataContext and two entity classes called Order and LineItem that map to the database tables.
You may also notice is the screen shot above that we've added a set of stored procedures to our database that perform all the inserts, updates, and deletes, and they show up as methods on the OrdersDataContext class. While LINQ to SQL entity classes have the ability to perform these operations on their own, they have a limitation that forces us to use a alternative mechanism, like stored procedures, instead. We'll investigate this issue further a little later on in the post.
At this point, the OrdersDataContext, Order, and LineItem classes could be used by a set of CSLA.NET business objects to perform all the required data access. However, the business objects would be be tightly coupled to the LINQ to SQL code and therefore there would be no easy way to abstract the LINQ to SQL code so it could be mocked for unit testing purposes. Let's see how we can migrate this code into a concrete implementation of our repository pattern abstraction.
Before we jump into the concrete repository and context objects, let's take a quick look at how we implement the DTO's. LINQ to SQL makes this relatively easy since the entity classes code generated by LINQ to SQL are the DTO's. All we need to do is make them implement our DTO interfaces. Since the LINQ to SQL code generation is done using partial classes, this is quite easy.
First the, concrete IOrderDto class:
partial class Order
: IOrderDto
{
byte[] IOrderDto.Timestamp
{
get
{
return this.Timestamp.ToArray();
}
set
{
this.Timestamp = new Binary(value);
}
}
IEnumerable<ILineItemDto> IOrderDto.LineItems
{
get
{
return this.LineItems.Cast<ILineItemDto>();
}
}
}
At a minimum, we need to define the partial class Order (which binds to the code-generated Order class at compile time) that implements the IOrderDto interface. But we also need to add a couple explicit IOrderDto property implementations.
The first is due to the fact that the Order class that was code-generated by LINQ to SQL has a Timestamp property that is of the LINQ to SQL-specific type Binary. However, the IOrderDto interface defines the Timestamp property as a byte array, which is not specific to a data access technology. Therefore we need to add the IOrderDto.Timestamp property explicitly and marshal the Binary and byte array values back and forth.
The second explicit property implementation is IOrderDto.LineItems. The Order class code-generated by LINQ to SQL also defines a LineItems property, but it's of type EntitySet<LineItem>. Therefore, we need to convert between the two and a handy way to do it is to use the Cast extension method.
The concrete ILineItemDto class is very similar, but we only have to add an explicit implementation of its the ILineItemDto.Property:
partial class LineItem
: ILineItemDto
{
byte[] ILineItemDto.Timestamp
{
get
{
return this.Timestamp.ToArray();
}
set
{
this.Timestamp = new Binary(value);
}
}
}
Now, with the concrete DTO's defined, let's move onto the concrete repository and context classes.
You may recall the role of the repository object is to be a factory for all of the other objects needed by the data access layer. It's main job is to create the associated context. Therefore our order repository will need to create an order context. It will also need to be able to create any DTO's required by data access methods that require DTO's as inputs.
Given that, here's our concrete OrderRepository class:
public sealed class OrderRepository
: IOrderRepository
{
IOrderContext IRepository<IOrderContext>.CreateContext(bool isTransactional)
{
return new OrderContext(isTransactional);
}
IOrderDto IOrderRepository.CreateOrderDto()
{
return new Order();
}
ILineItemDto IOrderRepository.CreateLineItemDto()
{
return new LineItem();
}
}
A fairly simple implementation of a factory. The CreateContext method creates a new instance of our concrete OrderContext (which we'll see its implementation just ahead), passing a value to its constructor, telling it whether or not it needs to be transactional. Then we have two methods for creating DTO's: CreateOrderDto and CreateLineItemDto. Notice that what we're actually returning are instances of the two entity classes code generated by LINQ to SQL since they implement the required DTO interfaces.
While the repository object is the factory that creates all the data access objects, the context object plays the star role in actually performing the data access operations. Therefore, the OrderContext class is going to have the most meat of any of our concrete repository pattern classes. Let's examine the OrderContext class in chunks since there's a lot going on.
First, let's take a look at the class definition itself and its constructor that we know takes a isTransactional boolean parameter:
public sealed class OrderContext
: IOrderContext
{
private OrdersDataContext _db;
private TransactionScope _ts;
public OrderContext(bool isTransactional)
{
_db = new OrdersDataContext();
if (isTransactional)
_ts = new TransactionScope();
}
}
As you can see, our OrderContext object wraps an instance of an OrdersDataContext object (via the _db field) which is a LINQ to SQL DataContext. Therefore, our OrderContext object is essentially an abstraction of a LINQ to SQL data context. When it implements the remaining IOrderContext interface members, it does this by making calls against that LINQ to SQL DataContext instance.
The OrderContext also wraps a TransactionScope object, which it only creates if the calling OrderRepository object specified that the context is transactional. That transaction is committed in the CompleteTransaction method, which is required by the IContext base interface:
void IContext.CompleteTransaction()
{
if (_ts != null)
_ts.Complete();
}
The last place we interact with this transaction is at the end of the order context object's lifecycle during the IDispose.Dispose implementation:
void IDisposable.Dispose()
{
if (_ts != null)
_ts.Dispose();
_db.Dispose();
}
We also dispose the OrdersDataContext which closes up the database connection.
So far with the OrderContext class we've implemented the creation and clean-up of the object. Now we need to implement the methods defined by the IOrderContext interface that actually do the data access.
First, let's take a look at the implementation of the IOrderContext interface's FetchInfoList method:
IEnumerable<IOrderInfoDto> IOrderContext.FetchInfoList()
{
var query =
from o in _db.Orders
orderby o.Date
select new OrderInfoData
{
Id = o.Id,
Customer = o.Customer,
Date = o.Date
};
return query.Cast<IOrderInfoDto>();
}
private class OrderInfoData
: IOrderInfoDto
{
public int Id { get; set; }
public string Customer { get; set; }
public DateTime Date { get; set; }
}
The purpose of this method is to return a list of all the orders in the database. They come back as the light-weight IOrderInfoDto objects. Our implementation of this method performs a standard LINQ to SQL query against the Order entity objects in the OrdersDataContext. However, we don't want to return all the data of each order. The IOrderInfoDto object is only a subset of that data. An easy solution is to perform a LINQ projection of Order objects to IOrderInfoDto objects. This will generate only the T-SQL necessary to populate the data required by the IOrderInfoDto objects. And of course we need a concrete IOrderInfoDto class to create and return; an easy approach is just to declare a private OrderInfoData class shown above just below the FetchInfoList method.
The next data access method required by the IOrderContext interface is FetchSingleWithLineItems:
IOrderDto IOrderContext.FetchSingleWithLineItems(int id)
{
var options = new DataLoadOptions();
options.LoadWith<Order>(o => o.LineItems);
_db.LoadOptions = options;
var query =
from o in _db.Orders
where o.Id == id
select o;
return query.Single();
}
This method is similar to the previous in that it is another LINQ to SQL query. However, it returns a single DTO (instead of a collection) and that DTO is an instance of the full Order entity class, which happens to implement the IOrderDto interface.
But we don't want to return just the data of the order itself. We also want to return all of it's child line item data as well (which will be accessible via the LineItems property), and preferably all with one call to the database. We can do this with a little LINQ to SQL magic by configuring the LoadOptions property of the OrdersDataContext, telling it that when it loads the data of an Order object, go ahead and load its child LineItem objects contained within the LineItems property.
The FetchInfoList and FetchSingleWithLineItems methods pretty much take care of all the data access querying. Now we need to implement the insert, update, and delete operations.
While the query method implementations simply took advantage of the built-in LINQ capabilities of the entity classes, we can't quite do the same with the insert, update, and delete methods. Normally, with LINQ to SQL you can make whatever state changes you want to those objects and when you're ready to persist those changes back to the database, you just call the SubmitChanges method on the DataContext object, which keeps track of which entity objects have changed.
While this approach could work in our situation, it requires us to maintain references to all of these objects between data access operations performed by our CSLA.NET business objects and this is a problem. All CSLA.NET business objects need to be serializable so they can function properly in the CSLA.NET DataPortal. This means that any objects contained within a CSLA.NET business object must also be serializable. Unfortunately, LINQ to SQL objects are not.
There are some potential workarounds like one where you create a new LINQ to SQL entity object, load it with data, and then attach it to a DataContext as if it were previously fetched by the DataContext, but this is not using LINQ to SQL as it was intended and in many cases produces unexpected behavior. The only reliable solution is to use a different mechanism than the LINQ to SQL entity objects and the DataContext to persist changes back to the database. One of the easiest is the use of stored procedures. This, in fact, is the same approach that Rocky uses with his LINQ to SQL data access code in his sample ProjectTracker application. In the Orders.dbml file in our project, we simply drag those stored procedures over from the database and LINQ to SQL adds them as methods to the OrdersDataContext.
The last thing we should mention about the insert, update, and delete methods is that, unlike the query methods which returned DTO's (or collections of them), these methods take DTO's as parameters (except for delete which typically only takes an ID). Therefore, the caller (in this case the CSLA.NET business object) needs to be able to create an empty DTO and populate it. Which is why the OrderRepository class has the DTO creation methods.
So, without further delay, here are the insert, update, and delete method implementations for the order entities:
void IOrderContext.InsertOrder(IOrderDto newOrder)
{
int? id = null;
Binary timestamp = null;
_db.insert_order(
ref id,
newOrder.Customer,
newOrder.Date,
newOrder.ShippingCost,
ref timestamp);
newOrder.Id = id.Value;
newOrder.Timestamp = timestamp.ToArray();
}
void IOrderContext.UpdateOrder(IOrderDto existingOrder)
{
Binary newTimestamp = null;
_db.update_order(
existingOrder.Id,
existingOrder.Customer,
existingOrder.Date,
existingOrder.ShippingCost,
existingOrder.Timestamp,
ref newTimestamp);
existingOrder.Timestamp = newTimestamp.ToArray();
}
void IOrderContext.DeleteOrder(int id)
{
_db.delete_order(id);
}
We also have insert, update, and deletes for the line item entities as well, but they are very similar, so I'll save them for the sample code download at the end.
To make all of this really gel, I wanted to include a fairly extensive sample application that demonstrates everything we've been talking about in the last three posts: dependency injection and the Repository pattern with CSLA.NET. However, this sample goes a bit further than what we've talked about so far so I wanted to briefly discuss it but save the details for an upcoming post.
A lot of what we've been building here are mechanisms to abstract each layer of our application so they are more loosely-coupled and more testable. This is why dependency injection is so useful and why patterns like Repository really help. But the Repository pattern is really just a means to abstract the data access layer. What if you wanted to abstract the business layer? What if you wanted to write unit tests that tested the functionality in your UI layer in isolation so that you wouldn't have to build concrete business objects in your tests? That's the one big additional thing that the sample application sets out to do. In short, it does this by defining abstractions (in the form of interfaces) for each business class and pulls out the static factor methods into separate factory interfaces and classes.
So here's a quick rundown of the projects that are included in the sample application solution, which is called CslaRepositoryTest:
Some other notes:
Finally, here's the sample application.
In this post we walked through a concrete implementation of our abstract data access layer that uses the Repository pattern. Our implementation used LINQ to SQL, but we could have easily created one that used any other data access technology. In an upcoming post, we'll dig a little further into how to abstract the business layer itself.
In a previous post I showed a way to use dependency injection with CSLA.NET. In this post, I'll show a practical example of how to use that technique to abstract the data access layer used by your business objects using the Repository pattern. This post is part 1. At the end of part 2, I'll include a link to a fully-functional demo application that even includes a fully functional business layer, data access layer, UI layer, and unit tests.
The default approach for data access in CSLA.NET is to write your data access code right in the business class in the DataPortal_* or Child_* methods. These methods have direct access to the internal state of the business object so they can easily persist that state to your data store without breaking encapsulation. While this approach obviously works, there are several reasons why one might want to move this code out of the business object and into its own layer. Here are few good ones:
Unfortunately, abstracting the data access layer is no easy task. There are a lot of choices and options, so you have to be careful that you don't end up limiting yourself. Here are a few things we need to consider:
The solution I chose to pursue was to follow the relatively well-known data access pattern called the Repository Pattern. Repository is a high-level abstraction of your data access layer that allows the caller to perform any necessary data access (queries, CRUD, etc) and get back a structured set of objects that represent the data. I like to call these objects DTO's (data transfer objects) since they are nothing more than strongly-typed data structures (just data, no logic). And since the Repository is a high-level abstraction, you gain the flexibility of being able to change the underlying data access technology in the future as well as do other fun tricks like data caching.
Given that description of Repository, there still are a lot of ways to implement it. Just do a Google search on "Repository Pattern" and you'll see what I mean. I've come up with what I think is a relatively simple approach that seems to work well with CSLA.NET. Let's take a closer look.
There are two key components to my Repository design: the repository and the context.
The repository represents the gateway to the data access layer. The repository will create all the necessary data access objects we need to perform our data access. Essentially it is a factory object and it can be injected into our business object via dependency injection.
When you want to actually perform data access operations, you usually want this to be done in a context of some sort that you can dispose of when you're done. Maybe you need to execute one or more calls atomically within a transaction or maybe you just need to do some querying and you want to ensure that the connection is closed when you're done, even if the query fails. This is what a context is for.
The repository's primary job is to create a context when the business object needs to perform data access. It can also create other data access objects, like DTO's, that may be needed to assist in performing data access.
So, let's take a look at what the repository and context might look like in code:
public interface IRepository<TContext>
where TContext : IContext
{
TContext CreateContext(bool isTransactional);
}
public interface IContext
: IDisposable
{
void CompleteTransaction();
}
Pretty simple. An IRepository object can create a specific type of IContext object, and when it does, you have to specify whether or not the IContext is transactional. If an IContext is transactional, it has a method called CompleteTransaction that is called by the business object to indicate that the transaction has succeeded and should be committed. And regardless if the IContext object is transactional or not, it is disposable which makes it easy for the calling business object to close things like database connections.
And by the way, I personally prefer to use interfaces for my abstractions (vs abstract classes) because they're much easier to mock in a testing scenario.
Notice that neither of these interfaces has any methods that perform specific database operation (ex: CRUD). I prefer to move those down into more specialized interfaces that abstract a specific set of entities in your data access layer. For example, here's a repository and a context for a simple order-entry system that contains order and line item entities:
public interface IOrderRepository
: IRepository<IOrderContext>
{
IOrderDto CreateOrderDto();
ILineItemDto CreateLineItemDto();
}
public interface IOrderContext
: IContext
{
IEnumerable<IOrderInfoDto> FetchInfoList();
IOrderDto FetchSingleWithLineItems(int id);
void InsertOrder(IOrderDto newOrder);
void UpdateOrder(IOrderDto existingOrder);
void DeleteOrder(int id);
void InsertLineItem(ILineItemDto newLineItem);
void UpdateLineItem(ILineItemDto existingLineItem);
void DeleteLineItem(int id, int orderId);
}
Most of the action is down in the IOrderContext object; it contains all of the data access methods that involve interacting with the database. There are two methods for querying and retrieving order data. The remaining methods perform the inserts, updates, and deletes.
Notice that my query methods are explicit: "fetch info list" and "fetch single order with line items". I've seen some Repository Pattern implementations out there that provide more generic query methods that allow you to harness the power of LINQ by returning an IQueryable<T> object. While there's nothing wrong with this approach, it does lock you into using data access technologies in your concrete implementation that only support LINQ. Some do, some don't (like ADO.NET). To be flexible, I chose to not lock myself into LINQ, so my query methods return simple IEnumerable<T> results. And even if you are confident that any data access technology you will use is LINQ-friendly, not all LINQ implementations are the same. For example: LINQ syntax for LINQ to SQL is a little different than LINQ syntax for LINQ to Entities.
Notice that all data is transferred to and from these data access methods via DTO's. The only issue is that these DTO's are interfaces so if the business object has to pass them to the context (say to the InsertOrder method), it needs a way to create one first. That's where the DTO factory methods on the IOrderRepository object come into play. This further cements the concept that the repository is really an object factory.
Before we move on, let's take a look at the definition of the DTO interfaces in my example.
First, the IOrderInfoDto which is returned by the FetchInfoList method:
public interface IOrderInfoDto
{
int Id { get; set; }
string Customer { get; set; }
DateTime Date { get; set; }
}
This is giving us only a portion of the fields that may be defined by the order entity in the database. The purpose of this DTO (and the ReadOnlyBase<T> business object it populates, is to provide a simplified view of order data, perhaps to populate a list in the GUI.
When we need a single entire order, the FetchSingleWithLineItems method returns the IOrderDto object:
public interface IOrderDto
{
int Id { get; set; }
string Customer { get; set; }
DateTime Date { get; set; }
decimal ShippingCost { get; set; }
byte[] Timestamp { get; set; }
IEnumerable<ILineItemDto> LineItems { get; }
}
It contains pretty much the same data as IOrderInfoDto plus the remaining order entity data and also a collection of child line items. Those line item objects are of type ILineItemDto:
public interface ILineItemDto
{
int Id { get; set; }
int OrderId { get; set; }
string ProductName { get; set; }
decimal Price { get; set; }
int Quantity { get; set; }
byte[] Timestamp { get; set; }
}
By the way, both the IOrderDto and ILineItemDto interfaces contain a Timestamp property which is used to manage data concurrency. This timestamp has to be persisted into the business object itself. I'll show how this is done in the sample code, but Rocky also does it in his ProjectTracker sample application.
I think to really see how this implementation of the Repository Pattern works, we should take a look at how a business object would call these data access objects. Let's examine the simplest case of a root-level collection of read-only order business objects (we'll name it OrderInfoCollection) performing its data access while fetching the collection.
private void DataPortal_Fetch()
{
RaiseListChangedEvents = false;
using (var context = EnsureDependency(_repository).CreateContext(false))
{
IsReadOnly = false;
foreach (var dto in context.FetchInfoList())
{
var child = DataPortal.FetchChild<OrderInfo>(dto);
this.Add(child);
}
IsReadOnly = true;
}
RaiseListChangedEvents = true;
}
The code follows the standard pattern for the implementation of the DataPortal_Fetch method of a business object that inherits from ReadOnlyListBase<T,C> where we turn off list-changed events and make the collection temporarily writable while we load it. But instead of opening up an ADO.NET database connection or creating a LINQ to SQL data context, we talk to an abstract repository instance instead and call CreateContext which returns us a IOrderContext instance. All context objects implement IDisposable so we wrap it in a using statement which guarantees things like database connections and transactions will be closed up at the end.
Within our using block is where we make all the data access method calls against the context. In this case, we're calling FetchInfoList, enumerating the IOrderInfoDto objects returned, and using each to create an associated child OrderInfo business object for the collection.
You may be asking: where does the instance of the _repository field get created and what's this EnsureDependency method? This goes back to how I implement dependency injection with CSLA.NET which I detail in the previous post. Here's the definition of that field and the method that Unity (my dependency-injection/IOC Container framework of choice) uses to inject it:
[NonSerialized]
[NotUndoable]
private IOrderRepository _repository;
[InjectionMethod]
public void Inject(IOrderRepository repository)
{
if (repository == null)
throw new ArgumentNullException("repository");
_repository = repository;
}
This is the magic that allows us to easily mock out the data access layer at test-time and use a real concrete implementation at run-time. Showing how you would mock these objects is a bit more than we have time for now. However, I will provide unit tests that show it in the downloadable sample code at the end of part 2.
So we showed the simple example of how a read-only collection would call the data access layer to query the database and populate itself. Let's also show an example of some data access code in a business object that's transactional.
Let's jump over to a full BusinessBase<T> business object for an order (we'll call it Order) and take a look at what the DataPortal_Insert method implementation might look like for inserting an order:
protected override void DataPortal_Insert()
{
using (var context = EnsureDependency(_repository).CreateContext(true))
{
var dto = EnsureDependency(_repository).CreateOrderDto();
dto.Customer = ReadProperty<string>(CustomerProperty);
dto.Date = ReadProperty<DateTime>(DateProperty);
dto.ShippingCost = ReadProperty<decimal>(ShippingCostProperty);
context.InsertOrder(dto);
LoadProperty<int>(IdProperty, dto.Id);
_timestamp = dto.Timestamp;
DataPortal.UpdateChild(ReadProperty<LineItemCollection>(LineItemsProperty), this, context);
context.CompleteTransaction();
}
}
A little more complicated, but the pattern is very similar. We create a context (this time specifying that it's transactional) and we perform our data access operations against it. In this case we to first create an empty IOrderDto so we can populate it with the business object state and pass it into the InsertOrder data access method. When that's done we load the ID and timestamp of the newly inserted order entity back into the business object. Finally, we cascade the update call down to any child line item business objects.
So this is all great and fun and with just the code we've written so far we could get our business layer up and running with passing unit tests. But with all of that we still haven't actually hit a real database! We need to code up a concrete implementation of our repository interfaces to get there. I'm going to save that for the next post and with that post will come the promised full set of sample code.
In this post, I'm going to talk about one way to implement Dependency Injection with CSLA.NET.
NOTE: My discussions and code samples are using CSLA.NET 3.5.
CSLA.NET. I'm a big fan. I have been even back before it went .NET in the VB5 and VB6 days.
I don't know actual statistics, but I would wager that CSLA.NET is probably the most popular framework for creating object-oriented business objects in .NET. If you're building even a moderately complex line-of-business application where you want your business logic to live in one place (instead of spread all over the place, the worst being in your UI), you want a middle tier that takes advantage of object-oriented design (not just a set of classes that mimic the structure of the database), and optionally have everything just work in a distributed environment, then you should definitely take a close look at CSLA.NET.
I'm also a big fan of automated tests around my business layer. And when I say tests, I'm referring to unit tests, where I want to validate just the behavior of my business object and nothing else. In other words, I'm not interested in testing the other layers that my business object may interact with (like the database or a logging component). Those would be integration or regression tests. Those are good too, by the way, but unit tests should come first.
Since business objects almost always have to communicate with other layers, your unit tests need the ability to fake those layers out in order to test your business logic in isolation. There are variety of ways to do this, but a popular one is to abstract calls to these layers using Dependency Injection and then use a mocking framework to inject a fake version of that layer. To really do Dependency Injection, you need to use a framework of some kind (typically called an IOC Container) to handle your dependency instances and automatically perform injections on your objects.
So, like I said, I really love the CSLA.NET framework. But with all of its awesome excellence, I've always been challenged writing true unit tests against business objects that use it. This is because CSLA.NET makes it difficult to implement Dependency Injection. Why? In short: CSLA.NET creates your business object instances for you. This happens in the servers-side portion of the DataPortal. Dependency Injection works best if it can have some kind of access to the object creation process so an object's dependencies can be injected. Unfortunately, the DataPortal does not provide any sort of hook where you can create your object. The DataPortal does this all behind the scenes as a black box and then gives you your object instance after creation, letting you then execute your data-access code in the DataPortal_* methods.
To be fair, the latest version of CSLA.NET, 3.6 which just released, does give you access into the creation of your business objects via the new object factory feature. However, there are two challenges with going down this road:
There is also another challenge, and that is that the creation of objects on the server-side of the DataPortal isn't the only place business objects in CSLA.NET are being created! One of the great features of CSLA.NET is this idea of mobile objects: your business objects have the ability to be transported from one physical tier to another. However, every time an object goes mobile it needs to be serialized. When it gets to the destination tier, it needs to be deserialized and deserialization involves recreating the object instance except this time its done within the bowels of the .NET Framework. Yuck! Even more difficult to hook into. And by the way, as of CSLA.NET 3.5, for consistency this serialization/deserialization process even occurs when everything happens in-process on one physical tier.
The solution I finally stumbled upon essentially gave up on the idea of trying to hijack the object creation process either in the DataPortal or worse yet in the .NET Framework itself during deserialization.
The good news is that most IOC Container frameworks out there allow you to perform dependency inject with an existing object instance. In my case, I'm using Unity, the IOC Container from Microsoft, which is a member of their Application Blocks family. Unity's container object has a method called BuildUp that let's you do exactly this.
And the other piece of good news is that CSLA.NET allows very easy access to an object instance just after it is created either by the server-side DataPortal or by deserialization. All you have to do is override a couple virtual methods and you're done!
My implementation of this was to create a set of base classes that all inherit from main CSLA.NET base classes that do the necessary overrides and perform the dependency injection. Let's build the base class for BusinessBase<T>, probably the most used CSLA.NET base class.
First, let's get the basics out of the way. We'll declare an abstract class called InjectableBusinessBase<T> that inherits from BusinessBase<T> and contains a protected constructor, which all abstract classes should have:
[Serializable]
public abstract class InjectableBusinessBase<T>
: BusinessBase<T>
where T : BusinessBase<T>
{
protected InjectableBusinessBase() { }
}
Now, let's add the necessary overrides to hook into post-object creation so we can kick off our dependency injection:
protected override void DataPortal_OnDataPortalInvoke(DataPortalEventArgs e)
{
Inject();
base.DataPortal_OnDataPortalInvoke(e);
}
protected override void Child_OnDataPortalInvoke(DataPortalEventArgs e)
{
Inject();
base.Child_OnDataPortalInvoke(e);
}
protected override void OnDeserialized(StreamingContext context)
{
Inject();
base.OnDeserialized(context);
}
First we overrode DataPortal_OnDataPortalInvoke. This gets called by the server-side DataPortal when a root level business object is created. Then we overrode Child_OnDataPortalInvoke which gets called by the server-side DataPortal whenever a child object is created by the DataPortal (a new feature as of CSLA.NET 3.5 that I highly recommend). Finally, we overrode OnDeserialized, which, through the help of BusinessBase<T>, gets called by the deserialization process of .NET.
In all three cases, we're calling an Inject method, which is a private method declared in our base class. It looks like this:
private void Inject()
{
var type = this.GetType();
Ioc.Container.BuildUp(type, this);
}
Nothing too fancy here. We're essentially calling the Unity BuildUp method which requires the type of our business object and the business object instance itself.
What is a little exotic, if you're familiar with Unity, is the Ioc.Container code. Our base class needs some way to access the Unity container instance against which to call BuildUp. I've created a utility class called Ioc that has a static Container property that returns this. I'll include the code for this class as well as all the code for the various base classes at the end of this post. For now, just know that the code Ioc.Container returns our IOC container.
That pretty much is all that's required to make dependency injection work with CLSA.NET and Unity! However, I do have one more method I want to include in my base class:
protected TDependency EnsureDependency<TDependency>(TDependency dependency)
where TDependency : class
{
if (dependency == null)
throw new MissingDependencyInjectionException(this.GetType(), typeof(TDependency));
return dependency;
}
The purpose of this method will become a little more clear when we take a look at an example concrete business object class that inherits from InjectableBusinessBase<T>. Essentially all this method does is return the same object that gets passed in. However, before it returns it, the method checks to make sure the object is null; if so, it throws a custom exception that basically says a required dependency instance is missing that it's of a certain type and is contained within the object of this type. I'll include the source code for this exception class at the end of the post as well.
To make all this gel, let's code up a concrete business object class that inherits from our base class. I'm going to code up a very simple Customer class that has two properties, ID and Name, and a single Fetch factory method. Here's the code so far:
[Serializable]
public sealed class Customer
: InjectableBusinessBase<Customer>
{
private static PropertyInfo<int> IdProperty =
RegisterProperty<int>(new PropertyInfo<int>("Id"));
public int Id
{
get { return GetProperty<int>(IdProperty); }
}
private static PropertyInfo<string> NameProperty =
RegisterProperty<string>(new PropertyInfo<string>("Name"));
public string Name
{
get { return GetProperty<string>(NameProperty); }
set { SetProperty<string>(NameProperty, value); }
}
private Customer() { }
public static Customer Fetch(int id)
{
var criteria = new SingleCriteria<Customer, int>(id);
return DataPortal.Fetch<Customer>(criteria);
}
}
Nothing new here other than the class inherits from InjectableBusinessBase<Customer>. We have two properties declared using the new CSLA.NET 3.5 managed property syntax. Then we have the standard private constructor and the static factory method which uses the DataPortal to create and fetch our business object from the database.
Now I want to introduce a dependency into my class that performs the actual data access necessary to fetch the customer, which will be performed in a standard DataPortal_Fetch method. This data access object will implement a custom interface called ICustomerDataAccess and will have a method called FetchData that takes a customer ID and returns a DTO that contains my customer data. Here's what my ICustomerDataAccess interface might look like:
public interface ICustomerDataAccess
{
ICustomerDto FetchData(int id);
}
By the way, a DTO (data transfer object) is just an object that contains nothing but data. For mocking purposes, my DTO is an interface (called ICustomerDto).
In an upcoming post, I'll show a more elegant way to abstract away the data access layer in CSLA.NET using dependency injection and the Repository pattern.
Let's add a field to my class that will contain this dependency:
[NonSerialized]
[NotUndoable]
private ICustomerDataAccess _dataAccess;
Notice that I've added two attributes to this field. The first, NonSerializedAttribute, is important because we don't want this dependency (or probably any dependency) to be serialized if the business object were to become mobile and transferred from one physical tier to another. In the case of data access, it really only needs to occur on the tier that performs data access (i.e. an application server).
The second attribute, NotUndoableAttribute, comes from the CSLA.NET framework. It tells CSLA.NET that this field is not to participate in the undo functionality provided by the BusinessBase<T> class. This is because the dependency does not contain any business object state that would need to be rolled back if the users were to perform an Undo.
Having both of these attributes in place essentially relieves us of the need to make our dependency serializable. The actual implementation class of ICustomerDataAccess can be just a plain old object.
Now we need a way to inject this dependency into our business object. Unity gives you three ways: constructor, set-able property, or method. We can't use the Customer constructor since we're performing the dependency injection after the instance has been created by the DataPortal or deserialization. We could use the set-able property. However, I personally like the method approach since, if you have multiple dependencies, you can inject all of them in a single call.
We just have one in our example, so here's the code:
[InjectionMethod]
public void Inject(ICustomerDataAccess dataAccess)
{
if (dataAccess == null)
throw new ArgumentNullException("dataAccess");
_dataAccess = dataAccess;
}
My method can be named anything, but it needs to be decorated with the special Unity InjectionMethodAttribute and it needs a parameter for each of my dependencies so I can set the fields. Notice I also throw an ArgumentNullException if whatever is doing the injection passes in a null. We want to fail if this ever happens.
Finally, we need to add the DataPortal_Fetch method that will use our data access dependency:
private void DataPortal_Fetch(SingleCriteria<Customer, int> criteria)
{
var customerData = EnsureDependency(_dataAccess).FetchData(criteria.Value);
LoadProperty<int>(IdProperty, customerData.Id);
LoadProperty<string>(NameProperty, customerData.Name);
}
The first thing we do is call the FetchData method of my ICustomerDataAccess object to obtain the customer DTO. Here is where you can see the EnsureDependency method in action that we coded earlier in the base class. If we wrap the _dataAccess dependency in a call to EnsureDependency, we know we're not going to get a NullReferenceException, which is non-descriptive and hard to debug. Rather we'll get a more descriptive exception that explains exactly what dependency is missing from what object.
Once we have the DTO, we can simply populate our business object in the standard CSLA.NET 3.5 way.
There you have it! Dependency Injection and CSLA.NET living peacefully side-by-side.
If you'd like to take a look at the complete set of source code for this, which includes all the Injectable* base classes, the MissingDependencyInjectionException class, the Ioc helper class, and the sample Customer business object code, you can download it here. Before the sample code will compile, you will also need to download CSLA.NET 3.5 and Unity 1.2 and update the assembly references accordingly.
Now I'm not pretending that this is the only way to make this work. If there are other people out there who've made Dependency Injection and CSLA.NET work better, perhaps with a different IOC Container like StructureMap or Castle Windsor, write a comment and let me know!
Per Scott Hanselman's recent blog post on the best code syntax highlighter for your blog, I'm giving his suggestion a try, which is to use the PreCode plug-in for Live Writer (a free blog writing GUI from Microsoft), which renders your code snippets so they use the SyntaxHighlighter JavaScript library.
I host my blog on Google's Blogger and so I don't have an easy way to host the necessary JavaScript files to make SyntaxHighlighter work. But I do have a Google Pages account, so I was able to upload them there and modify my blog's HTML Template in Blogger to include the necessary <link> and <script> tags to make the magic happen. I used tips from this blog post to get it working.
I wanted to get this set up since I'm about to post three (yes three!) blog entries on CSLA.NET which will probably contain a fair amount of code.
Anyway, without further adieu, here's my first SyntaxHighlighter code snippet, generated by the PreCode plug-in:
public interface IFoo
{
void Bar();
}
public class MyFoo
: IFoo
{
public Bar()
{
//do something
}
}
NOTE: If you're using a feed reader like Google Reader, this code won't look like anything special. You'll have to open the blog page directly to see the full effect.
