Faithlife.Build is a build automation system using C# build scripts.


This library allows developers to use C# to write build scripts. It is similar to Cake and NUKE, but simpler, providing a thin wrapper over some of the libraries acknowledged below.

Most importantly, since the build script is a full-fledged .NET app with access to any compatible NuGet package, you can do just about anything, in a language and framework you already know well.


To use this library for your automated build, create a .NET Console App project in tools/Build that references the latest Faithlife.Build NuGet package. Optionally add the project to your Visual Studio solution file. See Build.csproj for an example project.

The Main method of the console app should call BuildRunner.Execute or BuildRunner.ExecuteAsync with the args and a delegate that defines the build targets and any desired command-line options by calling methods on the provided BuildApp.

using Faithlife.Build;
using static Faithlife.Build.DotNetRunner;

internal static class Build
    public static int Main(string[] args) => BuildRunner.Execute(args, build =>
            .Describe("Builds the solution")
            .Does(() => RunDotNet("build", "-c", "Release", "--verbosity", "normal"));

Perform the build by running the Build project. This can be done directly via dotnet run, e.g. dotnet run --project tools/Build -- test, but builds are more easily run from a simple bootstrapper, usually named build.ps1, build.cmd, and/or

Specify the desired targets on the command line, e.g. ./build package. Use --help to list the available build targets and command-line options. These command-line arguments are always supported:

  • -n or --dry-run : Don’t execute target actions.
  • -s or --skip-dependencies : Don’t run any target dependencies.
  • --skip <targets> : Skip the comma-delimited target dependencies.
  • --no-color : Disable color output.
  • --show-tree : Show the dependency tree.
  • -? or -h or --help : Show build help.

Consult the full reference documentation for additional details.

Create .NET Targets

To create standard targets for a .NET build, call DotNetBuild.AddDotNetTargets with custom settings as needed. See Build.cs for an example.

The supported targets include:

The supported command-line options include:

  • -c <name> or --configuration <name> : The configuration to build (default Release).
  • -p <name> or --platform <name> : The solution platform to build.
  • -v <level> or --verbosity <level> : The build verbosity (q[uiet], m[inimal], n[ormal], d[etailed]).
  • --version-suffix <suffix> : Generates a prerelease NuGet package.
  • --nuget-output <path> : Directory for the generated NuGet package (default release).
  • --trigger <name> : The git branch or tag that triggered the build.
  • --build-number <number> : The automated build number.
  • --no-test : Skip the unit tests.

The supported DotNetBuildSettings include:

  • SolutionName : The name of the solution file; defaults to the only solution in the directory.
  • SolutionPlatform : The default solution platform to build.
  • Verbosity : The default build verbosity.
  • NuGetApiKey : The NuGet API key with which to push packages.
  • NuGetSource : The NuGet source to which to push packages, if not the standard source.
  • DocsSettings : Used to generate Markdown documentation from XML comments.
  • MSBuildSettings : Set to use MSBuild instead of dotnet to build the solution.

For details on exactly what each target does and how the settings and command-line options affect the build, read the source code.


Special thanks to the libraries and tools used by Faithlife.Build:

Also thanks to Paul Knopf for this article, which inspired us to think beyond Cake.