FractalDataWorks.Tools 0.1.26-alpha-gf64f8fdedf

FractalDataWorks Developer Kit

🚧 IN PROGRESS - Enhanced Enum Type Factories implementation in progress

A comprehensive .NET library framework providing foundational abstractions and implementations for building scalable, maintainable enterprise applications.

Overview

The FractalDataWorks Developer Kit is a layered architecture framework that provides:

• Core abstractions for services, configuration, validation, and results
• Service patterns with built-in validation, Serilog structured logging, and error handling
• Configuration management with validation and registry patterns
• Enhanced messaging using the EnhancedEnums pattern for type-safe, maintainable messages
• Extensible architecture supporting dependency injection, data access, hosting, and tools

Architecture

The framework follows a progressive layered architecture with clear separation between core abstractions and implementations. All core interfaces reside in Layer 0.5, while implementations are provided in Layer 1 packages.

Key Architectural Patterns

1. Universal Data Service: A single data service handles all data operations through a command pattern with provider-specific implementations
2. External Connections as Boundaries: External connections represent the boundary between the framework and external systems
3. Command Transformation: Universal commands (LINQ-like) are transformed to provider-specific commands via command builders
4. Service Factory Pattern: Services use factories to obtain and manage connections internally

Layer 0.5 - Core Foundation (No Dependencies)

• FractalDataWorks.net - Core abstractions and base types (targets netstandard2.0 for maximum compatibility)
  • IFdwService - Base service abstraction
  • IFdwConfiguration - Configuration abstraction
  • IFdwResult & FdwResult<T> - Consistent result pattern
  • ServiceMessage - Enhanced enum-based messaging system
  • IFdwValidator<T> - Validation abstractions
  • IServiceFactory - Service factory abstraction
  • IConfigurationRegistry - Configuration registry abstraction
  • IExternalConnection - External connection boundary interface
  • IFdwConnection - Framework connection wrapper
  • IDataConnection - Universal data service abstraction
  • IFdwDataCommand - Universal data command interface (Query/Insert/Update/Upsert/Delete)

Layer 1 - Domain-Specific Implementations

• FractalDataWorks.Services - Service patterns and base implementations

  • ServiceBase<TConfiguration, TCommand> - Base service with validation and Serilog structured logging
  • DataConnection<TDataCommand, TConnection> - Universal data service implementation
  • Built-in command validation and error handling
  • Comprehensive logging with ServiceBaseLog using source generators and Serilog destructuring

• FractalDataWorks.Configuration - Configuration providers and patterns

  • ConfigurationBase<T> - Self-validating configuration base class
  • ConfigurationProviderBase - Provider pattern implementation
  • ConfigurationSourceBase - Configuration source abstractions

• FractalDataWorks.Connections - External connection implementations

  • ExternalConnectionBase<TCommandBuilder, TCommand, TConnection, TFactory, TConfig> - Base for provider-specific connections
  • ExternalConnectionProvider - Selects appropriate connection factory
  • Provider implementations (e.g., MsSqlConnection, PostgresConnection)
  • Command builders that transform universal commands to provider-specific commands

• FractalDataWorks.DependencyInjection - DI container abstractions

  • Container-agnostic dependency injection patterns
  • Service registration extensions

• FractalDataWorks.Tools - Common utilities and helpers

  • Extension methods and utility classes
  • Common helper functions

• FractalDataWorks.Hosts - Web and worker host abstractions

  • Host service abstractions
  • Background service patterns

• FractalDataWorks.Data - Entity base classes and data patterns

  • Entity base classes with audit fields
  • Soft delete and versioning support
  • Entity validation patterns

Package Documentation

Each package has its own detailed README with usage examples and API documentation:

Core Foundation

• FractalDataWorks.net - Core abstractions and base types

Layer 1 Packages

• FractalDataWorks.Services - Service patterns and base implementations
• FractalDataWorks.Configuration - Configuration management system
• FractalDataWorks.Connections - Connection abstractions and base implementations
• FractalDataWorks.Data - Data access abstractions and entity base classes
• FractalDataWorks.DependencyInjection - DI container abstractions (planning phase)
• FractalDataWorks.Hosts - Host service abstractions (planning phase)
• FractalDataWorks.Tools - Common utilities and helpers (planning phase)

Git Workflow

This repository follows a git-flow branching strategy:

1. master - Production-ready releases only
2. develop - Main development branch
3. feature/ - Feature branches
4. beta/ - Beta release branches
5. release/ - Release candidate branches
6. experimental/ - Experimental features

Setting up the Development Branch

After cloning, create the develop branch from master:

git checkout -b develop
git push -u origin develop

Creating Feature Branches

Always branch from develop:

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

Building and Testing

Prerequisites

• .NET 10.0 Preview SDK
• Visual Studio 2022 Preview or VS Code

Build Commands

# Restore packages
dotnet restore

# Build solution
dotnet build

# Run tests
dotnet test

# Pack NuGet packages
dotnet pack

Configuration-Specific Builds

# Debug build (default)
dotnet build

# Alpha build
dotnet build -c Alpha

# Beta build
dotnet build -c Beta

# Release build
dotnet build -c Release

Package Dependencies

Each Layer 1 package depends on FractalDataWorks.net. Additional dependencies:

