.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.EntityFrameworkCore.Sqlite Entity Framework 支持包访问它们。

托管集成

SQLite 托管集成将 SQLite 数据库建模为 SQLiteResource 类型，并将在指定位置创建数据库文件。为了访问这些类型和 API，可以在应用主机项目中添加 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 EF 客户端的集成，请在使用 SQLite 客户端的应用程序项目中安装 📦 CommunityToolkit.Aspire.Microsoft.EntityFrameworkCore.Sqlite NuGet 包。 SQLite 客户端集成注册了一个可用于与 SQLite 交互的 SqliteConnection 实例。

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

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

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

添加 Sqlite 客户端

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

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

提示

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

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

public class ExampleService(YourDbContext context)
{
    // Use context...
}

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

扩充 SQLite 数据库上下文

你可能更喜欢使用标准 Entity Framework 方法获取数据库上下文并将其添加到依赖项注入容器：

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

注意

传递给 GetConnectionString 方法的连接字符串名称必须与在应用主机项目中添加 SQLite 资源时使用的名称匹配。有关详细信息，请参阅添加 SQLite 资源。

配置

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

使用连接字符串

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

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

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

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

使用配置提供程序

SQLite 客户端集成支持 Microsoft.Extensions.Configuration。它通过使用 Microsoft.Extensions.Hosting.SqliteConnectionSettings 键从 appsettings.json 或其他配置提供器加载 Aspire:Sqlite:EntityFrameworkCore:Sqlite。示例 _appsettings.json，用于配置某些选项：

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

通过