FractalDataWorks.CodeBuilder.CSharp 0.6.0-rc.1

FractalDataWorks.CodeBuilder.CSharp

Concrete implementations of the code generation framework defined in FractalDataWorks.CodeBuilder.Abstractions. This package provides builders, parsers, and generators for C# code generation with Roslyn-based syntax analysis.

Overview

This package provides:

• C# Code Builders: Builders for classes, methods, properties, constructors, and fields
• Roslyn-Based Parsing: C# code parsing using Microsoft.CodeAnalysis
• Code Generation Engine: Code generation with builder integration
• Language Registry: Registry with C# support and extensibility for additional languages

The package targets netstandard2.0 for broad compatibility.

Key Implementations

Base Infrastructure

CodeBuilderBase

From CodeBuilderBase.cs:

Abstract base class providing common functionality for all concrete builders:

• StringBuilder Management: String building with Builder property
• Indentation Handling: Indent(), Outdent(), and configurable IndentString
• Line Management: AppendLine() and Append() methods with proper indentation
• Builder State: Clear() method for state reset

// From CodeBuilderBase.cs:24-29
public string IndentString { get; set; } = "    ";
public int IndentLevel { get; private set; }
public abstract string Build();

C# Language Builders

ClassBuilder

From Builders/ClassBuilder.cs:

Implementation of IClassBuilder supporting C# class features:

Supported Features:

• Namespace and Usings: File-scoped namespaces and organized using directives
• Class Modifiers: public, internal, abstract, sealed, static, partial
• Inheritance: Base classes and multiple interface implementation
• Generic Types: Type parameters with constraint support
• Members: Fields, properties, methods, constructors, nested classes
• Attributes: Class-level and member-specific attributes
• Documentation: XML documentation

Available Methods (from ClassBuilder.cs:36-170):

// Namespace and usings
IClassBuilder WithNamespace(string namespaceName);
IClassBuilder WithUsings(params string[] usings);

// Class declaration
IClassBuilder WithName(string className);
IClassBuilder WithAccessModifier(string accessModifier);
IClassBuilder AsStatic();
IClassBuilder AsAbstract();
IClassBuilder AsSealed();
IClassBuilder AsPartial();

// Inheritance
IClassBuilder WithBaseClass(string baseClass);
IClassBuilder WithInterfaces(params string[] interfaces);

// Generics
IClassBuilder WithGenericParameters(params string[] typeParameters);
IClassBuilder WithGenericConstraint(string typeParameter, params string[] constraints);

// Attributes and documentation
IClassBuilder WithAttribute(string attribute);
IClassBuilder WithXmlDoc(string summary);

// Members
IClassBuilder WithField(IFieldBuilder fieldBuilder);
IClassBuilder WithProperty(IPropertyBuilder propertyBuilder);
IClassBuilder WithMethod(IMethodBuilder methodBuilder);
IClassBuilder WithConstructor(IConstructorBuilder constructorBuilder);
IClassBuilder WithNestedClass(IClassBuilder nestedClassBuilder);

Example Usage:

var classBuilder = new ClassBuilder()
    .WithNamespace("MyProject.Domain")
    .WithUsings("System", "System.ComponentModel.DataAnnotations")
    .WithName("Customer")
    .WithAccessModifier("public")
    .AsSealed()
    .WithBaseClass("EntityBase")
    .WithInterfaces("IValidatableObject", "INotifyPropertyChanged")
    .WithGenericParameters("TKey")
    .WithGenericConstraint("TKey", "struct", "IComparable<TKey>")
    .WithAttribute("Table(\"Customers\")")
    .WithXmlDoc("Represents a customer entity with validation support");

var idProperty = new PropertyBuilder()
    .WithName("Id")
    .WithType("TKey")
    .AsReadOnly()
    .WithAttribute("Key")
    .WithXmlDoc("Gets the unique identifier for this customer");

classBuilder.WithProperty(idProperty);

string generatedCode = classBuilder.Build();

MethodBuilder

From Builders/MethodBuilder.cs:

