DI and Configuration

DI and Configuration

AddDynamoDbLite registers IAmazonDynamoDB as a singleton built from a validated SQLite connection string. This page covers the registration surface, the builder, the options record, and the exception type — everything that sits between your composition root and a working DynamoDbClient.

Overview

The DI surface lives in the DynamoDbLite namespace inside the main package — there is no separate DynamoDbLite.DependencyInjection package.

• AddDynamoDbLite — the only registration extension.
• DynamoDbLiteOptionsBuilder — fluent builder with up-front validation.
• DynamoDbLiteOptions — the configuration record.
• DynamoDbLiteConfigurationException — thrown on misconfiguration.

AddDynamoDbLite

public static IServiceCollection AddDynamoDbLite(
    this IServiceCollection services,
    Action<DynamoDbLiteOptionsBuilder> configure)

One overload. configure receives a fresh builder; the extension calls Build immediately and registers the resulting DynamoDbClient as a singleton IAmazonDynamoDB via TryAddSingleton. Existing registrations are preserved.

Validation is eager. If configure does not call WithConnectionString, or the supplied connection string is invalid, Build throws DynamoDbLiteConfigurationException synchronously — at AddDynamoDbLite time, not at first resolution. This surfaces misconfiguration during host startup rather than during the first request.

using DynamoDbLite;

builder.Services.AddDynamoDbLite(o =>
    o.WithConnectionString("Data Source=myapp.db"));

Builder surface

WithConnectionString

public DynamoDbLiteOptionsBuilder WithConnectionString(string connectionString)

Validates connectionString and stores it on the builder. Throws DynamoDbLiteConfigurationException when the input is null, empty, whitespace, or fails to parse as a SQLite connection string.

WithWriteAheadLog

public DynamoDbLiteOptionsBuilder WithWriteAheadLog()

Enables SQLite Write-Ahead Logging on file-backed stores. Off by default — call this to opt in. WAL lets readers proceed while a writer holds the write lock, which materially improves reader-writer concurrency on file-backed stores.

Has no effect on in-memory stores. SQLite does not support WAL for :memory: databases and silently falls back to the memory journal mode.

WAL is persistent on the database file once enabled. Disabling later requires an explicit PRAGMA journal_mode=DELETE outside this library.

Build

Build is internal — AddDynamoDbLite is the only caller. If WithConnectionString was not called before Build, it throws DynamoDbLiteConfigurationException with the message:

Connection string was not configured. Call WithConnectionString before Build.

Options surface

public sealed record DynamoDbLiteOptions(string ConnectionString, bool UseWriteAheadLog = false);

A positional record with one required parameter and one optional flag.

• ConnectionString — required. No default; consumers opt in to either an in-memory or file-based store. See Getting Started for the connection string forms and the in-memory naming foot-gun.
• UseWriteAheadLog — optional, defaults to false. Enables SQLite Write-Ahead Logging on file-backed stores; no effect on in-memory stores. The builder equivalent is WithWriteAheadLog — same contract, including the note that WAL is persistent on the file once enabled.

Connection string normalization

The connection string follows Microsoft.Data.Sqlite connection string format but is normalized before use: Pooling=true, Mode=ReadWriteCreate, and ForeignKeys=true are forced. Specifying these in your connection string has no effect.

DynamoDbLiteConfigurationException

public sealed class DynamoDbLiteConfigurationException : Exception

Thrown by WithConnectionString and Build on the conditions documented above. Carries the standard Exception shape — message, inner exception when wrapping a SqliteConnectionStringBuilder parse failure, no extra state.

Catch this type at composition-root level to surface configuration problems with a clear message; do not catch it at request time, since misconfiguration has already crashed startup.

Direct instantiation

DynamoDbClient accepts the same DynamoDbLiteOptions record without DI:

using var client = new DynamoDbClient(new DynamoDbLiteOptions(
    "Data Source=myapp.db"));

See Getting Started for the full direct-instantiation walkthrough including in-memory naming.

IConfiguration

IConfiguration-based registration is not implemented today. Bind your config to a string and pass it through WithConnectionString:

builder.Services.AddDynamoDbLite(o =>
    o.WithConnectionString(builder.Configuration["DynamoDbLite:ConnectionString"]
        ?? throw new InvalidOperationException("DynamoDbLite:ConnectionString missing")));

Next steps

• Getting Started — installation and the full setup walkthrough
• FAQ — connection string and configuration gotchas
• API Parity — what IAmazonDynamoDB surface is supported