Classes Reference¶

namespace Dtde.EntityFramework;

public abstract class DtdeDbContext : DbContext

/// <summary>
/// Initializes a new instance with default options.
/// </summary>
protected DtdeDbContext()

/// <summary>
/// Initializes a new instance with specified options.
/// </summary>
/// <param name="options">The DbContext options.</param>
protected DtdeDbContext(DbContextOptions options)

/// <summary>
/// Gets a queryable filtered to entities valid at the specified date.
/// </summary>
/// <typeparam name="TEntity">The entity type.</typeparam>
/// <param name="asOfDate">The point in time.</param>
/// <returns>A queryable filtered to valid entities.</returns>
public IQueryable<TEntity> ValidAt<TEntity>(DateTime asOfDate)
    where TEntity : class

/// <summary>
/// Gets a queryable filtered to entities valid within the specified date range.
/// </summary>
/// <typeparam name="TEntity">The entity type.</typeparam>
/// <param name="startDate">The start of the range.</param>
/// <param name="endDate">The end of the range.</param>
/// <returns>A queryable filtered to valid entities.</returns>
public IQueryable<TEntity> ValidBetween<TEntity>(DateTime startDate, DateTime endDate)
    where TEntity : class

/// <summary>
/// Gets all versions of entities, bypassing temporal filtering.
/// </summary>
/// <typeparam name="TEntity">The entity type.</typeparam>
/// <returns>A queryable with all entity versions.</returns>
public IQueryable<TEntity> AllVersions<TEntity>()
    where TEntity : class

// Provisioning
public static Task EnsureAllShardsCreatedAsync(
    this DtdeDbContext context,
    CancellationToken cancellationToken = default);

// Cross-shard transactions
public static Task<ICrossShardTransaction> BeginCrossShardTransactionAsync(
    this DtdeDbContext context,
    CancellationToken cancellationToken = default);

public static Task<ICrossShardTransaction> BeginCrossShardTransactionAsync(
    this DtdeDbContext context,
    CrossShardTransactionOptions options,
    CancellationToken cancellationToken = default);

// Bulk operations
public static Task<int> BulkInsertAsync<TEntity>(
    this DtdeDbContext context,
    IEnumerable<TEntity> entities,
    CancellationToken cancellationToken = default)
    where TEntity : class;

public static Task<int> BulkDeleteAsync<TEntity>(
    this DtdeDbContext context,
    Expression<Func<TEntity, bool>> filter,
    CancellationToken cancellationToken = default)
    where TEntity : class;

// EF 7-9 signature:
public static Task<int> BulkUpdateAsync<TEntity>(
    this DtdeDbContext context,
    Expression<Func<TEntity, bool>> filter,
    Expression<Func<SetPropertyCalls<TEntity>, SetPropertyCalls<TEntity>>> setPropertyCalls,
    CancellationToken cancellationToken = default)
    where TEntity : class;

// EF 10 signature (selected via #if NET10_0_OR_GREATER):
public static Task<int> BulkUpdateAsync<TEntity>(
    this DtdeDbContext context,
    Expression<Func<TEntity, bool>> filter,
    Action<UpdateSettersBuilder<TEntity>> setters,
    CancellationToken cancellationToken = default)
    where TEntity : class;

namespace Dtde.Core.Metadata;

public sealed class ShardMetadata : IShardMetadata

/// <summary>
/// Creates a table shard with the specified table name.
/// </summary>
public static ShardMetadata ForTable(
    string shardId,
    string tableName,
    string? shardKeyValue = null,
    string schemaName = "dbo")

/// <summary>
/// Creates a database shard with the specified connection string.
/// </summary>
public static ShardMetadata ForDatabase(
    string shardId,
    string name,
    string connectionString,
    string? shardKeyValue = null)

namespace Dtde.Core.Metadata;

public class ShardMetadataBuilder

namespace Dtde.Core.Metadata;

public class ShardRegistry : IShardRegistry

/// <summary>
/// Gets all registered shards.
/// </summary>
public IReadOnlyList<IShardMetadata> GetAllShards()

/// <summary>
/// Gets a shard by ID.
/// </summary>
public IShardMetadata? GetShard(string shardId)

/// <summary>
/// Gets shards covering a date range.
/// </summary>
public IEnumerable<IShardMetadata> GetShardsForDateRange(DateTime startDate, DateTime endDate)

