Visual Studio Projects: A Tutorial in Setting Up Solutions to Succeed

As a consultant, I have spent time in numerous environments at various companies. And while I find differences in each of the environments, there are some elements I find in multiple companies that impede there development efforts. One of these is setting up their projects.

In this post, I am going to show a general method of setting up a Visual Studio project that works well on projects that encompass numerous teams, or even program level development that spans multiple applications. The goals of the method are:

• Aid in creating testable software
• Increase team velocity by allowing teams to work in parallel
• Develop with lower risk

In this post, I am going to cover the following topics, from a high level view.

• Domain Driven Design
• Contract First Development
• Loose Coupling and Separation of Concerns
• Working with multiple teams

The items above are covered rather loosely, so I will call them out as we approach them.

Contract First

Let’s jump in feet first.

Rather than beat around the subject, one of the core elements of my set up is focusing on contract first development. This is a paradigm shift for many people in two respects.

1. Contract First means you spend time planning the contracts up front, rather than developing via a stream of consciousness, determining contracts later
2. Contract first dictates setting up interfaces for your software, which many developers are not used to, until they need to add an interface

The core of contract first is I determine anywhere there is a boundary and figure out its public interface, or contract, up front. Some of the boundaries are obvious, as they end up in some form of “user” interface (“user” in quotes here, as the user may be a system, not a human being). A good example of this type of boundary, from a systems perspective, is a “web service”. Note that “web service” here means any service that can be served via a network, so this could be ASMX, Remoting or WCF. When many people talk about web services, they generally only focus on services that reside in IIS and use SOAP, but I don’t see the server or message protocol as a determinant factor, especially when we look at WCF which allows you to switch protocols quite easily. If you want to simply the definition, you can call this a service boundary.

The other main boundary we routinely work with is an assembly boundary, which is exposed the public methods on our classes. In reality, this is the same boundary as a web service, except how the interface is expressed (no WSDL for an assembly). That and we can have an assembly boundary in a single process.

I could mention separation in boundaries, like in-process, out-of-process on same machine, different machine, etc., but the main difference in type of contract  lies in how the contract is expressed.

Contract Expression

On of the simplest expressions of contract is an interface. In .NET languages, you will add an interface to your project, like so:

public interface IRepository<T, in U>
    where T : class 
    where U : struct
{
    IQueryable<T> GetAll();
    T GetById(U id);
    void Create(T obj);
    void Save(T obj);
    void Delete(T obj);
}

public interface IQuoteRepository : IRepository<Quote, int>
{
    IQueryable<Quote> GetAllByAuthorName(string authorName);
}

 

To create a concrete example, you will have the class adhere to the interface, like so:

public class QuoteRepository : IQuoteRepository
{
    public IQueryable<Quote> GetAllByAuthorName(string authorName)
    {
        throw new NotImplementedException();
    }

    public IQueryable<Quote> GetAll()
    {
        throw new NotImplementedException();
    }

    public Quote GetById(int id)
    {
        throw new NotImplementedException();
    }

    public void Create(Quote quote)
    {
        throw new NotImplementedException();
    }

    public void Save(Quote quote)
    {
        throw new NotImplementedException();
    }

    public void Delete(Quote quote)
    {
        throw new NotImplementedException();
    }
}

Fairly simple and I believe we all get this. If we need a service boundary, we will add some attributes to the class and the interface. I then can create a Web Service Description Language (WSDL) file that describes the interface in a way it is easily consumable from a variety of environments.

The point here is the interface is a good code description of a contract, while WSDL is a good way to express the same contract for a “web service”.

Setting Up for Contract First

In Visual Studio, this is an easy exercise. The rule is every time I have a boundary, I need to have interfaces defined. The most common way I see this done is like the following screen capture:

If we run this setup against our goals, we find that we have aided the creation of testable software, as we have interfaces. And, with the interfaces, we have some ability to run teams in parallel, provided the team implementing the library does not change the library too radically. But we still have a high risk of halting development if someone from the library building team checks in broken code, as we cannot utilize the latest library for our interfaces.

