Set up SQLite in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire SQLite Hosting integration. It enumerates the AppHost APIs that you use to model a SQLite database resource in your AppHost project.

If you’re new to the SQLite integration, start with the Get started with SQLite integrations guide. For how consuming apps read the connection information this page exposes, see Connect to SQLite.

Note

The SQLite hosting integration is part of the .NET Aspire Community Toolkit and is not included in the core Aspire SDK. The TypeScript AppHost does not have an addSqlite API. To reference a SQLite file from a TypeScript AppHost, use builder.addConnectionString(...) with a parameter instead.

Installation

To start building an Aspire app that uses SQLite, install the 📦 CommunityToolkit.Aspire.Hosting.SQLite NuGet package in your AppHost project:

Terminal

aspire add sqlite

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.SQLite@*

XML — AppHost.csproj

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

Add SQLite resource

Once you’ve installed the hosting integration in your AppHost project, you can add a SQLite resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite");

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

// After adding all resources, run the app...

1. When Aspire adds a SQLite resource, as shown in the preceding example, it creates the database file in the user’s temporary directory. No container is started because SQLite is an embedded, file-based database.

2. The AppHost reference call configures a connection in the consuming project named after the referenced SQLite resource, such as sqlite in the preceding example.

Note

When you reference a SQLite resource from the AppHost, Aspire makes the database file path available to the consuming project as a DATASOURCE environment variable. For a complete list of these properties and per-language connection examples, see Connect to SQLite.

Add SQLite resource with custom database file path

By default, Aspire creates the SQLite database file in the user’s temporary directory. To specify a custom location, provide the directory path and file name as arguments to AddSqlite:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

The preceding code creates the SQLite database file at C:\Database\Location\my-database.db. The file is created if it doesn’t already exist.

Add SQLiteWeb resource

To add a browser-based management UI alongside your SQLite database, use the WithSqliteWeb extension method:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite")
    .WithSqliteWeb();

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

// After adding all resources, run the app...

This adds a container based on ghcr.io/coleifer/sqlite-web connected to the same database file. Each WithSqliteWeb call creates one container per database. When you run the solution, the Aspire dashboard displays the SQLiteWeb resource with an endpoint — select it to open the SQLiteWeb UI in a new browser tab.

Add SQLite extensions

SQLite supports loadable extensions that can be provided via a NuGet package or from a local file on disk. Use either WithNuGetExtension or WithLocalExtension:

C# — AppHost.cs (NuGet extension)

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite")
    .WithNuGetExtension("SQLitePCLRaw.lib.e_sqlite3");

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

// After adding all resources, run the app...

C# — AppHost.cs (Local extension)

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite")
    .WithLocalExtension("C:\\Extensions\\my-extension.dll");

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

// After adding all resources, run the app...

Note

SQLite extension support is considered experimental and produces a CTASPIRE002 diagnostic warning.

Connection properties

For the full reference of SQLite connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to SQLite.

Hosting integration health checks

The SQLite hosting integration does not register a health check because SQLite is an embedded, file-based database with no server process to poll. Health checks are available in the C# client integration.