Skip to content
Hagicode Docs
Blog

Engineering

1 post with the tag “Engineering”

Best Practices for Building a Modern Build System with C# and Nuke

Say Goodbye to Script Hell: Why We Chose C# for a Modern Build System

Section titled “Say Goodbye to Script Hell: Why We Chose C# for a Modern Build System”

A look at how the HagiCode project uses Nuke to build a type-safe, cross-platform, and highly extensible automated build workflow, fully addressing the maintenance pain points of traditional build scripts.

Background

Section titled “Background”

Throughout the long journey of software development, the word “build” tends to inspire both love and frustration. We love it because with a single click, code becomes a product, which is one of the most rewarding moments in programming. We hate it because maintaining that pile of messy build scripts can feel like a nightmare.

In many projects, we are used to writing scripts in Python or using XML configuration files (just imagine the fear of being ruled by <property> tags). But as project complexity grows, especially in projects like HagiCode that involve frontend and backend work, multiple platforms, and multiple languages, traditional build approaches start to show their limits. Scattered script logic, no type checking, weak IDE support… these issues become small traps that repeatedly trip up the development team.

To solve these pain points, in the HagiCode project we decided to introduce Nuke - a modern build system based on C#. It is more than just a tool; it is a new way of thinking about build workflows. Today, let us talk about why we chose it and how it has made our development experience take off.

About HagiCode

Section titled “About HagiCode”

Hey, let us introduce what we are building

We are developing HagiCode - an AI-powered intelligent coding assistant that makes development smarter, more convenient, and more enjoyable.

Smarter - AI assistance throughout the entire process, from idea to code, multiplying development efficiency. Convenient - Multi-threaded concurrent operations make full use of resources and keep the development workflow smooth. Enjoyable - Gamification mechanisms and an achievement system make coding less tedious and far more rewarding.

The project is evolving quickly. If you are interested in technical writing, knowledge management, or AI-assisted development, feel free to check us out on GitHub~

Core Analysis: Why Nuke?

Section titled “Core Analysis: Why Nuke?”

You might be wondering: “There are so many build systems, like Make, Gradle, or even plain Shell scripts. Why go out of the way to use one built on C#?”

That is actually a great question. Nuke’s core appeal is that it brings the programming language features we know best into the world of build scripts.

1. Modularizing the Build Workflow: The Art of Targets

Section titled “1. Modularizing the Build Workflow: The Art of Targets”

Nuke has a very clear design philosophy: everything is a target.

In traditional scripts, we may end up with hundreds of lines of sequential code and tangled logic. In Nuke, we break the build workflow into independent Targets. Each target is responsible for just one thing, for example:

  • Clean: clean the output directory
  • Restore: restore dependency packages
  • Compile: compile the code
  • Test: run unit tests

This design aligns well with the single responsibility principle. Like building with blocks, we can combine these targets however we want. More importantly, Nuke lets us define dependencies between targets. For example, if you want Test, the system will automatically check whether Compile has already run; if you want Compile, then Restore naturally has to come first.

This dependency graph not only makes the logic clearer, but also greatly improves execution efficiency, because Nuke automatically analyzes the optimal execution path.

2. Type Safety: Saying Goodbye to the Nightmare of Typos

Section titled “2. Type Safety: Saying Goodbye to the Nightmare of Typos”

Anyone who has written build scripts in Python has probably experienced this embarrassment: the script runs for five minutes and then fails because Confi.guration was misspelled, or because a string was passed to a parameter that was supposed to be a number.

The biggest advantage of writing build scripts in C# is type safety. That means:

  • Compile-time checks: while you are typing, the IDE tells you what is wrong instead of waiting until runtime to reveal the issue.
  • Safe refactoring: if you want to rename a variable or method, the IDE can handle it with one refactor action instead of a nervous global search-and-replace.
  • Intelligent completion: powerful IntelliSense completes the code for you, so you do not need to dig through documentation to remember obscure APIs.

3. Cross-Platform: A Unified Build Experience

Section titled “3. Cross-Platform: A Unified Build Experience”

In the past, you might write .bat files on Windows and .sh files on Linux, then add a Python script just to bridge the two. Now, wherever .NET Core (now .NET 5+) can run, Nuke can run too.

