integrazione di .NET AspirePostgreSQLEntity Framework Core

Articolo
01/31/2025

include:integrazione dell'hosting e Client integrazione

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 AspirePostgreSQLEntity Framework Core 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 sistema di integrazione PostgreSQL modella varie risorse PostgreSQL nei seguenti modi.

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

.NET dell'interfaccia della riga di comando
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

Per ulteriori 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 composte da "postgres" e password generate in modo casuale usando il metodo CreateDefaultPasswordParameter.

Il metodo WithReference configura una connessione nel ExampleProject denominato "messaging". Per ulteriori informazioni, consultare ciclo di vita della risorsa container.

Suggerimento

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

Aggiungere la risorsa PostgreSQL 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 a builder utilizzando 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 ogni istanza, e ciascuna configurazione è associata alla directory dei segnalibri del contenitore pgweb. Per altre informazioni, vedere documentazione di PgWeb: Server segnalibri di connessione.

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 bind mount consentono l'accesso e la modifica diretta dei file sul sistema host, ideale per lo sviluppo e il testing in cui 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 bind mount dei dati è montato sul percorso C:\PostgreSQL\Data su Windows (o /PostgreSQL/Data su Unix) sul computer host nel contenitore server PostgreSQL. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: 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.

Verifiche di integrità dell'integrazione di hosting

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 dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.Npgsql.

integrazione Client

Per iniziare a usare l'integrazione client .NET AspirePostgreSQLEntity Framework Core, installare il pacchetto NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL nel progetto che consuma il client, cioè il progetto dell'applicazione che utilizza il client PostgreSQL. L'integrazione client .NET AspirePostgreSQLEntity Framework Core registra le istanze di sottoclasse DbContext desiderate che è possibile usare per interagire con PostgreSQL.

.NET dell'interfaccia della riga di comando
PackageReference

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

Aggiungere il contesto del database Npgsql

Nel file Program.cs del progetto che usa il client chiamare il metodo di estensione AddNpgsqlDbContext su qualsiasi IHostApplicationBuilder per registrare la sottoclasse DbContext da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddNpgsqlDbContext<YourDbContext>(connectionName: "postgresdb");

Suggerimento

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 YourDbContext al generatore, è possibile ottenere l'istanza di YourDbContext usando l'inserimento delle dipendenze. Ad esempio, per recuperare l'oggetto origine dati da un servizio di esempio, definirlo come parametro del costruttore e assicurarsi che la classe ExampleService sia registrata con il contenitore di inserimento delle dipendenze:

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

Per altre informazioni sul dependency injection, vedere .NET.

Aggiungere il contesto del database Npgsql con arricchimento

Per arricchire il DbContext con servizi aggiuntivi, ad esempio tentativi automatici, controlli dello stato di salute, log e telemetria, chiamare il metodo EnrichNpgsqlDbContext:

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

Il parametro settings è un'istanza della classe NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configurazione

L'integrazione .NET AspirePostgreSQLEntity Framework Core 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, si specifica il nome della stringa di connessione quando si chiama il metodo AddNpgsqlDbContext:

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

La stringa di connessione viene recuperata dalla sezione di configurazione ConnectionStrings:

{
  "ConnectionStrings": {
    "pgdb": "Host=myserver;Database=test"
  }
}

Il EnrichNpgsqlDbContext non userà la sezione di configurazione ConnectionStrings perché prevede che un DbContext venga registrato nel momento in cui viene chiamato.

Per ulteriori informazioni, vedere ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspirePostgreSQLEntity Framework Core supporta Microsoft.Extensions.Configuration. Carica il NpgsqlEntityFrameworkCorePostgreSQLSettings dai file di configurazione, come appsettings.json, utilizzando la chiave Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Se sono state configurate le configurazioni nella sezione Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, è sufficiente chiamare il metodo senza passare alcun parametro.

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

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

Per lo schema completo PostgreSQLEntity Framework CoreJSON di integrazione client, vedere Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> per configurare alcune o tutte le opzioni inline, ad esempio per impostare il ConnectionString:

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

Configurare più classi DbContext

Se desideri registrare più di un DbContext con configurazioni diverse, puoi usare il nome della sezione di configurazione $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". La configurazione json sarà simile alla seguente:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Chiamando quindi il metodo AddNpgsqlDbContext con un parametro di tipo AnotherDbContext si caricheranno le impostazioni dalla sezione Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Controlli sanitari

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.

Per impostazione predefinita, le integrazioni .NET AspirePostgreSQLEntity Framework Core gestiscono le operazioni seguenti:

Aggiunge il DbContextHealthCheck, che chiama il metodo EF Core di CanConnectAsync. Il nome del controllo della salute è il nome del tipo TContext.
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 impostazioni di registrazione, tracciamento e metriche, talvolta note 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 AspirePostgreSQLEntity Framework Core usa le categorie di log seguenti:

Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Model
Microsoft.EntityFrameworkCore.Model.Validation
Microsoft.EntityFrameworkCore.Query
Microsoft.EntityFrameworkCore.Update

Tracciamento

L'integrazione .NET AspirePostgreSQLEntity Framework Core genererà le attività di traccia seguenti usando OpenTelemetry:

Npgsql

Metriche

L'integrazione .NET AspirePostgreSQLEntity Framework Core genererà le metriche seguenti usando OpenTelemetry:

Microsoft.EntityFrameworkCore:
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second
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