Method generation supporting C# method patterns:

Supported Features:

• Method Types: Instance, static, abstract, virtual, override, new methods
• Async Support: Async methods with proper modifiers
• Generic Methods: Generic type parameters with constraint support
• Parameters: Required and optional parameters with default values
• Body Types: Block body, expression body, abstract (no body)
• Documentation: XML documentation with parameter and return descriptions

Available Methods (from MethodBuilder.cs:35-176):

IMethodBuilder WithName(string name);
IMethodBuilder WithReturnType(string returnType);
IMethodBuilder WithAccessModifier(string accessModifier);
IMethodBuilder AsStatic();
IMethodBuilder AsVirtual();
IMethodBuilder AsOverride();
IMethodBuilder AsAbstract();
IMethodBuilder As();  // Sets async modifier
IMethodBuilder AsNew();
IMethodBuilder WithParameter(string type, string name, string? defaultValue = null);
IMethodBuilder WithGenericParameters(params string[] typeParameters);
IMethodBuilder WithGenericConstraint(string typeParameter, params string[] constraints);
IMethodBuilder WithAttribute(string attribute);
IMethodBuilder WithBody(string body);
IMethodBuilder AddBodyLine(string line);
IMethodBuilder WithExpressionBody(string expression);
IMethodBuilder WithXmlDoc(string summary);
IMethodBuilder WithParamDoc(string parameterName, string description);
IMethodBuilder WithReturnDoc(string description);

Example Usage:

var methodBuilder = new MethodBuilder()
    .WithName("ProcessAsync")
    .WithReturnType("Task<ProcessResult<T>>")
    .WithGenericParameters("T")
    .WithGenericConstraint("T", "class", "IProcessable")
    .WithParameter("T", "item")
    .WithParameter("CancellationToken", "cancellationToken", "default")
    .As()  // Sets async modifier
    .WithAttribute("RequireAuthentication")
    .WithXmlDoc("Processes an item asynchronously with cancellation support")
    .WithParamDoc("item", "The item to process")
    .WithParamDoc("cancellationToken", "Token to cancel the operation")
    .WithReturnDoc("The result of the processing operation")
    .AddBodyLine("ArgumentNullException.ThrowIfNull(item);")
    .AddBodyLine("return await _processor.ProcessAsync(item, cancellationToken);");

string generatedCode = methodBuilder.Build();

Note: The As() method sets the async modifier. Consider renaming to AsAsync() for clarity.

PropertyBuilder

From Builders/PropertyBuilder.cs:

C# property generation with language feature support:

Supported Features:

• Property Types: Auto-properties, computed properties, properties with custom accessors
• Accessors: Get, set, init-only setters with individual access modifiers
• Property Bodies: Expression body properties and custom accessor implementations
• Modifiers: Static, virtual, override, abstract properties
• Initializers: Property initializers

Available Methods (from PropertyBuilder.cs:34-166):

IPropertyBuilder WithName(string name);
IPropertyBuilder WithType(string type);
IPropertyBuilder WithAccessModifier(string accessModifier);
IPropertyBuilder AsStatic();
IPropertyBuilder AsVirtual();
IPropertyBuilder AsOverride();
IPropertyBuilder AsAbstract();
IPropertyBuilder AsReadOnly();
IPropertyBuilder AsWriteOnly();
IPropertyBuilder WithGetter(string getterBody);
IPropertyBuilder WithSetter(string setterBody);
IPropertyBuilder WithGetterAccessModifier(string accessModifier);
IPropertyBuilder WithSetterAccessModifier(string accessModifier);
IPropertyBuilder WithInitializer(string initializer);
IPropertyBuilder WithInitSetter();
IPropertyBuilder WithAttribute(string attribute);
IPropertyBuilder WithExpressionBody(string expression);
IPropertyBuilder WithXmlDoc(string summary);

Example Usage:

