FractalDataWorks.Configuration.SourceGenerators 0.6.0-rc.1

FractalDataWorks.Configuration.SourceGenerators

Incremental source generator that creates DDL definitions, ConfigurationTypes collection, FluentValidation validators, and validation logging from [ManagedConfiguration] attributes.

Features

• Embedded Attributes: No runtime dependency required - attributes are generated into your assembly
• DDL Generation: Generates SQL Server DDL for configuration tables with parent/child relationships
• ConfigurationTypes Collection: Compile-time discovery of all managed configurations
• FluentValidation: Generates validators with TypeCollection reference validation
• Validation Logging: Generates [MessageLogging] methods for validation error logging

Usage

From MsSqlConnectionConfiguration.cs:43-54:

[ManagedConfiguration(
    Schema = "cfg",
    TableName = "MsSqlConnection",
    Parent = nameof(ConnectionConfigurationBase<MsSqlConnectionConfiguration>),
    ServiceCategory = "Connection",
    ServiceType = "MsSql")]
public partial class MsSqlConnectionConfiguration : ConnectionConfigurationBase<MsSqlConnectionConfiguration>
{
    public override string ConnectionType => "MsSql";
    public string Server { get; set; } = "localhost";
    public string Database { get; set; } = string.Empty;
    public int Port { get; set; } = 1433;
}

Parent configurations define shared properties that child configurations inherit. The generator creates parent-child DDL relationships with foreign keys.

Generated Output

• {ClassName}.Ddl.g.cs - DDL definition with table schema
• {ClassName}.Validator.g.cs - FluentValidation validator
• {ClassName}.ValidationLog.g.cs - Logging messages for validation
• ConfigurationTypes.g.cs - Discovery collection with All(), ByName(), FromType<T>()
• {TypeCollection}.TypeCollectionDdl.g.cs - DDL for TypeCollection lookup tables
• TypeCollectionDdlRegistry.g.cs - Registry of TypeCollections requiring tables

Attributes

[ManagedConfiguration]

Marks a class as a managed configuration.

From ManagedConfigurationAttribute.cs (embedded source):

[ConfigurationOption]

Marks a property as referencing a TypeCollection. Generates FK from configuration table to TypeCollection table and validation rules.

From ConfigurationOptionAttribute.cs (embedded source):

[DbType]

Overrides the default SQL type mapping for a property.

From DbTypeAttribute.cs (embedded source):

TypeCollection DDL Generation

When a configuration property references a TypeCollection via [ConfigurationOption], the generator automatically creates DDL for the TypeCollection lookup table.

How It Works

1. Generator Phase: When you add [ConfigurationOption(typeof(ConnectionStates))] to a property:

   • DDL is generated for the ConnectionStates lookup table (Id int PK, Name varchar unique)
   • FK is added from the configuration table to the TypeCollection table
   • A TypeCollectionDdlRegistry is generated listing all TypeCollections

2. Bootstrap Phase: When the application starts, ConfigurationSchemaBootstrapService:

   • Creates TypeCollection tables if they don't exist
   • Seeds data by calling TypeCollection.All() and inserting each option
   • Creates configuration tables with FK constraints

Example

The [ConfigurationOption] attribute marks a property as referencing a TypeCollection. This generates a foreign key constraint from the configuration table to the TypeCollection lookup table.

// Illustrative example - [ConfigurationOption] creates FK to TypeCollection table
[ManagedConfiguration]
public class ConnectionMonitorConfiguration
{
    public Guid Id { get; set; }
    public string Name { get; set; } = string.Empty;

    // Creates FK: ConnectionMonitor.InitialState -> ConnectionStates.Name
    [ConfigurationOption(typeof(ConnectionStates))]
    public string InitialState { get; set; } = "Disconnected";

    // Creates FK: ConnectionMonitor.DefaultStateId -> ConnectionStates.Id
    [ConfigurationOption(typeof(ConnectionStates), ById = true)]
    public int DefaultStateId { get; set; } = 1;
}

The TypeCollection referenced above is defined in the codebase.

From ConnectionStates.cs:12-14:

[TypeCollection(typeof(ConnectionStateBase), typeof(IConnectionState), typeof(ConnectionStates))]
public abstract partial class ConnectionStates : TypeCollectionBase<ConnectionStateBase, IConnectionState>
{
}

Generated Database Schema

The generator produces DDL for both the TypeCollection lookup table and the configuration table with foreign key constraints:

-- TypeCollection table (created first)
CREATE TABLE cfg.ConnectionStates (
    Id int NOT NULL PRIMARY KEY,
    Name varchar(100) NOT NULL UNIQUE
);

-- TypeCollection data seeded from ConnectionStates.All()
INSERT INTO cfg.ConnectionStates (Id, Name) VALUES (1, 'Disconnected');
INSERT INTO cfg.ConnectionStates (Id, Name) VALUES (2, 'Connecting');
INSERT INTO cfg.ConnectionStates (Id, Name) VALUES (3, 'Connected');
-- ...

-- Configuration table with FKs
CREATE TABLE cfg.ConnectionMonitor (
    Id uniqueidentifier NOT NULL PRIMARY KEY,
    Name varchar(256) NOT NULL UNIQUE,
    InitialState varchar(100) NOT NULL,
    DefaultStateId int NOT NULL,
    CONSTRAINT FK_ConnectionMonitor_ConnectionStates FOREIGN KEY (InitialState) REFERENCES cfg.ConnectionStates(Name),
    CONSTRAINT FK_ConnectionMonitor_ConnectionStates_Id FOREIGN KEY (DefaultStateId) REFERENCES cfg.ConnectionStates(Id)
);

Idempotent Behavior

All operations are idempotent:

• Tables are only created if they don't exist
• Columns are only added if missing
• TypeOption rows are only inserted if not present (checked by Id)
• Safe to run multiple times

Installation

Reference this source generator in your project:

<ItemGroup>
  <ProjectReference Include="..\..\src\FractalDataWorks.Configuration.SourceGenerators\FractalDataWorks.Configuration.SourceGenerators.csproj"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>

The OutputItemType="Analyzer" and ReferenceOutputAssembly="false" attributes are required for source generator references.

Related Packages

• FractalDataWorks.Configuration - Runtime configuration management
• FractalDataWorks.Configuration.Persistence - Database schema management and bootstrap service
• FractalDataWorks.Collections.SourceGenerators - TypeCollection source generator
• FractalDataWorks.Configuration.UI.SourceGenerators - UI component generation for configurations

Next Steps

• See the Configuration Persistence package for schema bootstrap setup
• Review TypeCollection documentation for creating TypeCollections referenced by [ConfigurationOption]
• See MsSqlConnectionConfiguration for a complete parent-child configuration example