There is a way to alter the solution setup to mitigate this risk: separate the interfaces. The following screen shot shows this method:

We can then isolate our teams by creating two solutions, as seen below:

Setup for Library Building team is shown in the previous example, while the setup for the team consuming the library to build the business tier library(s) is set up as follows:

The important takeaway here is both the data and business teams use the domain models and the contracts. The data team is setting up concrete implementations, while the business team is working with mocks and stubs that adhere to the contracts (interfaces). Note also that the business team can set up contracts (highlighted in the screenshot above) so the UI team can work from mocks and stubs.

Very early in the process, we should have the interfaces completed and then compile the .Contracts projects and include the compiled libraries. This should be done as soon as the contracts are firmed up and completed. The reason for doing this is it reduces the temptation to change contracts without thinking them through. This reduces the risk of having teams develop in parallel. It can also foster communication between teams, as it is quite clear when you change contract you are working with “publicly released” software, even if it is only internal to the company.

Working on the Domain

The domain is another area we have to spend some time on. In my projects, I will divide the entire solution into the following “layers” or “tiers”.

• UI – contains one or more user interface projects
• Business – contains the application logic
• Data – Data Access bits
• Framework – Components shared across multiple applications
• Domain – Domain (data) models shared across layers
• Test – Unit and Integration tests coded with a particular unit test framework

I will cover these in a bit.

Nearly every project will consume the Domain project, as it contains the domain models. The data layer will be responsible for filling the models and persisting them back. The actual data access technology should not matter (DataSets, EF, LINQ to SQL), as the models are independent of access. The business layer will perform business rules validation, etc, on the models. And the UI will bind the models in many cases. I say “many cases” as certain UI technologies may be more suited to creating presentation models that may or may not have direct parity with the domain models. A prime example of this is MVVM (Model – View – ViewModel), which is commonly used with Silverlight. The idea of separating domain models from presentation models is also present in ASP.NET MVC, especially when strongly typed models are used on your views.

Step-By-Step

Before going through the steps, let’s make up a silly story of what we are building.

Greetings, Inc. is a company that creates hello messages that plug into other company’s application. They are interested in a web application version of their old COM based application that delivers a personalized Hello message with a random quote. The application is to be developed using .NET technologies and has to be flexible enough to support various user interfaces.

I am in the process of researching setting this up as a template and sharing it. I am not there yet. So, here is a brief step-by-step on how I set up a project. This explanation goes through the ideal order of setting things up.

1. Create an Empty Solution with the following naming convention <CompanyName>.<ProjectName>. In this case, the application is GreetingsInc.HelloWorld
   
2. Create Solution folders in Visual Studio 2010
   

   

3. Create the same folders in Windows Explorer – this is an optional step, but I find it easier to develop this way, as my logical folders correspond to a physical folder. To do this, I run the following script (makeDirectories.bat):

   mkdir Business
   mkdir Data
   mkdir Domain
   mkdir Framework
   mkdir Test
   mkdir UI

   cd Data
   mkdir SqlServer

   This creates the following structure:
   

4. The next step is to create a domain model project: GreetingsInc.HelloWorld.Domain
   

   After creating the project, I create my two domain models: HelloMessage (the full message) and Quote (quote returned from database):

   

5. Add a project to the Data folder called GreetingsInc.HelloWorld.Data.Contracts
   
6. Reference the Domain project
7. Add a Generic Repository and then HelloMessage and Quote repositories:

   

We can go on here, but at this point, I am ready to start Test Driven Development of my business layer and allow the developers of the data layer to go off and start developing their work on an independent schedule. Here is how the interfaces appear:

Here are two tasks that can now be done in parallel:

• Data tier team begins setting up Repositories for data access, adhering to the interfaces
• Business tier team sets up mocks for the Repository to deliver a known answer and use them to create the business functionality