// Expression body property
var propertyBuilder = new PropertyBuilder()
    .WithName("FullName")
    .WithType("string")
    .WithAccessModifier("public")
    .AsVirtual()
    .WithExpressionBody("$\"{FirstName} {LastName}\"")
    .WithXmlDoc("Gets the full name by combining first and last name");

// Auto-property with init setter
var autoPropertyBuilder = new PropertyBuilder()
    .WithName("CreatedAt")
    .WithType("DateTime")
    .WithAccessModifier("public")
    .AsReadOnly()
    .WithInitSetter()
    .WithInitializer("DateTime.UtcNow")
    .WithXmlDoc("Gets the creation timestamp");

string generatedCode = propertyBuilder.Build();

ConstructorBuilder

From Builders/ConstructorBuilder.cs:

Constructor generation including static constructors:

Supported Features:

• Constructor Types: Instance constructors, static constructors
• Parameters: Parameter support including default values
• Constructor Chaining: Base constructor calls and this() chaining
• Body Generation: Multi-line constructor body support

Available Methods (from ConstructorBuilder.cs:27-113):

ConstructorBuilder WithClassName(string className);
IConstructorBuilder WithAccessModifier(string accessModifier);
IConstructorBuilder AsStatic();
IConstructorBuilder WithParameter(string type, string name, string? defaultValue = null);
IConstructorBuilder WithBaseCall(params string[] arguments);
IConstructorBuilder WithThisCall(params string[] arguments);
IConstructorBuilder WithAttribute(string attribute);
IConstructorBuilder WithBody(string body);
IConstructorBuilder AddBodyLine(string line);
IConstructorBuilder WithXmlDoc(string summary);
IConstructorBuilder WithParamDoc(string parameterName, string description);

Example Usage:

var constructorBuilder = new ConstructorBuilder()
    .WithClassName("Customer")
    .WithAccessModifier("public")
    .WithParameter("string", "firstName")
    .WithParameter("string", "lastName")
    .WithParameter("DateTime?", "dateOfBirth", "null")
    .WithBaseCall("Guid.NewGuid()")
    .WithXmlDoc("Initializes a new customer instance")
    .WithParamDoc("firstName", "The customer's first name")
    .WithParamDoc("lastName", "The customer's last name")
    .WithParamDoc("dateOfBirth", "Optional date of birth")
    .AddBodyLine("FirstName = firstName;")
    .AddBodyLine("LastName = lastName;")
    .AddBodyLine("DateOfBirth = dateOfBirth;");

string generatedCode = constructorBuilder.Build();

FieldBuilder

From Builders/FieldBuilder.cs:

Field generation supporting C# field modifiers:

Supported Features:

• Field Types: Instance fields, static fields, constants, readonly fields
• Modifiers: volatile, readonly, const with proper validation
• Initializers: Field initialization (required for const fields)
• Preprocessor Directives: Support for conditional compilation

Available Methods (from FieldBuilder.cs:27-110):

IFieldBuilder WithName(string name);
IFieldBuilder WithType(string type);
IFieldBuilder WithAccessModifier(string accessModifier);
IFieldBuilder AsStatic();
IFieldBuilder AsReadOnly();
IFieldBuilder AsConst();
IFieldBuilder AsVolatile();
IFieldBuilder WithInitializer(string initializer);
IFieldBuilder WithAttribute(string attribute);
IFieldBuilder WithXmlDoc(string summary);
IFieldBuilder WithPreprocessorDirective(string directive);

Example Usage:

// Readonly field
var fieldBuilder = new FieldBuilder()
    .WithName("_logger")
    .WithType("ILogger")
    .WithAccessModifier("private")
    .AsReadOnly()
    .WithXmlDoc("The logger instance");

// Constant field
var constField = new FieldBuilder()
    .WithName("DefaultTimeout")
    .WithType("int")
    .WithAccessModifier("public")
    .AsConst()
    .WithInitializer("30");

string generatedCode = fieldBuilder.Build();

PropertyBuilder (Advanced Features)

Additional property patterns with custom accessors:

// Property with custom getter/setter
var advancedProperty = new PropertyBuilder()
    .WithName("Status")
    .WithType("CustomerStatus")
    .WithAccessModifier("public")
    .WithGetter("return _status;")
    .WithSetter("_status = value; OnPropertyChanged();")
    .WithSetterAccessModifier("private")
    .WithAttribute("JsonPropertyName(\"status\")");

// Expression body property
var computedProperty = new PropertyBuilder()
    .WithName("IsActive")
    .WithType("bool")
    .WithExpressionBody("Status == CustomerStatus.Active && LastLoginDate > DateTime.Now.AddDays(-30)");

Roslyn-Based Parsing

RoslynCSharpParser

From Parsing/RoslynCSharpParser.cs:

C# parser using Microsoft.CodeAnalysis:

Features:

• Full C# Support: Latest C# language version support via LanguageVersion.Latest
• Error Handling: Returns IGenericResult<ISyntaxTree> with error information
• Async Support: Async parsing with cancellation token support
• Documentation: XML documentation parsing via DocumentationMode.Parse
• Validation: Separate Validate() method for syntax validation

Available Methods (from RoslynCSharpParser.cs:16-82):

string Language { get; }  // Returns "csharp"

Task<IGenericResult<ISyntaxTree>> Parse(
    string sourceCode,
    string? filePath = null,
    CancellationToken cancellationToken = default);

Task<IGenericResult> Validate(
    string sourceCode,
    CancellationToken cancellationToken = default);

Example Usage:

var parser = new RoslynCSharpParser();
var result = await parser.Parse(sourceCode, "Customer.cs");

if (result.IsSuccess)
{
    var syntaxTree = result.Value;
    Console.WriteLine($"Parsed file: {syntaxTree.FilePath}");
    Console.WriteLine($"Has errors: {syntaxTree.HasErrors}");

    // Find all class declarations
    var classes = syntaxTree.FindNodes("ClassDeclarationSyntax");
    foreach (var classNode in classes)
    {
        Console.WriteLine($"Class node: {classNode.NodeType}");
    }
}

Note: The FindNodes() method uses Roslyn SyntaxKind names (e.g., ClassDeclarationSyntax), not simplified names.

RoslynSyntaxTree

From Parsing/RoslynSyntaxTree.cs:

Syntax tree implementation wrapping Roslyn's SyntaxTree:

Properties and Methods (from RoslynSyntaxTree.cs:33-106):

ISyntaxNode Root { get; }
string SourceText { get; }
string Language { get; }
string? FilePath { get; }
bool HasErrors { get; }

IEnumerable<ISyntaxNode> GetErrors();
IEnumerable<ISyntaxNode> FindNodes(string nodeType);
ISyntaxNode? GetNodeAtPosition(int position);
ISyntaxNode? GetNodeAtLocation(int line, int column);

RoslynSyntaxNode

From Parsing/RoslynSyntaxNode.cs:

Syntax node implementation wrapping Roslyn's SyntaxNode:

Properties and Methods (from RoslynSyntaxNode.cs:34-114):

string NodeType { get; }      // Returns SyntaxKind as string
string Text { get; }          // Node text content
int StartPosition { get; }
int EndPosition { get; }
int StartLine { get; }
int StartColumn { get; }
IReadOnlyList<ISyntaxNode> Children { get; }
ISyntaxNode? Parent { get; }
bool IsTerminal { get; }
bool IsError { get; }

ISyntaxNode? FindChild(string nodeType);
IEnumerable<ISyntaxNode> FindChildren(string nodeType);
IEnumerable<ISyntaxNode> DescendantNodes();

Code Generation

CSharpCodeGenerator

From Generators/CSharpCodeGenerator.cs:

Code generation engine implementing ICodeGenerator:

Available Methods (from CSharpCodeGenerator.cs:13-60):

string TargetLanguage { get; }  // Returns "csharp"

string Generate(ISyntaxTree syntaxTree);
string Generate(IClassBuilder classBuilder);
string Generate(IInterfaceBuilder interfaceBuilder);
string Generate(IEnumBuilder enumBuilder);
string GenerateCompilationUnit(IEnumerable<ICodeBuilder> builders);