/// <summary>
/// Gets all writable shards (not read-only).
/// </summary>
public IEnumerable<IShardMetadata> GetWritableShards()

/// <summary>
/// Gets shards by storage tier.
/// </summary>
public IEnumerable<IShardMetadata> GetShardsByTier(ShardTier tier)

/// <summary>
/// Adds a shard to the registry.
/// </summary>
public void AddShard(IShardMetadata shard)

namespace Dtde.Core.Metadata;

public readonly struct DateRange

/// <summary>
/// Checks if a date falls within this range.
/// </summary>
public bool Contains(DateTime date)

/// <summary>
/// Checks if this range intersects with another.
/// </summary>
public bool Intersects(DateRange other)

/// <summary>
/// Gets the intersection of two ranges.
/// </summary>
public DateRange? Intersection(DateRange other)

namespace Dtde.Core.Metadata;

public sealed class EntityMetadata : IEntityMetadata

namespace Dtde.Core.Metadata;

public class MetadataRegistry : IMetadataRegistry

/// <summary>
/// Gets metadata for an entity type.
/// </summary>
public IEntityMetadata? GetEntityMetadata<TEntity>() where TEntity : class

/// <summary>
/// Gets metadata for an entity type.
/// </summary>
public IEntityMetadata? GetEntityMetadata(Type entityType)

/// <summary>
/// Registers entity metadata.
/// </summary>
public void RegisterEntity(IEntityMetadata metadata)

namespace Dtde.EntityFramework.Query;

public sealed class ShardedQueryExecutor : IShardedQueryExecutor

public ShardedQueryExecutor(
    IShardRegistry shardRegistry,
    IMetadataRegistry metadataRegistry,
    ITemporalContext temporalContext,
    IShardContextFactory shardContextFactory,
    ILogger<ShardedQueryExecutor> logger)

/// <summary>
/// Executes a query across all relevant shards.
/// </summary>
/// <typeparam name="TEntity">The entity type.</typeparam>
/// <param name="query">The LINQ query to execute.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Combined results from all shards.</returns>
public async Task<IReadOnlyList<TEntity>> ExecuteAsync<TEntity>(
    IQueryable<TEntity> query,
    CancellationToken cancellationToken = default)
    where TEntity : class

/// <summary>
/// Executes a scalar aggregation across shards.
/// </summary>
public async Task<TResult> ExecuteScalarAsync<TEntity, TResult>(
    IQueryable<TEntity> query,
    Func<IEnumerable<TResult>, TResult> aggregator,
    CancellationToken cancellationToken = default)
    where TEntity : class

namespace Dtde.EntityFramework.Query;

public class ShardContextFactory : IShardContextFactory

/// <summary>
/// Creates a DbContext for a specific shard.
/// </summary>
public async Task<DbContext> CreateContextAsync(
    IShardMetadata shard,
    CancellationToken cancellationToken = default)

namespace Dtde.EntityFramework.Query;

public class DtdeExpressionRewriter : IExpressionRewriter

/// <summary>
/// Rewrites an expression for execution on a specific shard.
/// </summary>
public Expression Rewrite(Expression expression, IShardMetadata shard)

namespace Dtde.EntityFramework.Update;

public sealed class ShardWriteRouter

public ShardWriteRouter(
    IShardRegistry shardRegistry,
    IMetadataRegistry metadataRegistry,
    ILogger<ShardWriteRouter> logger)

/// <summary>
/// Resolves the target shard for an entity.
/// </summary>
public IShardMetadata ResolveTargetShard<TEntity>(TEntity entity)
    where TEntity : class

/// <summary>
/// Routes all tracked changes to appropriate shards.
/// </summary>
public void RouteChanges(ChangeTracker changeTracker)

namespace Dtde.EntityFramework.Update;

public sealed class DtdeUpdateProcessor : IDtdeUpdateProcessor

/// <summary>
/// Processes changes before SaveChanges.
/// </summary>
public void ProcessChanges(ChangeTracker changeTracker)

/// <summary>
/// Creates a new version of an entity.
/// </summary>
public TEntity CreateNewVersion<TEntity>(
    TEntity entity,
    Action<TEntity> applyChanges,
    DateTime effectiveFrom)
    where TEntity : class

