CP.Nuke.BuildTools 2.0.16

CP.Nuke.BuildTools

A collection of extension methods that simplify common build, packaging and release tasks when using Nuke Build.

Add the NuGet package to your build project (the one containing Build.cs):

dotnet add build/_build.csproj package CP.Nuke.BuildTools

Then add:

using CP.BuildTools; // at top of Build.cs

Extension Overview

The following extension methods are available (defined in build/Extensions.cs):

NOTE: Methods that execute external processes (ProcessTasks.StartShell) or call GitHub API have side-effects and expect required tools (git, pwsh) and environment (GitHub PAT) to be available.

Usage Examples

Below are example targets you can integrate into your Build class.

1. Basic NuGet Source

Target Info => _ => _
    .Executes(() =>
    {
        Log.Information("NuGet V3: {Source}", this.PublicNuGetSource());
    });

2. Update Visual Studio & Workloads (CI environments)

Target SetupCI => _ => _
    .Executes(async () =>
    {
        await this.UpdateVisualStudio(); // Enterprise by default
        await this.InstallDotNetSdk("8.x.x", "9.x.x"); // install latest matching channels
        this.InstallAspNetCore("8.0");
        Solution.RestoreSolutionWorkloads();
    });

3. Packing Projects

Target Pack => _ => _
    .DependsOn(Compile)
    .Executes(() =>
    {
        var packable = Solution.GetPackableProjects();
        if (packable == null || packable.Count == 0)
        {
            Log.Warning("No packable projects found.");
            return;
        }
        DotNetPack(s => s
            .SetConfiguration(Configuration)
            .CombineWith(packable, (ps, p) => ps.SetProject(p)));
    });

4. Installing Specific SDK Channels

Target InstallSdks => _ => _
    .Executes(async () =>
    {
        // Patterns: Major.Minor.Patch can use 'x' placeholders.
        await this.InstallDotNetSdk("6.x.x", "7.x.x", "8.0.x", "9.0.100");
    });

5. GitHub Release Automation

Requires a GitHub PAT exported as an environment variable (e.g. GITHUB_TOKEN).

[Parameter][Secret] readonly string GitHubToken;
[GitRepository] readonly GitRepository Repository;

Target Release => _ => _
    .Requires(() => GitHubToken)
    .Executes(() =>
    {
        this.SetGithubCredentials(GitHubToken);

        // Create draft release
        var tag = $"v{NerdbankVersioning.NuGetPackageVersion}";
        var release = this.CreateRelease(Repository, tag, NerdbankVersioning.NuGetPackageVersion, null, isPrerelease: false);

        // Append commit based notes
        release = release.AppendReleaseNotes(Repository, maxCommits: 40);

        // Upload artifacts (assumes Pack target already produced nupkgs)
        var artifactsDir = RootDirectory / "output";
        release.UploadDirectory(artifactsDir);

        // Publish
        release.Publish(Repository);
    });

6. Downloading a Release Asset

Target FetchAsset => _ => _
    .Requires(() => GitHubToken)
    .Executes(() =>
    {
        this.SetGithubCredentials(GitHubToken);
        var bytes = this.GetAsset("owner", "repo", "mytool.zip", uiReleaseTag: null); // latest release
        var dest = RootDirectory / "temp" / "mytool.zip";
        this.SaveFile(dest, bytes);
        Log.Information("Saved asset to {Path}", dest);
    });

7. Using Commit Release Notes Separately

Target Notes => _ => _
    .Executes(() =>
    {
        var markdown = Repository.GenerateReleaseNotes(25);
        File.WriteAllText(RootDirectory / "RELEASE_NOTES.md", markdown);
    });

8. Clone External Repository (Shallow)

Target CloneExample => _ => _
    .Executes(() =>
    {
        var targetDir = RootDirectory / "external";
        targetDir.CreateDirectory();
        targetDir.Checkout("https://github.com/owner/repo.git");
    });

Error Handling & Notes

• InstallDotNetSdk throws if no matching stable versions are found.
• InstallAspNetCore throws if version < 6 or cannot parse.
• CreateRelease, Publish, AppendReleaseNotes require a valid authenticated Octokit client (set via SetGithubCredentials).
• Network dependent methods (GetFileFromUrlAsync, GitHub operations) should be wrapped with retry logic if used in unstable environments.

Suggested Target Ordering

A typical pipeline using these utilities:

1. SetupCI � ensure tooling & SDKs.
2. Restore (standard Nuke restore + workloads if needed).
3. Compile.
4. Pack.
5. Release (optional for main / tagged builds).

License

MIT � see LICENSE file.