C# project layout: dependency management

The implementation of a project layout is a boring and fastidious process. Contrary to Java which, with Maven, proposes a “standardized” layout, there is no such thing for .NET. In the previous post, we spoke of solution and projects division (French), in this one we will speak of dependency management.

Usage of third-party libraries is essential in a project development if one do not want to reinvent the wheel over and over. But how to handle these libraries? Where to put these dependencies in a C# project structure? How to reference them?

In C# one can make a reference to the following types of components:

• .NET Framework assemblies (<code>System</code>, <code>System.Core</code> …)
• Class libraries of projects in the same solution
• Other assemblies
• COM components
• XML Web services

We will only speak of reference to other projects and third-party libraries; references to .NET Framework is fairly straightforward and references to COM and web services are out of scope.

Reference to other projects

In a multi-project solution, you often have to reference projects one with another. This could be done using file references or project-to-project references. File references are direct references to assemblies; Project-to-project references are references to projects that contain assemblies.

You should always use project-to-project references to reference projects. It creates a dependency between the projects in the build system. Therefore, the dependent project will be built if it has changed since the last time the referencing project was built. Whereas a file reference does not create a build dependency, so it is possible to build the referencing project without building the dependent project and the reference can become obsolete. (The project can reference a previously built version of the project)

Third-party libraries

For dependencies with third-party libraries file references are the only way to go. Assemblies could be referenced from the GAC (Global Assembly Cache) or directly from the disk with using an absolute or a relative path.

We strongly disadvise to reference assemblies from the GAC because we think that a project should be easily buildable as soon as it is fetched from the source control repository. If dependency comes from the GAC, developers must put the missing assembly in it before they can build the project. The GAC was designed strictly for run-time use and never should have been included in the reference search path.

Instead, we recommend putting all the third-party libraries in a source-controlled folder in the root folder of your solution and using a relative path for the reference (e.g: <Hintpath>../lib/nunit.dll</Hintpath> in your csproj file). That way you will avoid the common pitfalls: the same version of a library will be used across projects and your solution will be self sufficient. Of course, this is a general advice that could be tweaked to meet your project needs. (use a different library folder by project with a common one for common libraries, flatten assembly files or use specific folders for each library with sub-folders for each version …)

NuGet on the Block

The Java world has Maven as a software project management that handles dependencies management (Apache Ivy do that too), Ruby has its gems but until a few months the .NET world had no real equivalent. Some solutions existed like Nu, NPanday (.NET integration for Maven), HornGet or OpenWrap but they were lacking traction.

Since October 2010, .NET has gotten its dependency manager tool: NuGet. It is a free and open source package manager which intents on simplifying the process of including third-party libraries into a .NET application. NuGet is not a Microsoft project, but an Outercurve/Codeplex Foundation project.  It has both Microsoft and non-Microsoft contributors, and is run as a true Open Source project that accepts contributions (that’s a first for Microsoft).

Prior to NuGet, when one wanted to include a third-party library in its application, Nunit for example, he would have to

• Search the NUnit project page.
• Look around the home page for a link to the download page.
• Choose a version to download (Platform? Version? )
• Install or unzip the downloaded package.
• Copy the relevant assemblies in the application lib folder (see above)
• Add the reference within Visual Studio
• Update web.config if it is a web application project.
• Deal with dependency dependencies if any… (Pain follows)

Thanks to NuGet, this process resumes to:

• Click on “References > Add Library Package Reference…” within Visual Studio 2010
• Search for NUnit, among more than 800 libraries
• Click on “Install”
• You’re done.

NuGet download the requested library, put it in the “packages” folder in the solution root and updates the project file (updates web.config too if the project is a web application). Although it lists the dependencies in its packages.config file it does not download automatically the missing one, it is thus recommended putting the packages folder under version control.

For the command-line aficionados, the process could be done using the PowerShell-based Package Manager Console and the Install-Package command.

NuGet is a young but promising project, it simplifies the dependency management process and we hope that it will gain  even more traction over the time.

Wrapping up

To sum up:

• Use project references for dependencies between projects of a solution
• Put your third-party dependencies in a source-controlled folder in the root of your solution
• Do not reference libraries from the GAC
• Use NuGet!