Summary

One of the most oft missed portions of development schedules is starting with decoupling as a first step. By focusing on the domain models first, then contracts, you force the project to a very loosely coupled state. In addition, you set up the work so the contracts (interfaces here) can be compiled and consumed in a “locked” state, reducing risk of the project not being able to integrate at a later date. This is an extremely valuable exercise.

Peace and Grace,
Greg

Twitter: @gbworld

World’s laziest or most clueless recruiter

I wanted to share an email with my audience. This is an email I got from a recruiter today who OBVIOUSLY DID NOT READ MY RESUME at all. Let’s see if you get a chuckle out of this (name removed to protect the guilty):

Hello,

I recently came across your resume on the internet and believe the job opportunity below would be of interest to you. It is a 3 month contract paying $17.00 an hour at a large bank in Nashville, TN. If you or someone you know is interested and meets the below qualifications, send resume in word format, desired hourly rate and best number to contact you.

NO CORP TO CORP

NO SPONSORSHIP AVAILABLE for this position

NO THIRD PARTY RESUMES

JOB DESCRIPTION

Duration: 3 months

Searching for an individual who will function as a PC Builder. The individual will build workstations using standard image, install custom applications via pre-established installation scripts, deliver machines to the customer and provide necessary support. S/He must have expertise in MS Windows XP and application installations. Must be able to effectively troubleshoot, work with customers and have strong organizational and record keeping skills. A minimum of 1 year relevant experience is required.

Thank you,
Clueless Recruiter
CluelessRecruiter@SomeCompanyInGeorgia.com

I am used to recruiters wasting my time, but I am sincerely convinced this guy is shotgun blasting resumes out to anyone who has a pulse and knows how to spell the word PC. If you want a few more chuckles, here is the email I sent him (and his boss):

CluelessRecruiter:

I am not sure what resume you are reading, but although I can easily build computers, and have done many of my own, it is not a skill even remotely mentioned on my resume. In fact, I have been a senior software architect for many years, and, if this were daytime, I would probably make the $17 in about the time it takes me to check my morning email.

I am not sure “shotgun blasting” is the best approach to get talent. In fact, it makes your company look rather amateurish. Good luck on filling the position. I am not one who even knows where to start to help on this one.

Peace and Grace,
Gregory A. Beamer

Have fun sharing!

Peace and Grace,
Greg

Twitter: @gbworld

Isolating the Data Store: A Brief Discussion on Microsoft Data Access and Domain Modeling

Recently, I had a geek acquaintance waxing on about the frustrations he was experiencing upgrading an application from DataSets to Entity Framework entities. He asked how I dealt with changes in data technology in my own applications. I told him it was not really a huge problem for me, as I did not consume data access “objects” outside of the data tier. This caused a bit of a “deer in the headlight” look that convinced me we needed a paradigm shift talk.

There are three basic data access technologies in .NET, if you leave out the roll your own and third party solutions. They are:

1. DataSets – This is the oldest and is basically a nice XML container for any number of “tables". It is a very flexible method of data access and is also quite easy to serialize, especially if the consumer is also .NET.
2. LINQ to SQL – LINQ to SQL was created to fill in the gap between DataSets and Entity Framework. I have a personal affinity against LINQ to SQL, especially in web applications, but that is a story for another day.
3. Entity Framework – Entity Framework (EF) is the latest Microsoft technology and also the least mature. In the latest incarnation, EF has the ability to map to POCO (Plain Old CLR Objects), but I would not use the POCO bits as a Domain model.

If you get one thing from the above, it is that you cannot easily trade one of the object models for another if you have bound the “objects” to the UI layer. That is the reason for this blog entry. So let’s look at what we do and why and then examine another way.

What we do

Let’s suppose we are building an application for the shipping department. The problem is the old shipping application is not aware of the cheapest way to ship to a customer, so we need an application that will examine different methods and figure the lowest price, based on the customer’s shipping constraints. The company already has an eCommerce application, a warehouse application (the old shipping application, as well), etc. This application is strictly concerned with shipping out the merchandise.

