OdeToCode IC Logo

.NET Core Opinion #1 - Structuring a Repository

Tuesday, August 28, 2018

There are numerous benefits to the open source nature of .NET Core. One specific benefit is the ability to look at how teams organize folders, projects, and files. You’ll see common conventions in the layout across the official.NET Core and ASP.NET Core repositories.

Here’s a typical layout:

|-- src/
|-- test/
|-- <solution>.sln 

Applying conventions across multiple repositories makes it easier for developers to move between repositories. The first three conventions I look for in project I work on are:

  1. A src folder, where all projects will live in sub-folders.
  2. A test folder, where all unit test projects will live in sub-folders
  3. A .sln file in the root of the repository (for Visual Studio environments)

Having a VS solution file in the root makes it easy for VS developers to clone a repo and open the file to get started. I'll also point out that these repository layout conventions existed in other ecosystems long before .NET Core came along.

In upcoming posts I’ll share some additional folders I like to see in every repository.

Gravatar Wayne Blackmon Tuesday, August 28, 2018
Can I assume that this is a Github repository?
Gravatar scott Tuesday, August 28, 2018
I'd only assume a Git repository - the repository could live anywhere (GitHub, local. TFS, etc). There's really nothing about the directory layout that would be specific to Git, either.
Dominik Tuesday, August 28, 2018
I'm not so fond of separating src and test, I like to have the tests close to the production code. It is often a good idea to read the tests in order to understand production code in more depth.
Gravatar Dominick Wednesday, August 29, 2018
We modified this slightly - in our newer repos, src only contains the ONE project that will be the build artifact of this repo (nuget or published app). We might have other folders like host or lib - for dependencies or test hosts. This way you can re-use the exact same build script (cake in our case) for every repo.
Gravatar John Wednesday, August 29, 2018
Do you prefer a single mono-repository for multiple projects\services or a separate repository for each service?
Gravatar scott Wednesday, August 29, 2018
@Dom - nice. @John - I prefer separate, but I can see the arguments for all sides.
Gravatar Bryan Wednesday, August 29, 2018
I like seeing a samples directory too for libraries, makes it easy see how to use the code correctly.
Gravatar Sean Wright Wednesday, August 29, 2018
Thanks for sharing! I always appreciate your best practices advice. I love how the javascript community keeps their tests directly next to their source code and often named the same but with a .spec suffix. It's great finding the things that change together by co-locating. I wish there was a way through build tooling for .NET to not have to separate your test code into another part of the file system where it's easier to not think about things like keeping tests up to date, testing while developing or TDD. It puts me more in a mindset of "I'm either testing or coding - not both at the same time." If the tooling could understand that *.spec.cs was not to be deployed and would create a App.Test.dll whereas regular *.cs files would create App.dll the whole "Where do I put test files" discussion would radically change.
Gravatar Stephen Brouillard Thursday, August 30, 2018
Hi Scott, Great stuff. I always enjoy your perspective on things. I generally agree with your recommendation and am looking forward to the follow-up on this. I have one issue that I struggle a bit to reconcile when working in the Visual Studio Environment. Some repos legitimately get large enough that solution level folders make sense for a little organization. Of course, solution folders are virtual and don't map 1-1 with file system folders. Do you have any thoughts about handling that process-wise? When I'm in Visual Studio, I'd rather use that interface to create the things I need rather than having to jump out to the command line. Maybe I'm just being a little OCD or missing a simple solution, so after reading your post, I thought it was worth asking the question.
Gravatar scott Friday, August 31, 2018
@Sean: I agree - would love to keep test files in the same folder. That's what I loved about features folders with JS / TypeScript. @Stephen: topic for an upcoming post!
Gravatar Stephen Brouillard Friday, August 31, 2018
@Scott - Looking forward to that post!
Comments are closed.