Integración de .NET AspirePostgreSQLEntity Framework Core

Artículo
02/07/2025

incluye: integración de hospedaje de e integración de Client

PostgreSQL es un potente sistema de bases de datos relacionales de objetos de código abierto con muchos años de desarrollo activo que le ha ganado una sólida reputación de confiabilidad, solidez de características y rendimiento. La integración de .NET AspirePostgreSQLEntity Framework Core proporciona una manera de conectarse a las bases de datos de PostgreSQL existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor de docker.io/library/postgres.

Integración de hospedaje

La integración de alojamiento de PostgreSQL modela varios recursos PostgreSQL como los tipos siguientes.

Para acceder a estos tipos y APIs y expresarlos como recursos en el proyecto de host de la aplicación , instale el paquete NuGet 📦Aspire.Hosting.PostgreSQL.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en aplicaciones .NET.

Agregar PostgreSQL recurso de servidor

En el proyecto host de la aplicación, llame a AddPostgres en la instancia de builder para agregar un recurso de servidor de PostgreSQL y, a continuación, llame a AddDatabase en la instancia de postgres para agregar un recurso de base de datos, como se muestra en el ejemplo siguiente:

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...

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/library/postgres, crea una nueva instancia de servidor PostgreSQL en el equipo local. Se usa una referencia al servidor de PostgreSQL y a la instancia de base de datos de PostgreSQL (la variable postgresdb) para agregar una dependencia al ExampleProject. El recurso del servidor de PostgreSQL incluye credenciales predeterminadas con un username de "postgres" y password que se generan aleatoriamente mediante el método CreateDefaultPasswordParameter.

El método WithReference configura una conexión en el ExampleProject denominado "messaging". Para obtener más información, consulte Ciclo de Vida de los Recursos de Contenedor.

Propina

Si prefiere conectarse a un servidor PostgreSQL existente, llame a AddConnectionString en su lugar. Para obtener más información, consulte Referencia de recursos existentes.

Agregar recurso PostgreSQL pgAdmin

Al agregar recursos de PostgreSQL al builder con el método AddPostgres, puede encadenar llamadas a WithPgAdmin para agregar el contenedor dpage/pgadmin4. Este contenedor es un cliente multiplataforma para bases de datos PostgreSQL, que proporciona un panel de administración basado en la web. Tenga en cuenta el ejemplo siguiente:

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...

El código anterior agrega un contenedor basado en la imagen de docker.io/dpage/pgadmin4. El contenedor se usa para administrar los recursos de base de datos y servidor de PostgreSQL. El método WithPgAdmin agrega un contenedor que sirve un panel de administración basado en web para PostgreSQL bases de datos.

Configuración del puerto de host pgAdmin

Para configurar el puerto de host para el contenedor pgAdmin, llame al método WithHostPort en el recurso del servidor PostgreSQL. En el ejemplo siguiente se muestra cómo configurar el puerto de host para el contenedor 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...

El código anterior agrega y configura el puerto de host para el contenedor pgAdmin. De lo contrario, se asigna aleatoriamente el puerto de host.

Agregar el recurso pgWeb PostgreSQL

Al añadir recursos PostgreSQL al builder utilizando el método AddPostgres, puedes encadenar llamadas a WithPgWeb para agregar el contenedor sosedoff/pgweb. Este contenedor es un cliente multiplataforma para bases de datos PostgreSQL, que proporciona un panel de administración basado en la web. Tenga en cuenta el ejemplo siguiente:

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...

El código anterior agrega un contenedor basado en la imagen de docker.io/sosedoff/pgweb. Todas las instancias de PostgresDatabaseResource registradas se usan para crear un archivo de configuración por instancia, y cada configuración está vinculada al directorio de marcadores del contenedor de pgweb. Para obtener más información, consulte documentación de PgWeb: Server marcadores de conexión.

Configuración del puerto de host pgWeb

Para configurar el puerto de host para el contenedor pgWeb, llame al método WithHostPort en el recurso del servidor de PostgreSQL. En el ejemplo siguiente se muestra cómo configurar el puerto de host para el contenedor pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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