Using the methods I normally see, if we had to create the database, it might look something like this:

And this works well. We probably also have an order, order detail, a product table. But, this is a good start. Following the top down (UI to database) or bottom up (database to UI) approaches, we would probably end up creating an object for each of these tables. We might even use DataSets, LINQ to SQL or EF to create the objects we use in our user interface and merely ignore the parts we don’t wish to use for the shipping application.

The problem with this approach is updating from a DataSet coupled to the UI to an Entity is major surgery, a real PITA.

The Domain Driven Approach

In Domain Driven Design, we might look at this problem a bit differently. Since we only need a customer name and an address. We could well set up the customer to look like the following:

public class ShippingCustomer
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string AddressLine { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string PostalCode { get; set; }
}

Now, that is not a customer in the traditional sense, but to ship to this customer, this is all we need. Now, how do we best fill the object? I would probably use a SQL statement like the following:

SELECT c.FirstName
    , c.LastName
    , a.AddressLine
    , a.City
    , sp.StateProvinceName
    , a.PostalCode
FROM Customer c
JOIN Customer_Address ca
    ON c.CustomerId = ca.CustomerId
JOIN AddressType at
    ON ca.AddressTypeId = at.AddressTypeId
JOIN Address a
    ON ca.AddressId = a.AddressId
JOIN StateProvince sp
    ON a.StateProvinceId = sp.StateProvinceId
WHERE at.AddressTypeName = 'Shipping'
AND c.CustomerId = @CustomerId

And, I can easily do this with any of the three data access methods. With the DataSet, I can create a DataTable and then use a custom TableAdapter to fill it. With LINQ to SQL, I will end up either connecting to a stored procedure or a rather complex LINQ to SQL statement. With the Entity Framework, I can model it in a variety of ways.

BUT … I am not going to use these objects in my business layer or user interface. Instead, I am going to map the objects to my domain object or set up some type of translation helper bits or perhaps even a layer.

The Repository and mapping

Okay, so let’s set this up with different types of methods of pulling data. My first step is to set up an Interface for the Repository(s):

public interface IShippingCustomerRepository
{
    ShippingCustomer GetById(int id);
}

Okay, cool. Per my last blog entry on repositories, we can also genericize this. Since this is only one method, it is a bit ridiculous, but it can go like this:

public interface IRepository <T,U>
    where T : class 
    where U : struct
{
    T GetById(U id);
}

public interface IShippingCustomerRepository : IRepository<ShippingCustomer, int>
{
}

This is a useful pattern when you have some custom methods, as in the previous blog entry, even if it looks a bit nauseating right here. Let’s implement this with a DataSet:

public class DataSetShippingCustomerRepository : IShippingCustomerRepository
{
    public ShippingCustomer GetById(int id)
    {
        ShippingCustomerDataTable table = new ShippingCustomerDataTable();
        ShippingCustomerTableAdapter adapter = new ShippingCustomerTableAdapter();

        adapter.FillById(table, id);

        if (table.Rows.Count > 0)
            return DataSetMapper.MapShippingCustomer(table.Rows[0]);

        return null;
    }
}

Not the greatest implementation, but the important concept is we are not passing back a DataRow, we are passing back a mapped object. We can do the same type of mapping for LINQ to SQL and EF. We then just need a mapper:

public class DataSetMapper
{
    public static ShippingCustomer MapShippingCustomer(ShippingCustomerDataRow row)
    {
        return new ShippingCustomer() { FirstName=row.FirstName, row.LastName
            , AddressLine=row.AddressLine, City=row.City,  row.PostalCode, row.State}
    }
}

Important Takeaway

Perhaps the examples in this entry aren’t the best, but they do illustrate that the application and UI use the domain model and not the bits thrown back from Microsoft. And, I can easily switch from one data model to another without rewriting the application. To put this another way, my data access and database are very loosely coupled to the application.

