integrazione di .NET AspirePostgreSQL

Include:integrazione dell'hosting e integrazione Client

PostgreSQL è un potente sistema di database relazionale a oggetti open source con molti anni di sviluppo attivo che lo ha guadagnato una forte reputazione di affidabilità, affidabilità delle funzionalità e prestazioni. L'integrazione .NET AspirePostgreSQL consente di connettersi ai database di PostgreSQL esistenti o di creare nuove istanze da .NET con l'immagine del contenitore docker.io/library/postgres.

Integrazione dell'hosting

Il PostgreSQL che ospita l'integrazione modella un PostgreSQLserver come tipo di PostgresServerResource. Per accedere a questo tipo e alle API che permettono di aggiungerlo al 📦Aspire.Hosting.PostgreSQL pacchetto NuGet nel progetto host dell'app .

dotnet add package Aspire.Hosting.PostgreSQL

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

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere la risorsa PostgreSQLserver

Nel progetto host dell'app chiamare AddPostgres nell'istanza di builder per aggiungere una risorsa PostgreSQLserver e quindi chiamare AddDatabase nell'istanza di postgres per aggiungere una risorsa di database, come illustrato nell'esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

Quando .NET.NET Aspire aggiunge un'immagine contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/library/postgres, crea una nuova istanza PostgreSQLserver nel computer locale. Un riferimento al PostgreSQLserver e all'istanza del database PostgreSQL (la variabile postgresdb) vengono usati per aggiungere una dipendenza alla ExampleProject. La risorsa PostgreSQLserver include le credenziali predefinite con un username di "postgres" e password generate in modo casuale usando il metodo CreateDefaultPasswordParameter.

Il metodo WithReference configura una connessione nel ExampleProject denominato "messaging". Per altre informazioni, vedere ciclo di vita delle risorse contenitore.

Aggiungere la risorsa PostgreSQL di pgAdmin

Quando si aggiungono risorse PostgreSQL all'builder con il metodo AddPostgres, è possibile concatenare le chiamate a WithPgAdmin per aggiungere il contenitore dpage/pgadmin4. Questo contenitore è un client multipiattaforma per i database PostgreSQL, che serve un dashboard di amministrazione basato sul Web. Si consideri l'esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

Il codice precedente aggiunge un contenitore basato sull'immagine docker.io/dpage/pgadmin4. Il contenitore viene usato per gestire le risorse PostgreSQLeserver e quelle di database. Il metodo WithPgAdmin aggiunge un contenitore che gestisce un dashboard di amministrazione basato sul Web per i database PostgreSQL.

Aggiungere la risorsa pgWeb PostgreSQL

Quando si aggiungono risorse PostgreSQL al builder con il metodo AddPostgres, è possibile concatenare le chiamate a WithPgWeb per aggiungere il contenitore sosedoff/pgweb. Questo contenitore è un client multipiattaforma per i database PostgreSQL, che fornisce un dashboard di amministrazione basato sul Web. Si consideri l'esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

Il codice precedente aggiunge un contenitore basato sull'immagine docker.io/sosedoff/pgweb. Tutte le istanze di PostgresDatabaseResource registrate vengono utilizzate per creare un file di configurazione per ciascuna istanza, e ogni configurazione è vincolata alla directory dei segnalibri del contenitore pgweb. Per ulteriori informazioni, consulta la documentazione di PgWeb : segnalibri di connessione Server.

Aggiungere la risorsa PostgreSQLserver con volume di dati

Per aggiungere un volume di dati alla risorsa PostgreSQLserver, chiamare il metodo WithDataVolume nella risorsa PostgreSQLserver:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

Il volume di dati viene usato per rendere persistenti i dati PostgreSQLserver al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /var/lib/postgresql/data nel contenitore PostgreSQLserver e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Aggiungere la risorsa PostgreSQLserver con montaggio di associazione dati

Per aggiungere un montaggio del data bind alla risorsa PostgreSQLserver, chiamare il metodo WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

I montaggi di associazione dei dati si basano sul file system del computer host per mantenere persistenti i dati PostgreSQLserver tra i riavvii del contenitore. Il data bind mount è montato al percorso C:\PostgreSQL\Data su Windows (o /PostgreSQL/Data su Unix) sulla macchina host nel contenitore PostgreSQLserver. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.

Aggiungi la risorsa PostgreSQLserver con il montaggio bind di init

Per aggiungere un mount di tipo bind init alla risorsa PostgreSQLserver, chiamare il metodo WithInitBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

Il mount bind init si basa sul file system della macchina host per inizializzare il database PostgreSQLserver con la cartella init dei contenitori . Questa cartella viene usata per l'inizializzazione, per eseguire script shell eseguibili o file di comando .sql dopo la creazione della cartellapostgres-data . Il mount bind init è montato sul percorso C:\PostgreSQL\Init su Windows (o su /PostgreSQL/Init su Unix) sul computer host nel contenitore PostgreSQLserver.

Aggiungere PostgreSQLserver risorsa con parametri

Quando si vuole specificare in modo esplicito il nome utente e la password usati dall'immagine del contenitore, è possibile specificare queste credenziali come parametri. Si consideri l'esempio alternativo seguente:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

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

// After adding all resources, run the app...

Per altre informazioni sulla fornitura di parametri, vedere Parametri esterni.

Hosting dei controlli di integrità dell'integrazione

L'integrazione di hosting PostgreSQL aggiunge in modo automatico un controllo dell'integrità per la risorsa PostgreSQLserver. Il controllo di integrità verifica che il PostgreSQLserver sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.Npgsql.

integrazione Client