namespace Dtde.EntityFramework.Update;

public class VersionManager

/// <summary>
/// Creates a new version of a temporal entity.
/// </summary>
public TEntity CreateVersion<TEntity>(
    TEntity original,
    DateTime effectiveFrom,
    DateTime? expirationDate = null)
    where TEntity : class, new()

/// <summary>
/// Closes the validity of an entity.
/// </summary>
public void CloseValidity<TEntity>(
    TEntity entity,
    DateTime closureDate)
    where TEntity : class

namespace Dtde.Core.Transactions;

public sealed class CrossShardTransactionCoordinator : ICrossShardTransactionCoordinator

// With an explicit transaction log for crash recovery:
public CrossShardTransactionCoordinator(
    IShardRegistry shardRegistry,
    ShardParticipantFactory participantFactory,
    ITransactionLog? transactionLog,
    ILogger<CrossShardTransactionCoordinator> logger,
    ILogger<CrossShardTransaction> transactionLogger);

// Without a log (uses null):
public CrossShardTransactionCoordinator(
    IShardRegistry shardRegistry,
    ShardParticipantFactory participantFactory,
    ILogger<CrossShardTransactionCoordinator> logger,
    ILogger<CrossShardTransaction> transactionLogger);

/// <summary>
/// Begins a new cross-shard transaction.
/// </summary>
public async Task<ICrossShardTransaction> BeginTransactionAsync(
    CrossShardTransactionOptions? options = null,
    CancellationToken cancellationToken = default)

/// <summary>
/// Executes an action within a transaction with automatic commit/rollback.
/// </summary>
public async Task ExecuteInTransactionAsync(
    Func<ICrossShardTransaction, Task> action,
    CrossShardTransactionOptions? options = null,
    CancellationToken cancellationToken = default)

/// <summary>
/// Executes a function within a transaction and returns a result.
/// </summary>
public async Task<TResult> ExecuteInTransactionAsync<TResult>(
    Func<ICrossShardTransaction, Task<TResult>> func,
    CrossShardTransactionOptions? options = null,
    CancellationToken cancellationToken = default)

/// <summary>
/// Recovers in-doubt transactions after a failure.
/// </summary>
public async Task<int> RecoverAsync(CancellationToken cancellationToken = default)

namespace Dtde.Core.Transactions;

public sealed class CrossShardTransaction : ICrossShardTransaction

/// <summary>
/// Enlists a shard by its fully-qualified id or default-group local id.
/// </summary>
public Task EnlistAsync(string shardId, CancellationToken cancellationToken = default);

/// <summary>
/// Enlists a shard via its metadata. Uses ToQualifiedId() so
/// same-local-id-different-group shards don't alias.
/// </summary>
public Task EnlistAsync(IShardMetadata shard, CancellationToken cancellationToken = default);

/// <summary>
/// Gets or creates the participant for the given shard. The common
/// way to drive writes inside a transaction.
/// </summary>
public Task<ShardTransactionParticipant> GetOrCreateParticipantAsync(
    string shardId, CancellationToken cancellationToken = default);

public Task<ShardTransactionParticipant> GetOrCreateParticipantAsync(
    IShardMetadata shard, CancellationToken cancellationToken = default);

/// <summary>
/// 2PC commit — prepare across all participants, then commit. Skips
/// the prepare phase for single-shard transactions.
/// </summary>
public Task CommitAsync(CancellationToken cancellationToken = default);

/// <summary>
/// Rolls back every enlisted participant.
/// </summary>
public Task RollbackAsync(CancellationToken cancellationToken = default);

public ITransactionParticipant? GetParticipant(string shardId);

public ValueTask DisposeAsync();

namespace Dtde.Abstractions.Transactions;

public class CrossShardTransactionOptions

namespace Dtde.Core.Transactions;

public sealed class ShardTransactionParticipant : ITransactionParticipant, IAsyncDisposable

/// <summary>
/// 2PC phase 1: SaveChangesAsync inside the open transaction, return a vote.
/// </summary>
public Task<ParticipantVote> PrepareAsync(CancellationToken cancellationToken = default);

/// <summary>
/// 2PC phase 2: commit the local transaction. Called for both Prepared
/// and ReadOnly participants — a ReadOnly participant may still hold work
/// from earlier SaveChangesAsync calls (e.g. inside bulk paths).
/// </summary>
public Task CommitAsync(CancellationToken cancellationToken = default);