El código anterior agrega y configura el puerto de host para el contenedor pgWeb. De lo contrario, se asigna aleatoriamente el puerto de host.

Agregar PostgreSQL recurso de servidor con volumen de datos

Para agregar un volumen de datos al recurso del servidor de PostgreSQL, llame al método WithDataVolume en el recurso del servidor de 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...

El volumen de datos se usa para conservar los datos del servidor de PostgreSQL fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /var/lib/postgresql/data en el contenedor del servidor PostgreSQL y cuando no se especifica un parámetro name, el nombre se genera de forma aleatoria. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a montajes de enlace, consulte la Docker documentación: Volúmenes.

Agregar el recurso de servidor PostgreSQL con montaje de enlace de datos

Para agregar un montaje de datos vinculado al recurso del servidor PostgreSQL, llame al método 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

Los bind mounts de datos tienen una funcionalidad limitada en comparación con los volúmenes, que ofrecen mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes enlazados permiten el acceso directo y la modificación de archivos en el sistema host, lo cual es ideal para el desarrollo y las pruebas cuando se necesitan cambios en tiempo real.

Las vinculaciones de datos dependen del sistema de archivos de la máquina anfitriona para mantener los datos del servidor de PostgreSQL durante los reinicios de contenedores. El montaje de vínculo de datos se encuentra en la ruta C:\PostgreSQL\Data en Windows (o /PostgreSQL/Data en Unix) de la máquina anfitriona en el contenedor del servidor PostgreSQL. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: Enlazar montajes.

Añadir recurso de servidor PostgreSQL con montaje de enlace inicial

Para agregar un enlace de montaje inicial al recurso del servidor PostgreSQL, llame al método 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...

El montaje de enlace init se basa en el sistema de archivos de la máquina host para inicializar la base de datos del servidor PostgreSQL con la carpeta init de los contenedores. Esta carpeta se utiliza para la inicialización, ejecutando scripts de shell o archivos de comandos .sql después de que se crea la carpeta postgres-data. El montaje de vinculación de inicio se realiza en el C:\PostgreSQL\Init en Windows (o en /PostgreSQL/Init en Unix) en la ruta del equipo host, dentro del contenedor del servidor PostgreSQL.

Añada el recurso de servidor PostgreSQL con parámetros

Si desea proporcionar explícitamente el nombre de usuario y la contraseña usados por la imagen de contenedor, puede proporcionar estas credenciales como parámetros. Considere el siguiente ejemplo alternativo:

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...

Para obtener más información sobre cómo proporcionar parámetros, consulte Parámetros externos.

Integración de comprobaciones de salud de alojamiento

La integración de hospedaje de PostgreSQL agrega automáticamente una comprobación de estado para el recurso del servidor de PostgreSQL. La comprobación de estado comprueba que el PostgreSQL servidor se está ejecutando y que se puede establecer una conexión a él.

La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.Npgsql.

integración Client

Para comenzar con la integración del cliente de .NET AspirePostgreSQLEntity Framework Core, instale el paquete NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL en el proyecto que consuma el cliente, es decir, el proyecto de la aplicación que utiliza el cliente de PostgreSQL. La integración de cliente .NET AspirePostgreSQLEntity Framework Core registra las instancias de subclase de DbContext deseadas que puede usar para interactuar con PostgreSQL.

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

Añadir el contexto de la base de datos Npgsql

En el archivo Program.cs de su proyecto cliente-consumidor, llame al método de extensión AddNpgsqlDbContext en cualquier IHostApplicationBuilder para registrar su subclase DbContext para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

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

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso de servidor PostgreSQL en el proyecto host de la aplicación. Para obtener más información, consulte Agregar PostgreSQL recurso de servidor.

Después de agregar YourDbContext al generador, puede obtener la instancia de YourDbContext mediante la inyección de dependencias. Por ejemplo, para recuperar el objeto de origen de datos de un servicio de ejemplo, definalo como parámetro de constructor y asegúrese de que la clase ExampleService esté registrada con el contenedor de inserción de dependencias:

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

Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.

Enriquecimiento de un contexto de base de datos Npgsql

