OmniDataAccess.Core 1.2.0

OmniDataAccess.Core

OmniDataAccess.Core contains the shared types, configuration classes, annotations and helpers used across all OmniDataAccess packages. It is intentionally minimal — focused on the small, well-tested building blocks that the SQL and NoSQL providers depend on.

📦 Installation

dotnet add package OmniDataAccess.Core

🧩 What's in this package

• Result types: CacheResult<T>, DatabaseResult, PaginatedResult<T>, QueueResult<T>
• Message queue types: QueueMessage<T> (envelope returned by consume/read/claim), PendingMessageInfo (returned by GetPendingAsync)
• Procedure metadata: Procedure, ProcedureParameter (DDL — used by CreateProcedureAsync/CreateFunctionAsync), OmniParameter (execution — binds stored procedure calls, including OUTPUT/INPUT-OUTPUT parameters)
• Exceptions: DatabaseManagerException, DatabaseConnectionException, DatabaseConstraintViolationException, CacheManagerException, QueueManagerException, OmniConcurrencyException
• Configuration: DatabaseManagerOptions, CacheManagerOptions, MessageQueueOptions (extends CacheManagerOptions)
• Schema annotations: [Table], [Column], [PrimaryKey], [UniqueKey], [NotMapped], [NotInserted], [NotUpdated], [SoftDelete], [HasMany], [HasOne], [BelongsTo], [CacheKey], [CacheExpiry], [RowVersion], [Index]
• Core interfaces: IDatabaseManager
• ORM hooks: IOmniHooks — BeforeCreate/AfterCreate/BeforeUpdate/AfterUpdate/BeforeDelete/AfterDelete lifecycle callbacks, called automatically by OmniDB when an entity implements it
• Utilities: JsonHelpers, Loggers, Generators

Configuration

DatabaseManagerOptions

var opts = new DatabaseManagerOptions
{
    ConnectionString       = "Host=localhost;Database=mydb;Username=me;Password=secret",
    Database               = "mydb",
    ContextTimeout         = 30,    // command timeout in seconds
    ShowLogs               = true,  // enables connection/retry diagnostic messages; timing logs always emit
    VerifySsl              = false,
    UsePooling             = true,  // default; pooling is on by default for all providers
    MinPoolSize            = 0,
    MaxPoolSize            = 100,
    ConnectionIdleLifetime = 300,   // seconds

    // Transient-error retry (exponential backoff)
    RetryCount   = 3,   // attempts after the first failure
    RetryDelayMs = 200, // base delay; doubles each attempt → 200ms, 400ms, 800ms
};

// Query-log redaction: parameter values matching a keyword (case-insensitive substring,
// ignoring underscores) are logged as "***REDACTED***" instead of their real value.
// Pre-populated with: password, passwd, pwd, hash, secret, token, pin, ssn, apikey,
// creditcard, cvv, authorization.
opts.AddSensitiveParameterNames("otp", "nationalid"); // add domain-specific keywords
opts.SensitiveParameterNames.Remove("token");         // drop a default causing false positives

Transient errors that trigger a retry: network timeouts, connection resets, deadlocks, serialisation failures, CockroachDB restart-transaction, Azure SQL resource-pool throttling, and any IOException / SocketException (including the Npgsql "Exception while reading from stream" error).

CacheManagerOptions

var cacheOpts = new CacheManagerOptions
{
    ConnectionString = "localhost:6379",
    DatabaseIndex    = 0,
    CacheExpiry      = 3600, // seconds; -1 = no expiry
    ShowLogs         = true, // enables connection/reconnect diagnostic messages; timing logs always emit
};

MessageQueueOptions (extends CacheManagerOptions)