• FractalDataWorks.DependencyInjection also depends on FractalDataWorks.Configuration
• FractalDataWorks.Hosts also depends on FractalDataWorks.Services

Testing

All projects use xUnit.v3 for testing. Test projects follow the naming convention: FractalDataWorks.[Package].Tests

Run tests with:

dotnet test

CI/CD

This repository includes both Azure Pipelines and GitHub Actions workflows for CI/CD.

Azure Pipelines

• Configuration: azure-pipelines.yml
• Publishes to Azure Artifacts feed: dotnet-packages

GitHub Actions

• Configuration: .github/workflows/ci.yml
• Publishes to GitHub Packages and optionally Azure Artifacts

Contributing

1. Create a feature branch from develop
2. Make your changes
3. Ensure all tests pass
4. Submit a pull request to develop

Key Features

Service Pattern

public class MyService : ServiceBase<MyConfiguration, MyCommand>
{
    public MyService(ILogger<MyService> logger, IConfigurationRegistry<MyConfiguration> configs)
        : base(logger, configs)
    {
    }

    protected override async Task<FdwResult<TResult>> ExecuteCore<TResult>(MyCommand command)
    {
        // Implementation with automatic validation and error handling
    }
}

Configuration Management

public class MyConfiguration : ConfigurationBase<MyConfiguration>
{
    public string ConnectionString { get; set; }
    public int Timeout { get; set; }
    
    protected override FluentValidation.Results.ValidationResult ValidateCore()
    {
        var validator = new MyConfigurationValidator();
        return validator.Validate(this);
    }
}

Enhanced Messaging

// Type-safe, discoverable service messages with Serilog structured logging
_logger.LogError("Invalid configuration: {Error}", ServiceMessages.InvalidConfiguration.Format("Missing connection string"));
_logger.LogInformation("Service started: {ServiceName}", ServiceName);

// Enhanced structured logging with Serilog destructuring
_logger.LogError("Connection failed after {Retries} attempts: {@Error}", 
    retries, new { Message = errorMessage, Timestamp = DateTime.UtcNow });

// Use ServiceBaseLog for comprehensive structured logging
ServiceBaseLog.CommandExecutedWithContext(_logger, command);
ServiceBaseLog.PerformanceMetrics(_logger, new PerformanceMetrics(150.5, 1000, "BatchProcess"));

Result Pattern

// Consistent error handling across all services
var result = await service.Execute<Customer>(command);
if (result.IsSuccess)
{
    return Ok(result.Value);
}
else
{
    return BadRequest(result.Error);
}

Universal Data Service Pattern

// Universal data service that works with any data source
public class DataConnection<TDataCommand, TConnection> : ServiceBase<TDataCommand>
    where TDataCommand : IFdwDataCommand
{
    private readonly IExternalConnectionProvider _connectionProvider;
    
    protected override async Task<FdwResult<TResult>> ExecuteCore<TResult>(TDataCommand command)
    {
        // Provider selects appropriate connection based on configuration
        var connection = await _connectionProvider.GetConnection(command.ConnectionId);
        return await connection.Execute<TResult>(command);
    }
}

// SQL Server provider implementation
public class MsSqlConnection : ExternalConnectionBase<SqlCommandBuilder, SqlCommand, SqlConnection, SqlConnectionFactory, SqlConfiguration>
{
    protected override SqlCommand BuildCommand(IFdwDataCommand dataCommand)
    {
        // SqlCommandBuilder transforms universal command to SQL
        return CommandBuilder.Build(dataCommand);
    }
}

Code Quality

The framework enforces code quality through:

• Analyzers: StyleCop, AsyncFixer, Meziantou.Analyzer, Roslynator
• Threading Analysis: Microsoft.VisualStudio.Threading.Analyzers
• XML Documentation: Required for all public/protected members
• Testing: xUnit v3 with parallel execution
• Coverage: Coverlet integration for code coverage
• Build Configurations: Progressive quality gates from Debug to Release

Enhanced Enum Type Factories

🚧 IN PROGRESS - New pattern for type registration using Enhanced Enums

The Enhanced Enum Type Factories pattern provides compile-time safe, automatically registered factory types for services, connections, and tools. This pattern leverages source generators to create strongly-typed collections with full IntelliSense support.

Key Benefits

• Compile-time Safety: All types are verified at compile time
• IntelliSense Support: Full IDE support for generated collections (ServiceTypes., ConnectionTypes., ToolTypes.*)
• Automatic DI Registration: Types are automatically registered with dependency injection
• Factory Pattern: Each type acts as a factory for creating instances
• Discoverability: Easy discovery of available types through generated static collections

Quick Example

// Define a service type
[EnumOption(1, "EmailNotification", "Email notification service")]
public class EmailNotificationServiceType : ServiceTypeBase<INotificationService, EmailConfiguration>
{
    public override object Create(EmailConfiguration configuration)
    {
        return new EmailNotificationService(configuration);
    }
}

// Use the generated collections
var emailService = ServiceTypes.EmailNotification.Instance;
var allServices = ServiceTypes.All;
var service = ServiceTypes.GetByName("EmailNotification");

// Automatic DI registration
services.AddServiceTypes(Assembly.GetExecutingAssembly());

For detailed documentation, see Enhanced Enum Type Factories Documentation.

Quality Gate Configurations

License

Apache License 2.0 - see LICENSE file for details.