Es posible que prefiera usar el método de Entity Framework estándar para obtener un contexto de base de datos y agregarlo al contenedor de inserción de dependencias:

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

Nota

El nombre de la cadena de conexión que se pasa al método GetConnectionString debe coincidir con el nombre usado al agregar el recurso de servidor PostgreSQL en el proyecto host de la aplicación. Para obtener más información, consulte Agregar PostgreSQL recurso de servidor.

Tiene más flexibilidad al crear el contexto de la base de datos de esta manera, por ejemplo:

Puede reutilizar el código de configuración existente para el contexto de la base de datos sin volver a escribirlo para .NET.NET Aspire.
Puede usar Entity Framework Core interceptores para modificar las operaciones de base de datos.
Puede optar por no usar la agrupación de contextos Entity Framework Core, lo cual podría funcionar mejor en algunas circunstancias.

Si usa este método, puede mejorar el contexto de la base de datos con reintentos de estilo .NET.NET Aspire, comprobaciones de estado, registro y características de telemetría llamando al método EnrichNpgsqlDbContext:

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

El parámetro settings es una instancia de la clase NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configuración

La integración de .NET AspirePostgreSQLEntity Framework Core proporciona varios enfoques y opciones de configuración para cumplir los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, proporcione el nombre de la cadena de conexión al llamar al método AddNpgsqlDbContext:

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

La cadena de conexión se obtiene de la sección de configuración ConnectionStrings.

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

El EnrichNpgsqlDbContext no usará la sección de configuración de ConnectionStrings, ya que espera que el DbContext esté registrado en el momento de ser llamado.

Para obtener más información, consulte el ConnectionString.

Uso de proveedores de configuración

La integración .NET AspirePostgreSQLEntity Framework Core es compatible con Microsoft.Extensions.Configuration. Carga el NpgsqlEntityFrameworkCorePostgreSQLSettings desde archivos de configuración como appsettings.json mediante la clave Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Si ha configurado las configuraciones en la sección Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, simplemente puede llamar al método sin pasar ningún parámetro.

En el ejemplo siguiente se muestra un archivo appsettings.json que configura algunas de las opciones disponibles:

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

Para el esquema completo de integración de cliente PostgreSQLEntity Framework CoreJSON, consulte Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Utilice delegados en línea

También puede pasar el delegado Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> para configurar algunas o todas las opciones en línea, por ejemplo, para establecer el ConnectionString:

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

Configuración de varias clases DbContext

Si desea registrar más de una DbContext con una configuración diferente, puede usar el nombre de la sección de configuración $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". La configuración json tendría el siguiente aspecto:

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

A continuación, llamar al método AddNpgsqlDbContext con un parámetro de tipo AnotherDbContext cargaría la configuración desde la sección Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Client comprobaciones de salud de integración

De forma predeterminada, las integraciones de cliente .NET.NET Aspire tienen las comprobaciones de estado habilitadas para todos los servicios. Del mismo modo, muchas .NET.NET Aspireintegraciones de hospedaje también habilitan los puntos de conexión de comprobación de estado. Para obtener más información, consulte:

.NET comprobaciones de estado de la aplicación en C#
revisiones de salud en ASP.NET Core

De forma predeterminada, las integraciones de .NET AspirePostgreSQLEntity Framework Core controlan lo siguiente:

Agrega el DbContextHealthCheck, que llama al método CanConnectAsync de EF Core. El nombre de la verificación de salud es el nombre del tipo TContext.
Se integra con el punto de conexión HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben ser superadas para que la aplicación se considere lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección de configuración .

Registro

La integración de .NET AspirePostgreSQLEntity Framework Core usa las siguientes categorías de registro:

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

Rastreo

La integración de .NET AspirePostgreSQLEntity Framework Core emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

Npgsql

Métricas

La integración de .NET AspirePostgreSQLEntity Framework Core emitirá las siguientes métricas mediante 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

Consulte también

PostgreSQL documentos
integración de .NET AspireAzurePostgreSQLEntity Framework Core
Integraciones .NET.NET Aspire
.NET Aspire GitHub repo

Compartir a través de