Example Usage:

var generator = new CSharpCodeGenerator();

var builders = new ICodeBuilder[]
{
    new ClassBuilder()
        .WithNamespace("MyProject.Domain")
        .WithName("Customer")
        .WithAccessModifier("public"),
    new ClassBuilder()
        .WithNamespace("MyProject.Domain")
        .WithName("Order")
        .WithAccessModifier("public")
};

string compilationUnit = generator.GenerateCompilationUnit(builders);

Note: IInterfaceBuilder and IEnumBuilder implementations are not included in this package. Use ClassBuilder for class generation.

Language Registry

LanguageRegistry

From LanguageRegistry.cs:

Registry for language-specific parsers implementing ILanguageRegistry:

Features:

• Built-in C# Support: Registers RoslynCSharpParser for .cs and .csx extensions
• Extension Mapping: File extension to language resolution
• Dynamic Registration: Runtime parser registration capability

Available Methods (from LanguageRegistry.cs:29-128):

IReadOnlyList<string> SupportedLanguages { get; }

bool IsSupported(string language);
IReadOnlyList<string> GetExtensions(string language);
string? GetLanguageByExtension(string extension);
Task<ICodeParser?> GetParser(string language, CancellationToken cancellationToken = default);
void RegisterParser(string language, ICodeParser parser, params string[] extensions);

Example Usage:

var registry = new LanguageRegistry();

// Built-in support - returns nullable ICodeParser
var parser = await registry.GetParser("csharp");
if (parser != null)
{
    var result = await parser.Parse(sourceCode, "Customer.cs");
}

// Get language by extension
var language = registry.GetLanguageByExtension(".cs"); // Returns "csharp"

// Register custom parser
registry.RegisterParser("typescript", new TypeScriptParser(), ".ts", ".tsx");

Architecture and Design Patterns

Builder Pattern Implementation

The concrete builders implement a sophisticated builder pattern:

• Fluent Interface: Natural method chaining for code construction
• State Validation: Automatic validation of incompatible settings
• Lazy Generation: Code generation only occurs on Build() call
• Immutable Output: Generated code is immutable once created

Template Method Pattern

All builders follow a consistent generation workflow:

1. Initialization: Clear previous state and prepare for generation
2. Documentation: Generate XML documentation comments
3. Attributes: Apply attributes and annotations
4. Signature: Build the main construct signature
5. Body: Generate the construct body or members
6. Finalization: Complete the construct and return formatted code

Factory Pattern

The language registry implements a factory pattern for parser creation:

• Lazy Loading: Parsers created on demand
• Caching: Parser instances cached for performance
• Extension Points: Easy registration of custom parsers

Composite Pattern

Syntax tree implementation uses composite pattern:

• Uniform Interface: Consistent handling of simple and complex nodes
• Recursive Operations: Tree traversal and manipulation
• Flexible Queries: Deep searching with custom predicates

Usage Examples

Complete Class Generation

var customerClass = new ClassBuilder()
    .WithNamespace("MyProject.Domain.Entities")
    .WithUsings("System", "System.ComponentModel.DataAnnotations")
    .WithName("Customer")
    .WithAccessModifier("public")
    .AsSealed()
    .WithBaseClass("EntityBase")
    .WithInterfaces("IValidatableObject")
    .WithXmlDoc("Represents a customer entity")

    // Properties
    .WithProperty(new PropertyBuilder()
        .WithName("Id")
        .WithType("Guid")
        .WithAccessModifier("public")
        .AsReadOnly()
        .WithInitSetter()
        .WithXmlDoc("Gets the unique identifier"))

    .WithProperty(new PropertyBuilder()
        .WithName("FirstName")
        .WithType("string")
        .WithAccessModifier("public")
        .WithAttribute("Required")
        .AsReadOnly()
        .WithInitSetter())

    .WithProperty(new PropertyBuilder()
        .WithName("FullName")
        .WithType("string")
        .WithAccessModifier("public")
        .WithExpressionBody("$\"{FirstName} {LastName}\""))

    // Constructor
    .WithConstructor(new ConstructorBuilder()
        .WithClassName("Customer")
        .WithAccessModifier("public")
        .WithParameter("string", "firstName")
        .WithParameter("string", "lastName")
        .WithXmlDoc("Initializes a new customer instance")
        .AddBodyLine("FirstName = firstName;")
        .AddBodyLine("LastName = lastName;"))

    // Method
    .WithMethod(new MethodBuilder()
        .WithName("Validate")
        .WithReturnType("IEnumerable<ValidationResult>")
        .WithParameter("ValidationContext", "validationContext")
        .WithAccessModifier("public")
        .AddBodyLine("var results = new List<ValidationResult>();")
        .AddBodyLine("return results;"));