Configuration for IMessageQueueManager/IPubSubManager (implementations live in OmniDataAccess.NoSqlDatabases; this class is defined here since it's a config type, not a provider).

var queueOpts = new MessageQueueOptions("localhost:6379")
{
    ConsumerGroup       = "order-processors",
    MaxDeliveryAttempts = 5,             // informational only — the library does not auto-dead-letter
    ClaimMinIdleTime    = TimeSpan.FromSeconds(30),
    StreamMaxLength     = 10_000,        // Redis: XADD MAXLEN ~ trim. MemCache: caps each group's channel. null = unbounded
    MessageTtl          = TimeSpan.FromHours(24), // age-based trim (exact, not approximate). null = no age-based trim
    QueueTtl            = TimeSpan.FromHours(1),  // idle-queue expiration. null = never expires
    DefaultReadCount    = 10,
};

See the OmniDataAccess.NoSqlDatabases README for the full IMessageQueueManager/IPubSubManager API and every MessageQueueOptions field.

Result types

// CacheResult<T> — returned by all ICacheManager read operations
CacheResult<User> result = await cache.GetStringAsync<User>("user:1");
if (result.IsSuccess)
    Console.WriteLine(result.Data?.Name);
else
    Console.WriteLine(result.FailureReason); // CacheMiss | FailedConnection | InternalError

// DatabaseResult — returned by ExecuteAsync
DatabaseResult r = await db.ExecuteAsync("DELETE FROM sessions WHERE expired = true");
Console.WriteLine($"{r.RowsAffected} rows, took {r.ExecutionTime.TotalMilliseconds:F0}ms");

// PaginatedResult<T> — returned by FindPagedAsync
PaginatedResult<IEnumerable<User>> page = await db.FindPagedAsync<User>("SELECT * FROM users", page: 1, limit: 20);
Console.WriteLine($"Page {page.Page}, total {page.TotalCount}, has next: {page.HasNextPage}");
foreach (var u in page.Data) Console.WriteLine(u.Name);

// QueueResult<T> — returned by IMessageQueueManager read operations (ConsumeAsync, ReadAsync, ...)
QueueResult<QueueMessage<Order>> msg = await queue.ConsumeAsync<Order>("orders");
if (msg.IsSuccess)
    Console.WriteLine(msg.Data?.Data);
else
    Console.WriteLine(msg.FailureReason); // QueueEmpty | QueueNotFound | FailedConnection | InternalError | ...

Stored procedure OUTPUT parameters (OmniParameter)

Anonymous-object parameters (new { id = 1 }) are input-only — Dapper solves this with DynamicParameters; OmniDataAccess uses OmniParameter, which carries Direction/DbType/Size so OUTPUT and INPUT-OUTPUT values can be read back after execution via ISqlDatabaseManager.ExecuteNonQueryAsync(string procedureName, IEnumerable<OmniParameter> parameters, ...).

var parameters = new[]
{
    OmniParameter.In("SOURCE_TRANS_ID", sourceTransId),
    OmniParameter.In("AMOUNT_REQUESTED", amount),

    OmniParameter.Out("RESULT_1SUCCESS_0FAILED", DbType.Int32),
    OmniParameter.Out("RESULT_MESSAGE", DbType.String, size: -1), // -1 = MAX
    OmniParameter.InOut("RUNNING_TOTAL", currentTotal, DbType.Decimal),
};

DatabaseResult result = await db.ExecuteNonQueryAsync("dbo.MOBWEB_GET_NORMAL_LOAN_APPL", parameters);

bool success   = result.GetOutput<int>("RESULT_1SUCCESS_0FAILED") == 1;
string message = result.GetOutput<string>("RESULT_MESSAGE") ?? "";

DatabaseResult.OutputParameters holds the raw values keyed by parameter name (no provider prefix); GetOutput<T> converts and returns default when the parameter is absent or NULL.

Exceptions

try
{
    await db.ExecuteAsync("INSERT INTO users (email) VALUES (@email)", new { email });
}
catch (DatabaseConstraintViolationException ex)
{
    // Unique/FK/check/not-null violation — derives from DatabaseManagerException,
    // so existing `catch (DatabaseManagerException)` sites still catch it too.
    Console.WriteLine($"constraint violated: {ex.ProviderErrorCode}");
}
catch (DatabaseManagerException ex)
{
    Console.WriteLine($"{ex.ErrorCode}: {ex.Message}"); // ErrorCode: Unknown | Transient | Timeout | ConstraintViolation | ConnectionFailure
    Console.WriteLine(ex.InnerException);               // original provider exception is always preserved
}

Every exception's inner-exception constructor preserves the original provider exception (stack trace included) — nothing is swallowed into a message string.

Schema annotations

[Table("users")]
[SoftDelete("deleted_at")]
[CacheKey("user")]
[CacheExpiry(hours: 1)]
public class User
{
    [PrimaryKey("id", autoGenerate: true)]
    public int Id { get; set; }

    [Column("name")]
    public string Name { get; set; } = "";

    [Column("email")]
    [UniqueKey]
    public string Email { get; set; } = "";

    [Column("created_at")]
    [NotUpdated]           // excluded from UPDATE SET clauses
    public DateTime CreatedAt { get; set; }

    [Column("version")]
    [NotInserted]          // excluded from INSERT (managed by DB trigger/default)
    public int Version { get; set; }

    [RowVersion]           // optimistic concurrency — SaveAsync increments and checks this
    public long RowVersion { get; set; }

    [Column("deleted_at")]
    public DateTime? DeletedAt { get; set; }

    [NotMapped]            // never read from or written to the DB
    public string Label => $"{Name} <{Email}>";
}

// [Index] — repeatable, defines DB indexes created by EnsureCreatedAsync
[Table("posts")]
[Index("idx_posts_author", "author_id")]
[Index("idx_posts_slug", "slug", unique: true)]
public class Post
{
    [PrimaryKey]           // no-arg form — uses the property name ("Id") as column name
    public Guid Id { get; set; }

    [Column(Name = "author_id")]   // property-syntax alternative to [Column("author_id")]
    public int AuthorId { get; set; }

    [Column("slug")]
    public string Slug { get; set; } = "";
}

Where to look in the codebase