.NET Aspire Community Toolkit SQLite integration

Includes: Hosting integration and Client integration

SQLite is a lightweight, serverless, self-contained SQL database engine that is widely used for local data storage in applications. The .NET Aspire SQLite integration provides a way to use SQLite databases within your .NET Aspire applications, and access them via the Microsoft.Data.Sqlite client.

Hosting integration

The SQLite hosting integration models a SQLite database as the SQLiteResource type and will create the database file in the specified location. To access these types and APIs that allow you to add the 📦 CommunityToolkit.Aspire.Hosting.SQLite NuGet package in the app host project.

dotnet add package CommunityToolkit.Aspire.Hosting.SQLite

<PackageReference Include="CommunityToolkit.Aspire.Hosting.SQLite"
                  Version="*" />

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add SQLite resource

In the app host project, register and consume the SQLite integration using the AddSQLite extension method to add the SQLite database to the application builder.

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSQLite("my-database");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(sqlite);

When .NET Aspire adds a SQLite database to the app host, as shown in the preceding example, it creates a new SQLite database file in the users temp directory.

Alternatively, if you want to specify a custom location for the SQLite database file, provide the relevant arguments to the AddSqlite method.

var sqlite = builder.AddSQLite("my-database", "C:\\Database\\Location", "my-database.db");

Add SQLiteWeb resource

When adding the SQLite resource, you can also add the SQLiteWeb resource, which provides a web interface to interact with the SQLite database. To do this, use the WithSqliteWeb extension method.

var sqlite = builder.AddSQLite("my-database")
                    .WithSqliteWeb();

This code adds a container based on ghcr.io/coleifer/sqlite-web to the app host, which provides a web interface to interact with the SQLite database it is connected to. Each SQLiteWeb instance is connected to a single SQLite database, meaning that if you add multiple SQLiteWeb instances, there will be multiple SQLiteWeb containers.

Adding SQLite extensions

SQLite supports extensions that can be added to the SQLite database. Extensions can either be provided via a NuGet package, or via a location on disk. Use either the WithNuGetExtension or WithLocalExtension extension methods to add extensions to the SQLite database.

Client integration

To get started with the .NET Aspire SQLite client integration, install the 📦 CommunityToolkit.Aspire.Microsoft.Data.Sqlite NuGet package in the client-consuming project, that is, the project for the application that uses the SQLite client. The SQLite client integration registers a SqliteConnection instance that you can use to interact with SQLite.

dotnet add package CommunityToolkit.Aspire.Microsoft.Data.Sqlite

<PackageReference Include="CommunityToolkit.Aspire.Microsoft.Data.Sqlite" Version="*" />

Add Sqlite client

In the Program.cs file of your client-consuming project, call the Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection extension method on any IHostApplicationBuilder to register a SqliteConnection for use via the dependency injection container. The method takes a connection name parameter.

builder.AddSqliteConnection(connectionName: "sqlite");

After adding SqliteConnection to the builder, you can get the SqliteConnection instance using dependency injection. For example, to retrieve your connection object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

public class ExampleService(SqliteConnection connection)
{
    // Use connection...
}

For more information on dependency injection, see .NET dependency injection.

Add keyed Sqlite client

There might be situations where you want to register multiple SqliteConnection instances with different connection names. To register keyed Sqlite clients, call the Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddKeyedSqliteConnection method:

builder.AddKeyedSqliteConnection(name: "chat");
builder.AddKeyedSqliteConnection(name: "queue");

Then you can retrieve the SqliteConnection instances using dependency injection. For example, to retrieve the connection from an example service:

public class ExampleService(
    [FromKeyedServices("chat")] SqliteConnection chatConnection,
    [FromKeyedServices("queue")] SqliteConnection queueConnection)
{
    // Use connections...
}

Configuration

The SQLite client integration provides multiple configuration approaches and options to meet the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling the Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection method:

builder.AddSqliteConnection("sqlite");

Then the connection string will be retrieved from the ConnectionStrings configuration section.

{
  "ConnectionStrings": {
    "sqlite": "Data Source=C:\\Database\\Location\\my-database.db"
  }
}

Use configuration providers

The SQLite client integration supports Microsoft.Extensions.Configuration. It loads the Microsoft.Extensions.Hosting.SqliteConnectionSettings from the appsettings.json or other configuration providers by using the Aspire:Sqlite:Client key. Example appsettings.json that configures some of the options:

{
  "Aspire": {
    "Sqlite": {
      "Client": {
        "ConnectionString": "Data Source=C:\\Database\\Location\\my-database.db",
        "DisableHealthCheck": true
      }
    }
  }
}