.NET Aspire Community Toolkit SQLite Entity Framework 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.EntityFrameworkCore.Sqlite Entity Framework support package.

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 EF client integration, install the 📦 CommunityToolkit.Aspire.Microsoft.EntityFrameworkCore.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.EntityFrameworkCore.Sqlite

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

Add Sqlite client

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

builder.AddSqliteDbContext<YourDbContext>(connectionName: "sqlite");

After adding YourDbContext to the builder, you can get the YourDbContext instance using dependency injection. For example, to retrieve your data source 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(YourDbContext context)
{
    // Use context...
}

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

Enrich a SQLite database context

You may prefer to use the standard Entity Framework method to obtain the database contextand add it to the dependency injection container:

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("sqlite")
        ?? throw new InvalidOperationException("Connection string 'sqlite' not found.")));

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.AspireEFSqliteExtensions.AddSqliteDbContext method:

builder.AddSqliteDbContext<YourDbContext>("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:EntityFrameworkCore:Sqlite key. Example _appsettings.json that configures some of the options:

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