/// <summary>
/// Roll back the local transaction. Idempotent; safe in dispose.
/// </summary>
public Task RollbackAsync(CancellationToken cancellationToken = default);

/// <summary>
/// Creates a named savepoint inside the local transaction. No-op for
/// providers that don't support savepoints.
/// </summary>
public Task CreateSavepointAsync(string savepointName, CancellationToken cancellationToken = default);

/// <summary>
/// Rolls the local transaction back to a previously-created savepoint.
/// The transaction stays open; only work after the savepoint is undone.
/// Clears the change tracker so subsequent reads see fresh state.
/// </summary>
public Task RollbackToSavepointAsync(string savepointName, CancellationToken cancellationToken = default);

/// <summary>
/// Releases a savepoint, discarding the ability to roll back to it.
/// </summary>
public Task ReleaseSavepointAsync(string savepointName, CancellationToken cancellationToken = default);

namespace Dtde.EntityFramework.Infrastructure;

public class TransparentShardingInterceptor : SaveChangesInterceptor, IDbTransactionInterceptor

public TransparentShardingInterceptor(
    IServiceProvider serviceProvider,
    ILogger<TransparentShardingInterceptor> logger)

namespace Dtde.EntityFramework.Configuration;

public sealed class DtdeOptions

namespace Dtde.EntityFramework.Configuration;

public sealed class ShardingBuilder<TEntity> where TEntity : class

namespace Dtde.EntityFramework.Configuration;

public sealed class DtdeShardGroupBuilder

namespace Dtde.EntityFramework.Configuration;

public sealed class DtdeOptionsBuilder

namespace Dtde.EntityFramework.Infrastructure;

public class DtdeOptionsExtension : IDbContextOptionsExtension

namespace Dtde.Abstractions.Metadata;

public interface IShardMetadata
{
    string ShardId { get; }
    string Name { get; }
    ShardStorageMode StorageMode { get; }
    string? TableName { get; }
    string? SchemaName { get; }
    string? ConnectionString { get; }
    string? ShardKeyValue { get; }
    DateRange? DateRange { get; }
    KeyRange? KeyRange { get; }
    ShardTier Tier { get; }
    bool IsReadOnly { get; }
    int Priority { get; }
}

namespace Dtde.Abstractions.Metadata;

public interface IShardRegistry
{
    IReadOnlyList<IShardMetadata> GetAllShards();
    IShardMetadata? GetShard(string shardId);
    IEnumerable<IShardMetadata> GetShardsForDateRange(DateTime startDate, DateTime endDate);
    IEnumerable<IShardMetadata> GetWritableShards();
    IEnumerable<IShardMetadata> GetShardsByTier(ShardTier tier);
    void AddShard(IShardMetadata shard);
}

namespace Dtde.Abstractions.Metadata;

public interface IMetadataRegistry
{
    IEntityMetadata? GetEntityMetadata<TEntity>() where TEntity : class;
    IEntityMetadata? GetEntityMetadata(Type entityType);
    void RegisterEntity(IEntityMetadata metadata);
}

namespace Dtde.Abstractions.Metadata;

public interface IEntityMetadata
{
    Type ClrType { get; }
    string TableName { get; }
    string SchemaName { get; }
    IPropertyMetadata? PrimaryKey { get; }
    ITemporalConfiguration? TemporalConfiguration { get; }
    IShardingConfiguration? ShardingConfiguration { get; }
    bool IsTemporal { get; }
    bool IsSharded { get; }
}

namespace Dtde.Abstractions.Temporal;

public interface ITemporalConfiguration
{
    IPropertyMetadata ValidFromProperty { get; }
    IPropertyMetadata? ValidToProperty { get; }
    bool IsOpenEnded { get; }
    DateTime OpenEndedValue { get; }

    Expression<Func<TEntity, bool>> BuildPredicate<TEntity>(DateTime pointInTime);
}

namespace Dtde.Abstractions.Metadata;

public interface IShardingStrategy
{
    string StrategyType { get; }
    IEnumerable<IShardMetadata> ResolveShards(
        Expression? predicate,
        IShardRegistry registry);
    IShardMetadata ResolveWriteShard(
        object entity,
        IShardRegistry registry);
}

