DEV Community: DotMakeBuild

Docfx-Plus: A template and a tool to enhance DocFx and migrate from SHFB (Sandcastle)

DotMakeBuild — Sat, 13 Dec 2025 11:07:17 +0000

We used SHFB for many years mainly because of its excellent <code> block and NamespaceDoc support and it had been very stable but imho its theme and architecture is a bit outdated. DocFx is great in many ways but it misses some important features that we got used to with SHFB. So I created a new project docfx-plus to enhance DocFx. My aim was to update existing project docs that depend on some SHFB features, without changes to xml comments, to DocFx. Check it out and let me know what you think.

Live Demo - Sample API docs result for our other project DotMake Command-Line.

Just released DocFx-Plus v2.0.0 which now adds new convert command to convert/migrate your existing SHFB (Sandcastle Help File Builder) projects completely to docfx projects:

Project file (.shfbproj) will be converted to docfx.json
Content Layout files (.content) will be converted to toc.yml
MAML Topic files (.aml) will be converted to Markdown files (.md)
Namespace summaries will be converted to overwrite files (.md)
Other content files like images will be copied
By default content subfolder will be rebased to docs and icons, media subfolders will be rebased to images to match docfx conventions.

Sample Outputs

These documentation projects are converted from SHFB to Docfx-Plus:

Screenshots

Generating SVG sprites (spritesheets) for ASP.NET apps

DotMakeBuild — Thu, 23 Oct 2025 05:24:22 +0000

If you’ve ever wrangled dozens of SVG icons into a sprite sheet, you know how tedious and error-prone it can be. That’s why I built svg-sprite — a fast, standards-compliant CLI tool and library for generating <symbol>-based SVG sprites with zero fuss.

Whether you're building a design system, optimizing web assets, or just want clean, reusable icons, svg-sprite gives you the control and clarity you need.

What It Does

Builds SVG sprites from individual files using <symbol> elements
Preserves critical attributes like viewBox, fill, stroke, and id
Sanitizes and minifies input for web-ready output
Generates an HTML preview page to visually test your sprite
Extracts symbols back into individual SVGs for reverse workflows

Example Usage

