JD.MSBuild.Fluent

A strongly-typed, fluent DSL for authoring MSBuild packages in C#

Author MSBuild .props, .targets, and SDK assets using a strongly-typed fluent API in C#, then automatically generate 100% standard MSBuild XML during build. No more hand-editing XML - write refactorable, testable, type-safe C# code instead.

✨ Features

🎯 Strongly-typed fluent API - IntelliSense, refactoring, compile-time validation
🔄 Automatic build integration - Generate MSBuild assets during dotnet build, no CLI required
📦 Full NuGet layout support - build/, buildTransitive/, and Sdk/ folders
🔧 XML scaffolding - Convert existing XML to fluent code with jdmsbuild scaffold
✅ Production-tested - Validated against real-world MSBuild packages
📝 Deterministic output - Consistent XML generation for meaningful diffs

Quick Start

1. Install the package

<PackageReference Include="JD.MSBuild.Fluent" Version="*" />

2. Define your MSBuild assets in C#

using JD.MSBuild.Fluent;
using JD.MSBuild.Fluent.Fluent;

namespace MySdk;

public static class DefinitionFactory
{
  public static PackageDefinition Create() => Package.Define("MySdk")
    .Props(p => p
      .Property("MySdkEnabled", "true")
      .Property("MySdkVersion", "1.0.0"))
    .Targets(t => t
      .Target("MySdk_Hello", target => target
        .BeforeTargets("Build")
        .Condition("'$(MySdkEnabled)' == 'true'")
        .Message("Hello from MySdk v$(MySdkVersion)!", "High")))
    .Pack(o => { 
      o.BuildTransitive = true; 
      o.EmitSdk = true; 
    })
    .Build();
}

3. Build your project

MSBuild assets are automatically generated during build and packaged correctly:

✅ build/MySdk.props
✅ build/MySdk.targets
✅ buildTransitive/MySdk.props and .targets
✅ Sdk/MySdk/Sdk.props and Sdk.targets

No CLI required! Just build and pack:

dotnet build
dotnet pack

🎯 Why JD.MSBuild.Fluent?

Problem: Hand-editing MSBuild XML is painful

❌ No IntelliSense or type safety
❌ No refactoring support
❌ Hard to test and validate
❌ Copy-paste leads to duplication
❌ Difficult to review diffs

Solution: Write C# instead

✅ Strongly-typed API with full IntelliSense
✅ Refactoring support - rename, extract, move
✅ Unit testable - validate logic before publishing
✅ DRY principle - reuse patterns across targets
✅ Better diffs - meaningful C# changes instead of XML noise
✅ Automatic generation - integrated into build pipeline

📚 Documentation

Getting Started

Introduction - Project overview and core concepts
Getting Started Guide - Installation and your first package
Examples - Real-world usage examples

User Guides

Overview - Guide to all user documentation
Basic Concepts - Understanding the fluent API
MSBuild Integration - How build integration works
Migration from XML - Convert existing XML to fluent
Advanced Topics - Custom tasks, conditions, and more

Reference

API Reference - Complete API documentation
CLI Reference - Command-line tool documentation

🔄 Migrate from XML

Convert existing MSBuild XML files to fluent API:

# Install CLI tool
dotnet tool install -g JD.MSBuild.Fluent.Cli

# Scaffold from existing XML
jdmsbuild scaffold --xml MyPackage.targets --output DefinitionFactory.cs --package-id MyCompany.MyPackage

See the Migration Guide for complete details.

🧪 Samples

Minimal SDK Package - Complete end-to-end example
Integration tests validate against JD.Efcpt.Build (real-world production package)

🏗️ Architecture Overview

JD.MSBuild.Fluent has a clean, layered architecture:

┌─────────────────────────────────────┐
│     Fluent API (Builders)           │  ← You work here
│  Package.Define(...).Props().Build()│
├─────────────────────────────────────┤
│   Intermediate Representation (IR)  │  ← Composable data structures
│    MsBuildProject, MsBuildTarget    │
├─────────────────────────────────────┤
│         XML Renderer                │  ← Deterministic serialization
│     MsBuildXmlRenderer              │
├─────────────────────────────────────┤
│      Package Emitter                │  ← NuGet folder layout
│   build/, buildTransitive/, Sdk/    │
└─────────────────────────────────────┘

Layers Explained

Fluent API: High-level builders for natural C# authoring
IR Layer: Immutable data structures representing MSBuild constructs
Renderer: Converts IR to canonical MSBuild XML with deterministic ordering
Emitter: Organizes rendered XML into NuGet package folder structure

🤝 Contributing

Contributions welcome! See our GitHub repository to get started.

📄 License

MIT License

JD.Efcpt.Build - EF Core Power Tools build integration
JD.MSBuild.Containers - Docker container build integration