namespace Dtde.Abstractions.Temporal;

public interface ITemporalContext
{
    DateTime? CurrentPoint { get; }
    bool IncludeHistory { get; }

    void SetTemporalContext(DateTime asOfDate);
    void EnableHistoryMode();
    void ClearContext();
}

namespace Dtde.EntityFramework.Query;

public interface IShardedQueryExecutor
{
    Task<IReadOnlyList<TEntity>> ExecuteAsync<TEntity>(
        IQueryable<TEntity> query,
        CancellationToken cancellationToken = default)
        where TEntity : class;

    Task<TResult> ExecuteScalarAsync<TEntity, TResult>(
        IQueryable<TEntity> query,
        Func<IEnumerable<TResult>, TResult> aggregator,
        CancellationToken cancellationToken = default)
        where TEntity : class;

    /// <summary>
    /// Streams results across shards as IAsyncEnumerable<TEntity>.
    /// Per-shard producers are concurrent into a bounded Channel<T>.
    /// Default buffer = shardCount * 64; minimum 16.
    /// </summary>
    IAsyncEnumerable<TEntity> ExecuteStreamingAsync<TEntity>(
        IQueryable<TEntity> query,
        int? bufferSize = null,
        CancellationToken cancellationToken = default)
        where TEntity : class;
}

namespace Dtde.EntityFramework.Query;

public interface IShardContextFactory
{
    Task<DbContext> CreateContextAsync(
        IShardMetadata shard,
        CancellationToken cancellationToken = default);
}

namespace Dtde.EntityFramework.Query;

public interface IExpressionRewriter
{
    Expression Rewrite(Expression expression, IShardMetadata shard);
}

namespace Dtde.Abstractions.Metadata;

public interface IShardGroup
{
    string Name { get; }
    IReadOnlyList<IShardMetadata> Shards { get; }
    IShardMetadata? GetShard(string shardId);
}

public interface IShardGroupRegistry
{
    /// <summary>The conventional name of the default group: "__default__".</summary>
    public const string DefaultGroupName = "__default__";

    IShardGroup DefaultGroup { get; }
    IShardGroup? FindGroup(string name);
    IReadOnlyCollection<IShardGroup> Groups { get; }
}

namespace Dtde.Abstractions.Transactions;

public interface ITransactionLog
{
    Task RecordTransactionStartedAsync(
        string transactionId,
        CrossShardTransactionOptions options,
        CancellationToken cancellationToken = default);

    Task RecordParticipantEnlistedAsync(
        string transactionId,
        string participantId,
        CancellationToken cancellationToken = default);

    Task RecordParticipantPreparedAsync(
        string transactionId,
        string participantId,
        CancellationToken cancellationToken = default);

    Task RecordTransactionCommittedAsync(
        string transactionId,
        CancellationToken cancellationToken = default);

    Task RecordTransactionRolledBackAsync(
        string transactionId,
        CancellationToken cancellationToken = default);

    Task<IReadOnlyList<TransactionLogEntry>> GetInDoubtTransactionsAsync(
        CancellationToken cancellationToken = default);
}

namespace Dtde.EntityFramework.Update;

public interface IBulkInsertProvider
{
    bool CanHandle(DbContext context);

    Task<int> BulkInsertAsync<TEntity>(
        DbContext context,
        IReadOnlyCollection<TEntity> entities,
        CancellationToken cancellationToken = default)
        where TEntity : class;
}

public enum ShardStorageMode
{
    /// <summary>Multiple tables in the same database (per-shard tables).</summary>
    Tables,

    /// <summary>Separate database per shard.</summary>
    Databases,

    /// <summary>Pre-created tables; no migrations.</summary>
    Manual
}

public enum ShardTier
{
    /// <summary>Active data, fast storage.</summary>
    Hot,

    /// <summary>Less active data.</summary>
    Warm,

    /// <summary>Archived data, slow storage.</summary>
    Cold,

    /// <summary>Long-term storage.</summary>
    Archive
}

public enum DateShardInterval
{
    Year,
    Month,
    Quarter,
    Week
}

public enum VersioningMode
{
    /// <summary>Close old record, create new.</summary>
    SoftVersion,

    /// <summary>Copy to history table, update current.</summary>
    AuditTrail,

    /// <summary>Never update, always insert new.</summary>
    AppendOnly
}