Compartilhar via

Integração do SQLite do Kit de Ferramentas da Comunidade .NET.NET Aspire

  • Artigo

Inclui: integração de hospedagem e integração Client

Nota

Essa integração faz parte do do.NET.NET Aspire Community Toolkit e não é oficialmente compatível com a equipe de .NET.NET Aspire.

SQLite é um mecanismo de banco de dados SQL leve, sem servidor e independente que é amplamente usado para armazenamento de dados local em aplicativos. A integração .NET Aspire SQLite fornece uma maneira de usar bancos de dados SQLite em seus aplicativos .NET Aspire e acessá-los por meio do cliente Microsoft.Data.Sqlite.

Integração de hospedagem

A integração de hospedagem do SQLite modela um banco de dados SQLite como o tipo SQLiteResource e criará o arquivo de banco de dados no local especificado. Para acessar esses tipos e APIs que permitem adicionar o 📦 CommunityToolkit.Aspire. Hosting.SQLite pacote NuGet no do host do aplicativo projeto.

dotnet add package CommunityToolkit.Aspire.Hosting.SQLite

Para obter mais informações, consulte dotnet add package ou Gerencie dependências de pacotes em aplicativos .NET.

Adicionar recurso SQLite

No projeto de host do aplicativo, registre e consuma a integração do SQLite usando o método de extensão AddSQLite para adicionar o banco de dados SQLite ao construtor de aplicativos.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando .NET.NET Aspire adiciona um banco de dados SQLite ao host do aplicativo, conforme mostrado no exemplo anterior, ele cria um novo arquivo de banco de dados SQLite no diretório temp dos usuários.

Como alternativa, se você quiser especificar um local personalizado para o arquivo de banco de dados SQLite, forneça os argumentos relevantes para o método AddSqlite.

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

Adicionar recurso SQLiteWeb

Ao adicionar o recurso SQLite, você também pode adicionar o recurso SQLiteWeb, que fornece uma interface da Web para interagir com o banco de dados SQLite. Para fazer isso, use o método de extensão WithSqliteWeb.

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

Esse código adiciona um contêiner com base em ghcr.io/coleifer/sqlite-web ao host do aplicativo, que fornece uma interface da Web para interagir com o banco de dados SQLite ao qual ele está conectado. Cada instância do SQLiteWeb está conectada a um único banco de dados SQLite, o que significa que, se você adicionar várias instâncias do SQLiteWeb, haverá vários contêineres SQLiteWeb.

Adicionando extensões do SQLite

O SQLite dá suporte a extensões que podem ser adicionadas ao banco de dados SQLite. As extensões podem ser fornecidas por meio de um pacote NuGet ou por meio de um local no disco. Use os métodos de extensão WithNuGetExtension ou WithLocalExtension para adicionar extensões ao banco de dados SQLite.

Nota

O suporte a extensões SQLite é considerado experimental e produz um aviso CTASPIRE002.

integração Client

Para começar a usar a integração do cliente .NET.NET Aspire SQLite, instale o pacote NuGet 📦 CommunityToolkit.Aspire.Microsoft.Data.Sqlite no projeto consumidor, ou seja, o projeto do aplicativo que utiliza o cliente SQLite. A integração do cliente SQLite registra uma instância de SqliteConnection que você pode usar para interagir com o SQLite.

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

Adicionar cliente Sqlite

No arquivo Program.cs do projeto que consome o cliente, invoque o método de extensão Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection em qualquer IHostApplicationBuilder para registrar um SqliteConnection para uso através do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddSqliteConnection(connectionName: "sqlite");

Ponta

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso SQLite no projeto de host do aplicativo. Para obter mais informações, consulte Adicionarde recursos do SQLite.

Depois de adicionar SqliteConnection ao construtor, você pode obter a instância de SqliteConnection usando a injeção de dependência. Por exemplo, para recuperar o objeto de conexão de um serviço de exemplo, defina-o como um parâmetro de construtor e verifique se a classe ExampleService está registrada com o contêiner de injeção de dependência:

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

Para obter mais informações sobre injeção de dependência, consulte .NETinjeção de dependência.

Adicionar cliente Sqlite com chave

Pode haver situações em que você deseja registrar várias instâncias de SqliteConnection com nomes de conexão diferentes. Para registrar clientes sqlite com chave, chame o método Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddKeyedSqliteConnection:

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

Em seguida, você pode recuperar as instâncias de SqliteConnection usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Configuração

A integração do cliente SQLite fornece várias abordagens de configuração e opções para atender aos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar o método Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection:

builder.AddSqliteConnection("sqlite");

Em seguida, a cadeia de conexão será recuperada da seção de configuração ConnectionStrings.

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

Usar provedores de configuração

A integração do cliente SQLite dá suporte a Microsoft.Extensions.Configuration. Ele carrega a Microsoft.Extensions.Hosting.SqliteConnectionSettings do appsettings.json ou de outros provedores de configuração usando a chave Aspire:Sqlite:Client. Exemplo appsettings.json que configura algumas das opções:

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