Getting Started

Getting Started

Installation

Add the NuGet packages to your project:

dotnet add package DynamoDbLite
dotnet add package DynamoDbLite.DependencyInjection  # optional, for DI registration

Setup

Option 1: Dependency Injection

Register DynamoDbLite with your DI container using AddDynamoDbLite(). The client is registered as a singleton IAmazonDynamoDB.

From configuration (appsettings.json):

{
  "DynamoDbLiteOptions": {
    "ConnectionString": "Data Source=DynamoDbLite;Mode=Memory;Cache=Shared"
  }
}

using DynamoDbLite.DependencyInjection;

builder.Services.AddDynamoDbLite(builder.Configuration);

With explicit options:

builder.Services.AddDynamoDbLite(new DynamoDbLiteOptions(
    "Data Source=myapp.db"));

The AddDynamoDbLite method uses TryAddSingleton, so it won't overwrite an existing IAmazonDynamoDB registration.

Option 2: Direct Instantiation

using DynamoDbLite;

// In-memory (default)
var client = new DynamoDbClient();

// In-memory with explicit connection string
var client = new DynamoDbClient(new DynamoDbLiteOptions(
    "Data Source=DynamoDbLite;Mode=Memory;Cache=Shared"));

// File-based (persistent)
var client = new DynamoDbClient(new DynamoDbLiteOptions(
    "Data Source=myapp.db"));

DynamoDbClient implements IDisposable — dispose it when done, or let the DI container manage its lifetime.

Storage Modes

Mode	Connection String	Use Case
In-Memory	Data Source=MyDb;Mode=Memory;Cache=Shared	Unit tests, development
File-Based	Data Source=myapp.db	Persistent storage, mobile apps

The mode is auto-detected from the connection string: if it contains :memory: or Mode=Memory, an in-memory store is used; otherwise, a file-based store with WAL mode is created.

Minimal Working Example

using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using DynamoDbLite;

using var client = new DynamoDbClient();

// Create a table
await client.CreateTableAsync(new CreateTableRequest
{
    TableName = "Users",
    KeySchema =
    [
        new KeySchemaElement { AttributeName = "UserId", KeyType = KeyType.HASH }
    ],
    AttributeDefinitions =
    [
        new AttributeDefinition { AttributeName = "UserId", AttributeType = ScalarAttributeType.S }
    ],
    ProvisionedThroughput = new ProvisionedThroughput
    {
        ReadCapacityUnits = 5,
        WriteCapacityUnits = 5
    }
});

// Put an item
await client.PutItemAsync(new PutItemRequest
{
    TableName = "Users",
    Item = new Dictionary<string, AttributeValue>
    {
        ["UserId"] = new() { S = "user-123" },
        ["Name"] = new() { S = "Alice" },
        ["Age"] = new() { N = "30" }
    }
});

// Get the item
var response = await client.GetItemAsync(new GetItemRequest
{
    TableName = "Users",
    Key = new Dictionary<string, AttributeValue>
    {
        ["UserId"] = new() { S = "user-123" }
    }
});

Console.WriteLine(response.Item["Name"].S); // "Alice"

Configuration Reference

DynamoDbLiteOptions is a positional record with a single property:

Property	Type	Default	Description
ConnectionString	string	"Data Source=DynamoDbLite;Mode=Memory;Cache=Shared"	SQLite connection string

The connection string follows Microsoft.Data.Sqlite connection string format.

Next Steps

• Table Operations — creating and managing tables
• Item Operations — reading and writing data
• Secondary Indexes — adding GSIs and LSIs