.NET .NET Aspire Community Toolkit: integrazione con SQLite

include: l'integrazione dell'hosting e l'integrazione di Client

SQLite è un motore di database SQL leggero, serverless e autonomo ampiamente usato per l'archiviazione dei dati locali nelle applicazioni. L'integrazione .NET Aspire SQLite consente di usare i database SQLite all'interno delle applicazioni .NET Aspire e di accedervi tramite il client Microsoft.Data.Sqlite.

Integrazione dell'hosting

L'integrazione dell'hosting SQLite modella un database SQLite come tipo SQLiteResource e creerà il file di database nel percorso specificato. Per accedere a questi tipi e API che consentono di aggiungere il 📦 CommunityToolkit.Aspire. Hosting.SQLite pacchetto NuGet nel progetto host dell'app .

dotnet add package CommunityToolkit.Aspire.Hosting.SQLite

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

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Aggiungere una risorsa SQLite

Nel progetto host dell'app, registrare e usare l'integrazione di SQLite usando il metodo di estensione AddSQLite per aggiungere il database SQLite al costruttore dell'applicazione.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando .NET.NET Aspire aggiunge un database SQLite all'host dell'app, come illustrato nell'esempio precedente, crea un nuovo file di database SQLite nella directory temporanea degli utenti.

In alternativa, se si vuole specificare un percorso personalizzato per il file di database SQLite, specificare gli argomenti pertinenti per il metodo AddSqlite.

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

Aggiungere una risorsa SQLiteWeb

Quando si aggiunge la risorsa SQLite, è anche possibile aggiungere la risorsa SQLiteWeb, che fornisce un'interfaccia Web per interagire con il database SQLite. A tale scopo, usare il metodo di estensione WithSqliteWeb.

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

Questo codice aggiunge un contenitore basato su ghcr.io/coleifer/sqlite-web all'host dell'app, che fornisce un'interfaccia Web a cui interagire con il database SQLite a cui è connesso. Ogni istanza di SQLiteWeb è connessa a un singolo database SQLite, ovvero se si aggiungono più istanze SQLiteWeb, saranno presenti più contenitori SQLiteWeb.

Aggiunta di estensioni SQLite

SQLite supporta estensioni che possono essere aggiunte al database SQLite. Le estensioni possono essere fornite tramite un pacchetto NuGet o attraverso un percorso sul disco. Usare i metodi di estensione WithNuGetExtension o WithLocalExtension per aggiungere estensioni al database SQLite.

integrazione Client

Per iniziare con l'integrazione del client .NET.NET Aspire SQLite, installare il pacchetto NuGet 📦 CommunityToolkit.Aspire.Microsoft.Data.Sqlite nel progetto client-consumatore, cioè il progetto per l'applicazione che utilizza il client SQLite. L'integrazione client SQLite registra un'istanza di SqliteConnection che è possibile usare per interagire con SQLite.

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

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

Aggiungere il client Sqlite

Nel file Program.cs del progetto che usa il client chiamare il metodo di estensione Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection in qualsiasi IHostApplicationBuilder per registrare un SqliteConnection da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddSqliteConnection(connectionName: "sqlite");

Dopo aver aggiunto SqliteConnection al generatore, è possibile ottenere l'istanza di SqliteConnection tramite l'iniezione delle dipendenze. Ad esempio, per recuperare l'oggetto di connessione da un servizio esemplare, definirlo in quanto parametro del costruttore e assicurarsi che la classe ExampleService sia registrata con il contenitore di iniezione delle dipendenze.

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

Per altre informazioni sull'inserimento delle dipendenze, vedere .NET inserimento delle dipendenze.

Aggiungere un client Sqlite con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di SqliteConnection con nomi di connessione diversi. Per registrare i client Sqlite con chiave, chiamare il metodo Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddKeyedSqliteConnection:

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

È quindi possibile recuperare le istanze di SqliteConnection usando l'inserimento delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Configurazione

L'integrazione client SQLite offre più approcci di configurazione e opzioni per soddisfare i requisiti e le convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama il metodo Microsoft.Extensions.Hosting.AspireSqliteExtensions.AddSqliteConnection:

builder.AddSqliteConnection("sqlite");

La stringa di connessione verrà quindi recuperata dalla sezione di configurazione ConnectionStrings.

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

Usare i provider di configurazione

L'integrazione client SQLite supporta Microsoft.Extensions.Configuration. Carica il Microsoft.Extensions.Hosting.SqliteConnectionSettings dal appsettings.json o da altri provider di configurazione usando la chiave Aspire:Sqlite:Client. Esempio appsettings.json che configura alcune delle opzioni:

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