.NET Aspire Community Toolkit SQLite integration
Includes:
Hosting integration and
Client integration
Note
This integration is part of the .NET Aspire Community Toolkit and isn't officially supported by the .NET Aspire team.
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
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.
Note
The SQLite extensions support is considered experimental and produces a CTASPIRE002
warning.
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
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");
Tip
The connectionName
parameter must match the name used when adding the SQLite resource in the app host project. For more information, see Add SQLite resource.
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
}
}
}
}
.NET Aspire