integrazione di .NET AspirePostgreSQLEntity Framework Core

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 PostgreSQL che ospita l'integrazione modella un PostgreSQLserver come tipo di PostgresServerResource. Per accedere a questo tipo e alle API che consentono di aggiungerlo al pacchetto NuGet 📦Aspiredi hostingPostgreSQL nel progetto host applicazione .

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.

Aggiungi 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. Dei riferimenti 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 username impostato su "postgres" e un password generato casualmente utilizzando il metodo CreateDefaultPasswordParameter.

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

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 i database PostgreSQL, che fornisce una dashboard di amministrazione basata 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 di PostgreSQLserver e 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 a builder utilizzando 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 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.

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 è montato nel percorso /var/lib/postgresql/data all'interno del contenitore PostgreSQLserver e quando non viene fornito 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 un mount di associazione dati

Per aggiungere un bind mount di dati 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 data bind mounts si basano sul filesystem del computer host per rendere persistenti i dati PostgreSQLserver attraverso i riavvii del container. Il bind mount dei dati è montato sul percorso C:\PostgreSQL\Data su Windows (o /PostgreSQL/Data in Unix) sul computer host nel contenitore PostgreSQLserver. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

Aggiungere la risorsa PostgreSQLserver con il bind mount init

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

Verifiche di integrità dell'integrazione di hosting

L'integrazione dell'hosting PostgreSQL aggiunge in automatico un controllo dello stato di salute per la risorsa PostgreSQLserver. La verifica dello stato di salute controlla che il PostgreSQLserver 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 di .NET AspirePostgreSQLEntity Framework Coreclient, installare il pacchetto NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL nel progetto clientche consuma, ovvero il progetto per l'applicazione che utilizza il PostgreSQLclient. L'integrazione .NET AspirePostgreSQLEntity Framework Coreclient registra le istanze della sottoclasse DbContext desiderate che è possibile usare per interagire con PostgreSQL.

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 consuma client, chiamare il metodo estensione AddNpgsqlDbContext su IHostApplicationBuilder per registrare la sottoclasse DbContext da usare tramite il contenitore per l'iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione.

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

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",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Per lo schema completo di integrazione PostgreSQLEntity Framework CoreclientJSON, 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>",
          "DbContextPooling": true,
          "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 CanConnectAsync di EF Core. 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.Infrastructure
• 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 emetterà le seguenti attività di tracing 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

integrazione dell'hosting AzurePostgreSQL

Per distribuire le risorse di PostgreSQL in Azure, installare il pacchetto NuGet 📦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, chiama il metodo di estensione AddAzurePostgresFlexibleServer nel progetto host dell'app:

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 server di PostgreSQL da distribuire come AzurePostgres Flessibile Server.

Aggiungere Azure Npgsql autenticato client

Per impostazione predefinita, quando si chiama nell'integrazione dell'hosting , viene configurato il pacchetto NuGet Identity di per abilitare l'autenticazione.

dotnet add package Azure.Identity

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

Si può consumare la connessione PostgreSQL attraverso l'integrazione client e Azure.Identity:

builder.AddNpgsqlDbContext<YourDbContext>(
    "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 stringa di connessione.

Vedere anche

• Azure database per la documentazione PostgreSQL
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repo