Peace and Grace,
Greg

Twitter: @gbworld

Generics on the Data Access Layer

I was playing around with a bit of code last night and thought about the repository again. It was not a deep thought, but as it stuck for awhile, I thought about how the data repository is a nice pattern for truly understanding generics in .NET, as it is very practical.

The Basics of Generics

Before going further, let’s look at generics and the problems they solve. Here is a little snippet of code with both a generic and non-generic version:

SortedList sortedList = new SortedList();
sortedList.Add(1, "one");

SortedList<int, string> sortedList2 = new SortedList<int, string>();
sortedList2.Add(1, "one");

Note that I can easily flip both so the string is the key, as in the following:

SortedList sortedList = new SortedList();
sortedList.Add("one", 1);

SortedList<string, int> sortedList2 = new SortedList<string, int>();
sortedList2.Add("one", 1);

When you read about non-generics, one of the first things talked about is boxing and unboxing. This is true and can affect performance, etc. But one of the more germane issues is whether you catch an error at runtime or compile time. With the generic version, this will not work:

SortedList<string, int> sortedList2 = new SortedList<string, int>();
sortedList2.Add("one", 1);
sortedList2.Add("two", 2.0);

When you attempt to compile the above code, you end up with the error “Argument 2: cannot convert from ‘double’ to ‘int’.” I can change the second generic to a floating point and solve the problem, of course, but 2.0 is not an int, so it fails. In the non-generic..

SortedList sortedList = new SortedList();
sortedList.Add("one", 1);
sortedList.Add("two", 2.0);

… everything just works since the int and double are compatible. With the sorted list, the following is perfectly valid.

SortedList sortedList = new SortedList();
sortedList.Add("one", 1);
sortedList.Add("two", "x");

This is definitely a boxing exercise, as well, as the 1 is boxed as an object, as is the number 2. I cannot make the same code work with SortedList<string, int>.

To the Data Layer

When we think of the data layer, we often think of the idea of a repository and will create a repository for each type we have. In a typical eComm type application, we might have a CartRepository, OrderRepository, CustomerRepository, etc. We might think of these like the following code snippet:

public class Order {}
public class Customer {}
public class ShoppingCart {}
    
public class OrderRepository
{
    public List<Order> GetAll()
    {
    }
    public Order GetById(int id)
    {
    }
    public void Save(Order order)
    {
    }
    public void Remove(Order order)
    {
    }
}

public class CustomerRepository
{
    public List<Customer> GetAll()
    {
    }
    public Customer GetById(int id)
    {
    }
    public void Save(Customer customer)
    {
    }
    public void Remove(Customer customer)
    {
    }
}

public class ShoppingCartRepository
{
    public List<ShoppingCart> GetAll()
    {
    }
    public ShoppingCart GetById(int id)
    {
    }
    public void Save(ShoppingCart shoppingCart)
    {
    }
    public void Remove(ShoppingCart shoppingCart)
    {
    }
}

There is a lot of repeat and it forces us to create individual interfaces for testing (you do use unit testing, right?). Here are the interfaces:

public interface IOrderRepository
{
    List<Order> GetAll();
    OrderGetById(int id);
    voidSave(Orderorder);
    voidRemove(Orderorder);
}
public interfaceICustomerRepository
{
    List<Customer> GetAll();
    CustomerGetById(int id);
    voidSave(Customercustomer);
    voidRemove(Customercustomer);
}
public interfaceIShoppingCartRepository
{
    List<ShoppingCart> GetAll();
    ShoppingCart GetById(int id);
    voidSave(ShoppingCart shoppingCart);
    voidRemove(ShoppingCart shoppingCart);
}

With generics, however, we can put all of these in a single interface:

public interface IRepository<T>
    where T : class
{
    List<T> GetAll();
    T GetById(int id);
    void Save(T obj);
    void Remove(T obj);
}

