A single .NET Core project to rule them all - Luca Bolognese

A single .NET Core project to rule them all

Luca -

☕ 5 min. read


The code is here.

Thanks to Mike for re­view­ing this.

I have al­ways been mildly ir­ri­tated by how many .net pro­jects I need to cre­ate in my stan­dard work­flow.

Usually I start with an idea for a li­brary; I then want to test it with a sim­ple ex­e­cutable; write some XUnit tests for it and fi­nally bench­mark some key sce­nar­ios. So I end up with at least four pro­jects to man­age.

Sure, I can find ways to au­to­mat­i­cally gen­er­ate those pro­jects, but I have al­ways been weary of code­gen to solve com­plex­ity is­sues. It al­ways ends up com­ing back to bite you. For those of you as old as I am, think MFC

So what is my ideal world then? Well, let’s try this:

  1. One sin­gle pro­ject for the li­brary and re­lated ar­ti­facts (i.e. test, bench­marks, etc…).
  2. Distinguish the li­brary code from the test code from the bench­mark code by some con­ven­tion (i.e. name scheme).
  3. Generate each ar­ti­fact (i.e. li­brary, tests, bench­marks, ex­e­cutable) by pass­ing dif­fer­ent op­tions to dotnet build and dotnet run.
  4. Create a new pro­ject by us­ing the stan­dard dotnet new syn­tax.
  5. Have in­tel­lisense work­ing nor­mally in each file for my cho­sen ed­i­tor (VSCode).
  6. Work with dotnet watch so that one can au­to­mat­i­cally run tests when any­thing changes.


What fol­lows, de­spite work­ing fine, is not the stan­dard way .net tools are used. It is not in the golden path’. That is prob­lem­atic for pro­duc­tion us­age as:

  1. It might not work in your par­tic­u­lar con­fig­u­ra­tion.
  2. It might not work with other tools that rely on the pres­ence of mul­ti­ple pro­jects (i.e. code cov­er­age? …).
  3. It might work now in all sce­nar­ios, but get bro­ken in the fu­ture as you up­date to a new frame­work, sdk, ed­i­tor.
  4. It might ex­pose bugs in the tools, now or later, which aren’t go­ing to be fixed, as you are not us­ing the tools as in­tended.
  5. It might up­set your cowork­ers that are used to a more stan­dard setup.

I need to write a blog post about the con­cept of the golden path’ and the per­ils, mostly hid­den, of get­ting away from it. The sum­mary, it is a bad idea.

Having said all of that, for the dar­ing souls, here is one way to achieve most of the above. It also works out as a tu­to­r­ial on how the dif­fer­ent com­po­nents of the .NET Core build sys­tem in­ter­acts.

How to use it

Here are the steps:

  1. Type dotnet new -i Lucabol.SingleSourceProject.
  2. Create a di­rec­tory for your pro­ject and cd to it.
  3. Type dotnet new lsingleproject and op­tion­ally --standardVersion <netstandardXX> --appVersion <netcoreappXX>.
  4. Either mod­ify the Library.cs, Main.cs, Test.cs, Bench.cs files or cre­ate your own with this con­ven­tion:
    • Code for the ex­e­cutable goes in po­ten­tially mul­ti­ple files named XXXMain.cs (i.e. MyLibrary.Main.cs).
    • Code for the tests goes into files named XXXTest.cs (i.e. MyLibrary.Test.cs).
    • Code for the bench­marks goes into files named XXXBench.cs (i.e. MyLibrary.Bench.cs).
    • Any .cs file not fol­low­ing the above con­ven­tions is com­piled into the dll.
  5. Type:
    • dotnet build or dotnet build -c release to build debug or release ver­sion of your dll. This does­n’t in­clude any of the main, test or bench code.
    • dotnet build -c main or dotnet build -c main_release and the cor­re­spond­ing dotnet run -c .. build and run the exe.
    • dotnet build -c test, dotnet build -c test_release and dotnet test -c test build and run the tests.
    • dotnet build -c bench, dotnet run -c bench build and run the bench­mark.

How it all works

The var­i­ous steps above are im­ple­mented as fol­lows:

dotnet new -i ... in­stall a cus­tom tem­plate that I have cre­ated and pushed on NuGet.

The cus­tom tem­plate is com­posed of the fol­low­ing files:

Code files

There is one file for each kind of ar­ti­fact that the pro­ject can gen­er­ate: li­brary, pro­gram, tests and bench­mark. The files fol­low the name ter­mi­nat­ing con­ven­tions, as de­scribed above.