This means that whether team members use Windows, Linux, or macOS, and whether they prefer Visual Studio, VS Code, or Rider, everyone executes the same logic. That greatly reduces the environment-specific problems behind the classic “it works on my machine” scenario.

4. Parameter and Configuration Management

Section titled “4. Parameter and Configuration Management”

Nuke provides a very elegant parameter parsing mechanism. You do not need to manually parse string[] args. You only need to define a property and add the [Parameter] attribute, and Nuke will automatically map command-line arguments and configuration files for you.

For example, we can easily define the build configuration:

[Parameter("Configuration to build - Default is 'Debug'")]
readonly Configuration BuildConfiguration = IsLocalBuild ? Configuration.Debug : Configuration.Release;


Target Compile => _ => _
    .DependsOn(Restore)
    .Executes(() =>
    {
        // Use BuildConfiguration here; it is type-safe
        DotNetBuild(s => s
            .SetConfiguration(BuildConfiguration)
            .SetProjectFile(SolutionFile));
    });

This style is both intuitive and less error-prone.

Practical Guide: How to Apply It in a Project

Section titled “Practical Guide: How to Apply It in a Project”

Talking is easy; implementation is what matters. Let us take a look at how we put this approach into practice in the HagiCode project.

1. Plan the Project Structure

Section titled “1. Plan the Project Structure”

We did not want build scripts cluttering the project root, and we also did not want a directory structure so deep that it feels like certain Java projects. So we placed all Nuke-related build files in the nukeBuild/ directory.

The benefits are straightforward:

  • the project root stays clean;
  • the build logic remains cohesive and easy to manage;
  • when new team members join, they can immediately see, “oh, this is where the build logic lives.”

2. Design a Clear Target Dependency Chain

Section titled “2. Design a Clear Target Dependency Chain”

When designing targets, we followed one principle: atomic tasks + dependency flow.

Each target should be small enough to do exactly one thing. For example, Clean should only delete files; do not sneak packaging into it.

A recommended dependency flow looks roughly like this:

Clean -> Restore -> Compile -> Test -> Pack

Of course, this is not absolute. For example, if you only want to run tests and do not want to package, Nuke allows you to run nuke Test directly, and it will automatically take care of the required Restore and Compile steps.

3. Solid Error Handling and Logging

Section titled “3. Solid Error Handling and Logging”

What is the most frustrating thing about build scripts? Unclear error messages. For example, if a build fails and the log only says “Error: 1”, that is enough to drive anyone crazy.

In Nuke, because we can directly use C# exception handling, we can capture and report errors with much greater precision.

Target Publish => _ => _
    .DependsOn(Test)
    .Executes(() =>
    {
        try
        {
            // Try publishing to NuGet
            DotNetNuGetPush(s => s
                .SetTargetPath(ArtifactPath)
                .SetSource("https://api.nuget.org/v3/index.json")
                .SetApiKey(ApiKey));
        }
        catch (Exception ex)
        {
            Log.Error($"Publishing failed. Team, please check whether the key is correct: {ex.Message}");
            throw; // Ensure the build process exits with a non-zero code
        }
    });

4. Use Tests to Protect Quality

Section titled “4. Use Tests to Protect Quality”

A build script is still code, and code should be tested. Nuke allows us to write tests for the build workflow, ensuring that when we modify the build logic, we do not break the existing release process. This is especially important in continuous integration (CI) pipelines.

Conclusion

Section titled “Conclusion”

By introducing Nuke, HagiCode’s build process has become smoother than ever before. This is not just a tool replacement; it is an upgrade in engineering thinking.

What did we gain?

  • Maintainability: code as configuration, clear logic, and a faster onboarding path for new team members.
  • Stability: strong typing eliminates more than 90% of low-level mistakes.
  • Consistency: a unified cross-platform experience removes environment differences.

If writing build scripts used to feel like “feeling your way through the dark,” then using Nuke feels like “walking at night with the lights on.” If you are tired of maintaining hard-to-debug scripting languages, try bringing your build logic into the world of C# as well. You may discover that build systems can actually be this elegant.

References

Section titled “References”

Thank you for reading. If you found this article useful, please click the like button below 👍 so more people can discover it.

This content was created with AI-assisted collaboration, reviewed by me, and reflects my own views and position.