Sweet! But what if one or more of the tables use Guids for the primary key (id)? Easy again:

public interface IRepository<T, U>
    where T : class 
    where U : struct
{
    List<T> GetAll();
    T GetById(U id);
    void Save(T obj);
    void Remove(T obj);
}

Now we are cooking with gas. Here is an implementation with a Guid as the primary key:

public class OrderRepository : IRepository<Order, Guid>
{
    public List<Order> GetAll()
    {
    }

    public Order GetById(Guid id)
    {
    }

    public void Save(Order obj)
    {
    }

    public void Remove(Order obj)
    {
    }
}

This is a bit dangerous, however, as I might need a lookup for customer on their customer id, which is not the primary key. Changing the generic interface does not work in this instance. So, we end up with this:

public interface IRepository<T, U>
    where T : class 
    where U : struct
{
    List<T> GetAll();
    T GetById(U id);
    void Save(T obj);
    void Remove(T obj);
}

public interface ICustomerRepository : IRepository<Customer, Guid>
{
    Customer GetAllByCustomerId(string lastName);
}

public class CustomerRepository : ICustomerRepository
{
    public Customer GetAllByCustomerId(string lastName)
    {
    }

    public List<Customer> GetAll()
    {
    }

    public Customer GetById(Guid id)
    {
    }

    public void Save(Customer obj)
    {
    }

    public void Remove(Customer obj)
    {
    }
}

This is very testable goodness, as I can test at any interface and be sure the code is working correctly. And, with proper tests, I have a safety net for refactoring the code further. If you want to refactor to the nth, you can even remove the generic repository bits from the CustomerRepository to a generic repository class. I cover this before (click this link), so I am not going to hit it here. Have fun coding!

Peace and Grace,
Greg

Twitter: @gbworld

The Climb

I have always loved the song the Climb, which was made famous by Miley Cyrus. Today, I saw a post on FaceBook that cemented my view of the song. It sounds a lot like the battle our children go through when they are diagnosed with cancer. This picture says a thousand words to me:

Here is the entire video, if you want to watch the song:

Miley singing to young cancer patient

I am not sure who the little girl in the video is. The video was shot through a cell phone, or at least that is how it appears. It is quite obvious the little girl is going through some sort of medical treatment. The bald head and NG tube give it away. To me, it is fairly obvious the medical condition is some form of cancer. The bald head and NG tube give it away. Bald due to the cancer, NG tube due to the fact her throat is raw from the mucositis from her chemo treatments and the fact nearly everything solid causes a vomiting reflex.

These are not pretty words, but cancer is not pretty in children. It rips them apart and leaves them with lifelong effects. The treatment protocols, overall, are ancient in the cancer world, some dating back to the 60s. Sure there have been tweaks, but unlike adult cancer patients, who often have less damaging options, the children generally only have the options chemo, radiation and surgery.

My daughter Miranda was diagnosed on September 6, 2007 at the age of 3 with Ewing’s Sarcoma. Ewing’s is a cancer of the bones that affects about 250 people a year, primarily male children in their pre-teens and early teens. Miranda’s was an Askin’s tumor, which is a Ewing’s tumor of the soft tissue. Only 10% of the cases of Ewing’s are soft tissue. As only a handful of Ewing’s patients are under the age of five, and few in soft tissue, she was a very rare case. And today she lives. Unfortunately, so many we have met are not here with us today. Statistically speaking, this small child has an overall 80% chance of survival. If she has certain forms of tumors, her prognosis is worse. And, if her cancer is metastatic, especially to the lungs, or a diffuse brain tumor, she could well be gone today. That is the reality of this world.

In September, my wife and 45 other women are shaving their heads for these little heroes. The event will take place in California in the Los Angeles area. Then they will appear on national television on Friday and work on getting on other television shows. The main goal is to raise awareness for a disease that is largely swept into the dark corners.

Peace and Grace,
Greg

Twitter: @gbworld