string generatedCode = customerClass.Build();

Code Analysis Workflow

var registry = new LanguageRegistry();
var parser = await registry.GetParser("csharp");

if (parser != null)
{
    // Parse existing code - note: method is Parse(), not ParseAsync()
    var parseResult = await parser.Parse(existingCode, "Customer.cs");
    if (parseResult.IsSuccess)
    {
        var tree = parseResult.Value;

        // Find all properties - uses Roslyn SyntaxKind names
        var properties = tree.FindNodes("PropertyDeclarationSyntax");

        foreach (var property in properties)
        {
            Console.WriteLine($"Property: {property.NodeType}");
            Console.WriteLine($"Text: {property.Text}");
        }
    }
}

Batch Code Generation

var entities = new[] { "Customer", "Order", "Product" };
var generator = new CSharpCodeGenerator();
var builders = new List<ICodeBuilder>();

foreach (var entity in entities)
{
    // Generate entity class
    builders.Add(new ClassBuilder()
        .WithNamespace($"MyProject.Domain")
        .WithName(entity)
        .WithAccessModifier("public")
        .AsSealed()
        .WithBaseClass("EntityBase"));
}

string compilationUnit = generator.GenerateCompilationUnit(builders);

Note: InterfaceBuilder and EnumBuilder implementations are not included in this package.

Dependencies

Required Dependencies

• FractalDataWorks.CodeBuilder.Abstractions: Interface definitions (IClassBuilder, ICodeParser, etc.)
• FractalDataWorks.Results: Framework result patterns (IGenericResult<T>)
• Microsoft.CodeAnalysis.CSharp: Roslyn C# parser and syntax analysis

Target Framework

This package targets netstandard2.0 for broad compatibility with .NET Framework 4.6.1+, .NET Core 2.0+, and .NET 5+.

Integration Examples

With Dependency Injection

services.AddSingleton<ILanguageRegistry, LanguageRegistry>();
services.AddTransient<ICodeGenerator, CSharpCodeGenerator>();

Creating Custom Builders

Since ClassBuilder is sealed, create wrapper classes for custom functionality:

public class EntityClassFactory
{
    public ClassBuilder CreateEntity(string name, string tableName)
    {
        return new ClassBuilder()
            .WithName(name)
            .WithAccessModifier("public")
            .AsSealed()
            .WithAttribute($"Table(\"{tableName}\")");
    }
}

Custom Parser Registration

public class TypeScriptParser : ICodeParser
{
    public string Language => "typescript";

    public Task<IGenericResult<ISyntaxTree>> Parse(
        string sourceCode,
        string? filePath = null,
        CancellationToken cancellationToken = default)
    {
        // Custom implementation
        throw new NotImplementedException();
    }

    public Task<IGenericResult> Validate(
        string sourceCode,
        CancellationToken cancellationToken = default)
    {
        // Custom implementation
        throw new NotImplementedException();
    }
}

// Register with LanguageRegistry
var registry = new LanguageRegistry();
registry.RegisterParser("typescript", new TypeScriptParser(), ".ts", ".tsx");

Related Packages

• FractalDataWorks.CodeBuilder.Abstractions - Interface definitions