Per iniziare a usare l'integrazione di , installare il pacchetto NuGet Npgsql nel progetto consumatore , cioè, il progetto dell'applicazione che utilizza il . L'integrazione PostgreSQLclient registra un'istanza di NpgsqlDataSource che è possibile usare per interagire con PostgreSQL.

dotnet add package Aspire.Npgsql

<PackageReference Include="Aspire.Npgsql" Version="*" />

Aggiungere Npgsql client

Nel file Program.cs del tuo progetto consumante client, chiama il metodo di estensione AddNpgsqlDataSource su qualsiasi IHostApplicationBuilder per registrare un NpgsqlDataSource da usare tramite il contenitore per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Dopo aver aggiunto NpgsqlDataSource al generatore, è possibile ottenere l'istanza di NpgsqlDataSource usando l'iniezione delle dipendenze. Ad esempio, per recuperare l'oggetto sorgente dati da un servizio di esempio, definiscilo come parametro del costruttore e assicurati che la classe ExampleService sia registrata con il contenitore di iniezione delle dipendenze.

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

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

Aggiungere Npgsql con chiave client

In alcuni casi potrebbe essere necessario registrare più istanze di NpgsqlDataSource con nomi di connessione diversi. Per registrare i client Npgsql con chiave, chiamare il metodo AddKeyedNpgsqlDataSource:

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

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

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Per ulteriori informazioni sui servizi con chiave, vedere .NET iniezione delle dipendenze: servizi con chiave.

Configurazione

L'integrazione .NET AspirePostgreSQL 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 AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

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

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

Per altre informazioni, vedere ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspirePostgreSQL supporta Microsoft.Extensions.Configuration. Carica il NpgsqlSettings da appsettings.json o da altri file di configurazione usando la chiave Aspire:Npgsql. Esempio appsettings.json che configura alcune delle opzioni:

L'esempio seguente mostra un file appsettings.json che configura alcune delle opzioni disponibili:

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

Per lo schema completo PostgreSQLclient di integrazione JSON, vedere Aspire. Npgsql/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<NpgsqlSettings> configureSettings per configurare alcune o tutte le opzioni in linea, ad esempio per disabilitare i controlli di salute:

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

Controlli della salute

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano verifiche dello stato di salute per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

• Aggiunge il NpgSqlHealthCheck, che verifica che i comandi possano essere eseguiti correttamente sul database Postgres sottostante.
• Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta ad accettare il traffico

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente le impostazioni di registrazione, tracciamento e metriche, talvolta noti come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspirePostgreSQL usa le categorie di log seguenti:

• Npgsql.Connection
• Npgsql.Command
• Npgsql.Transaction
• Npgsql.Copy
• Npgsql.Replication
• Npgsql.Exception

Tracciamento

L'integrazione .NET AspirePostgreSQL genererà le attività di traccia seguenti usando OpenTelemetry:

• Npgsql

Metriche

L'integrazione .NET AspirePostgreSQL genererà le metriche seguenti usando OpenTelemetry:

• Npgsql:
  • ec_Npgsql_bytes_written_per_second
  • ec_Npgsql_bytes_read_per_second
  • ec_Npgsql_commands_per_second
  • ec_Npgsql_total_commands
  • ec_Npgsql_current_commands
  • ec_Npgsql_failed_commands
  • ec_Npgsql_prepared_commands_ratio
  • ec_Npgsql_connection_pools
  • ec_Npgsql_multiplexing_average_commands_per_batch
  • ec_Npgsql_multiplexing_average_write_time_per_batch

integrazione dell'hosting AzurePostgreSQL

Per distribuire le risorse di PostgreSQL in Azure, installare il pacchetto NuGet di 📦Aspire.Hosting.Azure.PostgreSQL:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

<PackageReference Include="Aspire.Hosting.Azure.PostgreSQL"
                  Version="*" />

Aggiungere AzurePostgreSQLserver risorsa

Dopo aver installato l'integrazione dell'hosting .NET AspireAzurePostgreSQL, richiamare il metodo di estensione AddAzurePostgresFlexibleServer nel progetto host dell'applicazione.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

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

La chiamata precedente a AddAzurePostgresFlexibleServer configura la risorsa PostgresSQL server da distribuire come AzurePostgres flessibile Server.

Aggiungere Azure Npgsql autenticato client

Per impostazione predefinita, quando si chiama AddAzurePostgresFlexibleServer nell'integrazione dell'hosting PostgreSQL, viene configurato 📦Azure. Identity pacchetto NuGet per abilitare l'autenticazione:

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

La connessione PostgreSQL può essere consumata utilizzando l'integrazione client e Azure.Identity:

builder.AddNpgsqlDataSource(
    "postgresdb", 
    configureDataSourceBuilder: (dataSourceBuilder) =>
{
    if (!string.IsNullOrEmpty(dataSourceBuilder.ConnectionStringBuilder.Password))
    {
        return;
    }

    dataSourceBuilder.UsePeriodicPasswordProvider(async (_, ct) =>
    {
        var credentials = new DefaultAzureCredential();
        var token = await credentials.GetTokenAsync(
            new TokenRequestContext([
                "https://ossrdbms-aad.database.windows.net/.default"
            ]), ct);

        return token.Token;
    },
    TimeSpan.FromHours(24),
    TimeSpan.FromSeconds(10));
});

Il frammento di codice precedente illustra come usare la classe DefaultAzureCredential del pacchetto di Azure.Identity per eseguire l'autenticazione con ID Microsoft Entra e recuperare un token per connettersi al database PostgreSQL. Il metodo UsePeriodicPasswordProvider viene usato per fornire il token al generatore di stringhe di connessione.

Vedere anche

• PostgreSQL docs
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repository