Project file

The pro­ject file is iden­ti­cal to any other pro­ject file gen­er­ated by dotnet new ex­cept that there is one ad­di­tional line ap­pended at the end:

<Import Project="Base.targets" />

This in­struct msbuild to in­clude the Base.targets file. That file has most of the mag­ick. I have sep­a­rated it out so that you can use it un­changed in your own pro­jects.


We start by re­mov­ing all the file from com­pi­la­tion ex­cept the ones that are used to build the li­brary.

<Compile Remove="**/*Bench.cs;**/*Test.cs;**/*Main.cs" />

We then con­di­tion­ally in­clude the cor­rect ones de­pend­ing on which con­fig­u­ra­tion is cho­sen. Please no­tice the last line, which in­struct dotnet watch to watch all the .cs files. By de­fault it just watches the ones in the debug con­fig­u­ra­tion.

<Compile Include="**/*Test.cs" Condition="'$(Configuration)'=='Test'"/>
<Compile Include="**/*Test.cs" Condition="'$(Configuration)'=='Test_Release'"/>
<Compile Include="**/*Bench.cs" Condition="'$(Configuration)'=='Bench'"/>
<Compile Include="**/*Main.cs" Condition="'$(Configuration)'=='Main'"/>
<Compile Include="**/*Main.cs" Condition="'$(Configuration)'=='Main_Release'"/>
<Watch Include="**\*.cs" />

Then we need to de­fine the ref­er­ences. Depending on what you are build­ing you need to in­clude ref­er­ences to the cor­rect NuGet pack­ages (i.e. if you are build­ing test you need the xunit pack­ages). This is done be­low:

  <ItemGroup  Condition="'$(Configuration)'=='Bench' OR '$(Configuration)'=='Debug'">
<PackageReference Include="BenchmarkDotNet" Version="0.11.3" />

<ItemGroup Condition="'$(Configuration)'=='Test' OR '$(Configuration)'=='Test_Release' OR '$(Configuration)'=='Debug'">
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.9.0" />
<PackageReference Include="xunit" Version="2.4.0" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.4.0" />

One thing to no­tice is that most ref­er­ences are also in­cluded in the debug con­fig­u­ra­tion. This is not a good thing, but it is the only way to get VSCode Intellisense to work for all the files in the so­lu­tion. Apparently, IntelliSense uses what­ever ref­er­ence are de­fined for the debug build in VsCode. So debug is spe­cial, if you wish …

But that’s not enough. When you cre­ate your own MsBuild con­fig­u­ra­tions, you also have to repli­cate the prop­er­ties and con­stants that are set in the debug and release con­fig­u­ra­tions. You would like a way to in­herit them, but I don’t think it is pos­si­ble.

It is par­tic­u­larly im­por­tant to set the TargetFramework prop­erty, as it needs to be set to netcoreappXXX for the main, test and bench­mark con­fig­u­ra­tions. I give an ex­am­ple of the Test and Test_release con­fig­u­ra­tions be­low. The rest is sim­i­lar:

  <PropertyGroup Condition="'$(Configuration)'=='Test'">

<PropertyGroup Condition="'$(Configuration)'=='Test_Release'">

The .template.config/template.json file

This is nec­es­sary to cre­ate a dotnet new cus­tom tem­plate. The only thing to no­tice is the two pa­ra­me­ters standardVersion and appVersion that gives the user a way to in­di­cate which ver­sion of the .NET Standard to use for the li­brary and which ver­sion of the ap­pli­ca­tion frame­work to use for Main, Test and Bench.

"$schema": "http://json.schemastore.org/template",
"author": "Luca Bolognese",
"classifications": [ "Classlib", "Console", "XUnit" ],
"identity": "Lucabol.SingleSourceProject",
"name": "One single Project",
"description": "One single Project for DLL, XUnit, Benchmark & Main, using configurations to decide what to compile",
"shortName": "oneproject",
"tags": {
"language": "C#",
"type": "project"
"preferNameDirectory": true,
"sourceName": "SingleSourceProject",
"standardVersion": {
"type": "parameter",
"defaultValue": "netstandard2.0",
"appVersion": {
"type": "parameter",
"defaultValue": "netcoreapp2.1",


Now that you know how it all works, you can make an in­formed de­ci­sion if to use it or not. As for me …

0 Webmentions

These are webmentions via the IndieWeb and webmention.io.