.NET .NET Aspire Community Toolkit SQLite 集成

2025-05-20

包含： - Client 集成

注意事项

此集成是 .NET.NET Aspire 社区工具包的一部分，不受 .NET.NET Aspire 团队正式支持。

SQLite 是一种轻型、无服务器、独立 SQL 数据库引擎，通常用于应用程序中的本地数据存储。 .NET Aspire SQLite 集成提供了一种在 .NET Aspire 应用程序中使用 SQLite 数据库的方法，并通过 Microsoft.Data.Sqlite 客户端访问它们。

托管集成

SQLite 托管集成将 SQLite 数据库建模为 SQLiteResource 类型，并将在指定位置创建数据库文件。若要访问这些类型和 API，在 📦 项目中，允许添加 Aspire CommunityToolkit。Hosting.SQLite NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package CommunityToolkit.Aspire.Hosting.SQLite

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

有关详细信息，请参阅 dotnet add package 或管理在 .NET 应用程序中的包依赖性。

添加 SQLite 资源

在应用主机项目中，使用 AddSQLite 扩展方法注册和使用 SQLite 集成，以将 SQLite 数据库添加到应用程序生成器。

var builder = DistributedApplication.CreateBuilder(args);

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

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

当 .NET.NET Aspire 将 SQLite 数据库添加到应用主机时，如前面的示例所示，它会在用户临时目录中创建新的 SQLite 数据库文件。

或者，如果要为 SQLite 数据库文件指定自定义位置，请向 AddSqlite 方法提供相关参数。

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

添加 SQLiteWeb 资源

添加 SQLite 资源时，还可以添加 SQLiteWeb 资源，该资源提供 Web 界面来与 SQLite 数据库交互。为此，请使用 WithSqliteWeb 扩展方法。

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

此代码将基于 ghcr.io/coleifer/sqlite-web 的容器添加到应用主机，该主机提供 Web 界面来与连接到的 SQLite 数据库进行交互。每个 SQLiteWeb 实例都连接到单个 SQLite 数据库，这意味着，如果添加多个 SQLiteWeb 实例，将有多个 SQLiteWeb 容器。

添加 SQLite 扩展

SQLite 支持可添加到 SQLite 数据库的扩展。可以通过 NuGet 包或通过磁盘上的位置提供扩展。使用 WithNuGetExtension 或 WithLocalExtension 扩展方法将扩展添加到 SQLite 数据库。

注意事项

SQLite 扩展支持被视为试验性，并生成 CTASPIRE002 警告。

Client 集成

若要开始使用 .NET.NET Aspire SQLite 客户端集成，请在使用 SQLite 客户端的应用程序项目中安装 📦 CommunityToolkit.AspireMicrosoft.Data.Sqlite NuGet 包。客户端集成会注册一个 SqliteConnection 实例供您与 SQLite 进行交互。

.NETCLI（命令行界面）
包引用

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

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

添加 Sqlite 客户端

在客户端使用项目的 Program.cs 文件中，对任何 Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection 调用 IHostApplicationBuilder 扩展方法，以注册 SqliteConnection，以便通过依赖项注入容器使用。该方法采用连接名称参数。

builder.AddSqliteConnection(connectionName: "sqlite");

提示

connectionName 参数必须与在应用主机项目中添加 SQLite 资源时使用的名称匹配。有关详细信息，请参阅添加 SQLite 资源。

将 SqliteConnection 添加到生成器后，可以使用依赖项注入获取 SqliteConnection 实例。例如，若要从示例服务检索连接对象，请将其定义为构造函数参数，并确保 ExampleService 类注册到依赖项注入容器：

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

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加键化 Sqlite 客户端

在某些情况下，可能需要使用不同的连接名称注册多个 SqliteConnection 实例。若要注册密钥 Sqlite 客户端，请调用 Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddKeyedSqliteConnection 方法：

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

然后，可以使用依赖项注入检索 SqliteConnection 实例。例如，若要从示例服务检索连接，

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

配置

SQLite 客户端集成提供了多种配置方法和选项，以满足项目的要求和约定。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection 方法时提供连接字符串的名称：

builder.AddSqliteConnection("sqlite");

然后，将从 ConnectionStrings 配置部分检索连接字符串。

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

使用配置提供程序

SQLite 客户端集成支持 Microsoft.Extensions.Configuration。它使用 Microsoft.Extensions.Hosting.SqliteConnectionSettings 键从 appsettings.json 或其他配置提供程序加载 Aspire:Sqlite:Client。配置某些选项的示例 appsettings.json：

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

通过