integrazione di .NET AspirePostgreSQL

Articolo
01/31/2025

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

L'integrazione dell'hosting PostgreSQL modella le varie risorse PostgreSQL nei seguenti tipi.

Per accedere a questi tipi e API per esprimerli come risorse nel progetto host dell'app , installare il pacchetto NuGet 📦Aspire.Hosting.PostgreSQL.

CLI.NET dell'interfaccia a riga di comando
PackageReference

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 server PostgreSQL

Nel progetto host dell'app chiamare AddPostgres nell'istanza di builder per aggiungere una risorsa server PostgreSQL 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 del server PostgreSQL nel computer locale. Viene usato un riferimento al server PostgreSQL e all'istanza del database PostgreSQL (la variabile postgresdb) per aggiungere una dipendenza al ExampleProject. La risorsa server PostgreSQL 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.

Mancia

Se preferisci connetterti a un server PostgreSQL esistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

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 PostgreSQL database, 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 del server e del database PostgreSQL. Il metodo WithPgAdmin aggiunge un contenitore che gestisce un dashboard di amministrazione basato sul Web per i database PostgreSQL.

Configurare la porta dell'host di pgAdmin

Per configurare la porta host per il contenitore pgAdmin, chiamare il metodo WithHostPort nella risorsa del server PostgreSQL. L'esempio seguente illustra come configurare la porta host per il contenitore pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

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

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

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

Il codice precedente aggiunge e configura la porta host per il contenitore pgAdmin. La porta host viene altrimenti assegnata in modo casuale.

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 PostgreSQL database, che serve 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.

Configurare la porta dell'host pgWeb

Per configurare la porta host per il contenitore pgWeb, chiamare il metodo WithHostPort nella risorsa server PostgreSQL. L'esempio seguente illustra come configurare la porta host per il contenitore pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgWeb => pgWeb.WithHostPort(5050));

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

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

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

Il codice precedente aggiunge e configura la porta host per il contenitore pgWeb. La porta host viene altrimenti assegnata in modo casuale.

Aggiungere PostgreSQL risorsa server con volume di dati

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

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 del server PostgreSQL al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /var/lib/postgresql/data nel contenitore del server PostgreSQL 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.

Aggiungi la risorsa server PostgreSQL con il bind mount dei dati

Per aggiungere un bind mount di dati alla risorsa server PostgreSQL, utilizzare 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...

Importante

I di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i montaggi di associazione consentono l'accesso e la modifica diretta dei file sul sistema host, risultando ideali per lo sviluppo e il test dove sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati del server PostgreSQL tra i riavvii del contenitore. Il montaggio dell'associazione dati viene montato nel percorso C:\PostgreSQL\Data in Windows (o /PostgreSQL/Data in Unix) nel computer host nel contenitore del server PostgreSQL. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.

Aggiungere la risorsa del server PostgreSQL con il montaggio bind di init.

Per aggiungere un montaggio di binding init alla risorsa server PostgreSQL, 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 bind mount init si basa sul file system del computer host per inizializzare il database del server PostgreSQL con la cartella init dei contenitori . Questa cartella viene usata per l'inizializzazione, eseguendo qualsiasi script della shell eseguibile o .sql file di comando dopo la creazione della cartella postgres-data . Il bind mount di init è montato su C:\PostgreSQL\Init in Windows (o su /PostgreSQL/Init sul percorso di Unix) nella macchina host nel contenitore del server PostgreSQL.

Aggiungere PostgreSQL risorsa server 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 dell'hosting PostgreSQL aggiunge automaticamente un controllo di integrità per la risorsa server PostgreSQL. Il controllo di integrità verifica che il server PostgreSQL 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 client .NET AspirePostgreSQL, installare il 📦Aspire. Npgsql pacchetto NuGet nel progetto che usa il client, ovvero il progetto per l'applicazione che usa il client PostgreSQL. L'integrazione client PostgreSQL registra un'istanza di NpgsqlDataSource che è possibile usare per interagire con PostgreSQL.

CLI.NET dell'interfaccia a riga di comando
PackageReference

dotnet add package Aspire.Npgsql

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

Aggiungere il client Npgsql

Nel file Program.cs del progetto che utilizza il client, chiamare il metodo di estensione AddNpgsqlDataSource su qualsiasi IHostApplicationBuilder per registrare un NpgsqlDataSource da utilizzare tramite il contenitore per l'iniezione di dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Mancia

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa server PostgreSQL nel progetto host dell'app. Per altre informazioni, vedere Aggiungere PostgreSQL risorsa server.

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 il client Npgsql con chiave

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 di integrazione client PostgreSQLJSON, 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

Condividi tramite