SQLite Client integration reference

To get started with the Aspire SQLite integrations, follow the Get started with SQLite integrations guide.

This article includes full details about the Aspire SQLite Client integration, which allows you to connect to and interact with SQLite databases from your Aspire consuming projects.

To get started with the 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

#:package CommunityToolkit.Aspire.Microsoft.Data.Sqlite@*

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

In the Program.cs file of your client-consuming project, call the AddSqliteConnection extension method 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:

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

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

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

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

Then you can retrieve the SqliteConnection instances using dependency injection:

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

For more information on keyed services, see .NET dependency injection: Keyed services.

When you use the WithReference method to pass a SQLite database resource from the AppHost project to a consuming client project, Aspire exposes the data source as an environment variable with a standardized naming convention:

The SQLite client integration provides multiple options to configure the connection based on the requirements and conventions of your project.

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling the 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"
  }
}

For more information on how to format this connection string, see Microsoft.Data.Sqlite connection strings.

The SQLite client integration supports Microsoft.Extensions.Configuration. It loads the settings from configuration 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
      }
    }
  }
}

You can also pass the Action<SqliteConnectionSettings> delegate to set up some or all the options inline:

builder.AddSqliteConnection(
    "sqlite",
    static settings => settings.DisableHealthCheck = true);

By default, Aspire integrations enable health checks for all services. For more information, see Aspire integrations overview.

The Aspire SQLite integration:

• Adds the health check when SqliteConnectionSettings.DisableHealthCheck is false, which attempts to open a connection to the SQLite database.
• Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.

Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

The Aspire SQLite integration uses standard .NET logging mechanisms for database operations.

The Aspire SQLite integration will emit tracing activities for database operations using OpenTelemetry when configured.

The Aspire SQLite integration currently has limited metrics support compared to other database integrations due to the nature of SQLite as an embedded database engine.