svg-sprite build icons/*.svg -o sprite.svg --html-preview

This command:
• Combines all SVGs in icons/ into a single sprite.svg
• Generates sprite-preview.html — a responsive grid of icons for QA

CLI + API: Use It Your Way

Install the CLI globally:

dotnet tool install --global svg-sprite

Use the library in your .NET project:

dotnet add package DotMake.SvgSprite

//Build an SVG sprite file from input SVG files

var svgDocument = new SvgDocument();
var svgSpriteBuilder = new SvgSpriteBuilder(svgDocument);

foreach (var file in Directory.EnumerateFiles(@"inputs\", "*.svg"))
{
    var svgDocumentToAdd = new SvgDocument(file);
    var symbolId = Path.GetFileNameWithoutExtension(file);

    svgSpriteBuilder.AddSymbol(svgDocumentToAdd, symbolId);
}

svgDocument.Save(@"sprite.svg");

Why It’s Different

Built with developer ergonomics in mind
Handles edge cases like missing IDs, duplicate names, and attribute conflicts
Designed for CI/CD pipelines, design systems, and static site generators
Fully open-source: GitHub repo

Using generated SVG sprites

Once you have an SVG sprite, for example sprite.svg like this:

<svg xmlns="http://www.w3.org/2000/svg">

  <symbol viewBox="0 0 640 640" id="address-book">
    <path fill="currentColor" d="M448 112C456.8 112 464 119.2 464 128L464 512C464 520.8 456.8 528 448 528L160 528C151.2 528 144 520.8 144 512L144 128C144 119.2 151.2 112 160 112L448 112zM160 64C124.7 64 96 92.7 96 128L96 512C96 547.3 124.7 576 160 576L448 576C483.3 576 512 547.3 512 512L512 128C512 92.7 483.3 64 448 64L160 64zM304 312C334.9 312 360 286.9 360 256C360 225.1 334.9 200 304 200C273.1 200 248 225.1 248 256C248 286.9 273.1 312 304 312zM272 352C227.8 352 192 387.8 192 432C192 440.8 199.2 448 208 448L400 448C408.8 448 416 440.8 416 432C416 387.8 380.2 352 336 352L272 352zM576 144C576 135.2 568.8 128 560 128C551.2 128 544 135.2 544 144L544 208C544 216.8 551.2 224 560 224C568.8 224 576 216.8 576 208L576 144zM560 256C551.2 256 544 263.2 544 272L544 336C544 344.8 551.2 352 560 352C568.8 352 576 344.8 576 336L576 272C576 263.2 568.8 256 560 256zM576 400C576 391.2 568.8 384 560 384C551.2 384 544 391.2 544 400L544 464C544 472.8 551.2 480 560 480C568.8 480 576 472.8 576 464L576 400z" />
  </symbol>

  <symbol viewBox="0 0 640 640" id="alarm-clock">
    <path fill="currentColor" d="M466.6 114.2C461.2 115.9 455.3 116 450.4 113.3C444.6 110.1 438.6 107.1 432.6 104.4C422.2 99.7 418.9 86.1 428.5 79.8C443.5 69.9 461.5 64.1 480.8 64.1C533.4 64.1 576 106.7 576 159.3C576 172.5 573.3 185.1 568.4 196.6C563.9 207.1 550 206.4 543.5 197C539.7 191.5 535.7 186.2 531.5 181C528 176.6 527 170.8 527.7 165.2C527.9 163.3 528.1 161.3 528.1 159.3C528.1 133.2 506.9 112.1 480.9 112.1C476 112.1 471.2 112.9 466.7 114.3zM96.5 196.9C90 206.3 76 207 71.6 196.5C66.7 185 64 172.4 64 159.2C64 106.6 106.6 64 159.2 64C178.5 64 196.5 69.8 211.5 79.7C221.1 86 217.8 99.6 207.4 104.3C201.3 107.1 195.4 110 189.6 113.2C184.7 115.9 178.7 115.8 173.4 114.1C168.9 112.7 164.2 111.9 159.2 111.9C133.1 111.9 112 133.1 112 159.1C112 161.1 112.1 163.1 112.4 165C113.1 170.6 112.1 176.4 108.6 180.8C104.4 186 100.4 191.3 96.6 196.8zM496 352C496 254.8 417.2 176 320 176C222.8 176 144 254.8 144 352C144 449.2 222.8 528 320 528C417.2 528 496 449.2 496 352zM460.5 526.5C422.1 557.4 373.2 576 320 576C266.8 576 217.9 557.4 179.5 526.5L137 569C127.6 578.4 112.4 578.4 103.1 569C93.8 559.6 93.7 544.4 103.1 535.1L145.6 492.6C114.6 454.1 96 405.2 96 352C96 228.3 196.3 128 320 128C443.7 128 544 228.3 544 352C544 405.2 525.4 454.1 494.5 492.5L537 535C546.4 544.4 546.4 559.6 537 568.9C527.6 578.2 512.4 578.3 503.1 568.9L460.6 526.4zM344 248L344 342.1L385 383.1C394.4 392.5 394.4 407.7 385 417C375.6 426.3 360.4 426.4 351.1 417L303.1 369C298.6 364.5 296.1 358.4 296.1 352L296.1 248C296.1 234.7 306.8 224 320.1 224C333.4 224 344.1 234.7 344.1 248z" />
  </symbol>

</svg>

You can use symbols from this sprite in your HTML pages like this:

<svg>
  <use href="sprite.svg#address-book" />
</svg>

<svg style="width: 48px; height: 48px;">
  <use href="sprite.svg#alarm-clock" />
</svg>

Note that <use> tag does not work cross-origin, including local HTML files (when not viewed from a web server),
so in that case you should put/inline the SVG sprite into your HTML page and
then you should only include the URL fragment in href attribute:

<svg>
  <use href="#address-book" />
</svg>

<svg style="width: 48px; height: 48px;">
  <use href="#alarm-clock" />
</svg>

Note that for <use> tag, the old attribute xlink:href is deprecated and the attribute href is used since browser
versions released from 2016-2019.

Feedback Welcome

I built svg-sprite to solve real-world pain points in icon workflows. If you have ideas, edge cases, or feature requests, I’d love to hear them.

Additional info

Building a Command-Line (CLI) app using System.CommandLine library in C# and .NET

DotMakeBuild — Mon, 29 Jan 2024 13:42:27 +0000

System.CommandLine is a very good parser but you need a lot of boilerplate code to get going and the API is hard to discover.
This becomes complicated to newcomers and also you would have a lot of ugly code in your Program.cs to maintain.
What if you had an easy class-based layer combined with a good parser?

DotMake.CommandLine is a library which provides declarative syntax for
System.CommandLine
via attributes for easy, fast, strongly-typed (no reflection) usage. The library includes includes a source generator
which automagically converts your classes to CLI commands and properties to CLI options or CLI arguments.
Supports
trimming,
AOT compilation and
dependency injection!

Getting started

Install the library to your console app project with NuGet.

In your project directory, via dotnet cli:



dotnet add package DotMake.CommandLine

or in Visual Studio Package Manager Console:



PM> Install-Package DotMake.CommandLine

Prerequisites

.NET 6.0 and later project or .NET Standard 2.0 and later project (note that .NET Framework 4.7.2+ can reference netstandard2.0 libraries). If your target framework is below net5.0, you also need <LangVersion>9.0</LangVersion> tag (minimum) in your .csproj file.
Visual Studio 2022 v17.3+ or .NET SDK 6.0.407+ (our incremental source generator requires performance features added first in these versions).
Usually a console app project but you can also use a class library project which will be consumed later.

Usage

Delegate-based model

Create a CLI App with DotMake.Commandline in seconds!
In Program.cs, add this simple code:



Cli.Run(([CliArgument]string argument1, bool option1) =>
{
    Console.WriteLine($@"Value for {nameof(argument1)} parameter is '{argument1}'");
    Console.WriteLine($@"Value for {nameof(option1)} parameter is '{option1}'");
});

And that's it! You now have a fully working command-line app.

Summary

Pass a delegate (a parenthesized lambda expression or a method reference) which has parameters that represent your options and arguments, to Cli.Run.
A parameter is by default considered as a CLI option but you can;
- Mark a parameter with CliArgument attribute to make it a CLI argument and specify settings (see CliArgumentAttribute docs for more info).
- Mark a parameter with CliOption attribute to specify CLI option settings (see CliOptionAttribute docs for more info).
- Mark the delegate itself with CliCommand attribute to specify CLI command settings (see CliCommandAttribute docs for more info).
- Note that for being able to mark a parameter with an attribute in an anonymous lambda function, if your target framework is below net6.0, you also need <LangVersion>10.0</LangVersion> tag (minimum) in your .csproj file.
Set a default value for a parameter if you want it to be optional (not required to be specified on the command-line).
Your delegate can be async.
Your delegate can have a return type void or int and if it's async Task or Task<int>.

Class-based model

While delegate-based model above is useful for simple apps, for more complex apps, you can use the class-based model.
Create a simple class like this:



using System;
using DotMake.CommandLine;

[CliCommand(Description = "A root cli command")]
public class RootCliCommand
{
    [CliOption(Description = "Description for Option1")]
    public string Option1 { get; set; } = "DefaultForOption1";

    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; }

    public void Run()
    {
        Console.WriteLine($@"Handler for '{GetType().FullName}' is run:");
        Console.WriteLine($@"Value for {nameof(Option1)} property is '{Option1}'");
        Console.WriteLine($@"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine();
    }
}

In Program.cs, add this single line:



Cli.Run<RootCliCommand>(args);

And that's it! You now have a fully working command-line app. You just specify the name of your class which represents your root command to Cli.Run<> method and everything is wired.

args is the string array typically passed to a program. This is usually
the special variable args available in Program.cs (new style with top-level statements)
or the string array passed to the program's Main method (old style).
We also have method signatures which does not require args,
for example you can also call Cli.Run<RootCliCommand>() and in that case args will be retrieved automatically from the current process via Cli.GetArgs().

If you want to go async, just use this:



await Cli.RunAsync<RootCliCommand>(args);

To handle exceptions, you just use a try-catch block:



try
{
    Cli.Run<RootCliCommand>(args);
}
catch (Exception e)
{
    Console.WriteLine(@"Exception in main: {0}", e.Message);
}

System.CommandLine, by default overtakes your exceptions that are thrown in command handlers (even if you don't set an exception handler explicitly) but DotMake.CommandLine, by default allows the exceptions to pass through. However if you wish, you can easily use an exception handler by using configureBuilder delegate parameter like this:



Cli.Run<RootCliCommand>(args, builder => 
    builder.UseExceptionHandler((e, context) => Console.WriteLine(@"Exception in command handler: {0}", e.Message))
);

If you need to simply parse the command-line arguments without invocation, use this:



var rootCliCommand = Cli.Parse<RootCliCommand>(args);

If you need to examine the parse result, such as errors:



var rootCliCommand = Cli.Parse<RootCliCommand>(args, out var parseResult);
if (parseResult.Errors.Count > 0)
{

}

Summary

Mark the class with CliCommand attribute to make it a CLI command (see CliCommandAttribute docs for more info).
Mark a property with CliOption attribute to make it a CLI option (see CliOptionAttribute docs for more info).
Mark a property with CliArgument attribute to make it a CLI argument (see CliArgumentAttribute docs for more info).
Add a method with name Run or RunAsync to make it the handler for the CLI command. The method can have one of the following signatures:



   void Run()

```c#

int Run()

  - 
   ```c#


   async Task RunAsync()

```c#

async Task RunAsync()

  Optionally the method signature can have a System.CommandLine.Invocation.InvocationContext parameter in case you need to access it:

  - 
   ```c#


   Run(InvocationContext context)



   RunAsync(InvocationContext context)

The signatures which return int value, sets the ExitCode of the app.
If no handler method is provided, then by default it will show help for the command.
This can be also controlled manually by extension method ShowHelp in InvocationContext.
Other extension methods IsEmptyCommand and ShowValues are also useful.

Call Cli.Run<> orCli.RunAsync<> method with your class name to run your CLI app (see Cli docs for more info).

DEV Community: DotMakeBuild

Docfx-Plus: A template and a tool to enhance DocFx and migrate from SHFB (Sandcastle)

Sample Outputs

These documentation projects are converted from SHFB to Docfx-Plus:

Screenshots

Generating SVG sprites (spritesheets) for ASP.NET apps

What It Does

Example Usage

CLI + API: Use It Your Way

Why It’s Different

Using generated SVG sprites

Feedback Welcome

Additional info

Building a Command-Line (CLI) app using System.CommandLine library in C# and .NET

Getting started

Prerequisites

Usage

Delegate-based model

Summary

Class-based model

Summary

Additional documentation