integración .NET AspirePostgreSQL

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 AspirePostgreSQL 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 docker.io/library/postgres.

Integración de hospedaje

La integración del servidor PostgreSQL modela varios recursos PostgreSQL en los siguientes tipos.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Para acceder a estos tipos y las API para expresarlas como recursos dentro de tu proyecto de host de aplicaciones , instala el paquete NuGet .Hosting.

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 los paquetes en las 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 PostgreSQL incluye credenciales predeterminadas con un username de "postgres" y password que se generan aleatoriamente utilizando 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.

Agregar el recurso de pgAdmin PostgreSQL.

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 sirve un panel de administración basado en 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 agregar recursos PostgreSQL al builder con el método AddPostgres, puede encadenar llamadas a WithPgWeb para agregar el contenedor sosedoff/pgweb. Este contenedor es un cliente multiplataforma para bases de datos PostgreSQL, que sirve un panel de administración basado en 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 utilizan para crear un archivo de configuración por instancia, y cada configuración está vinculada al directorio de marcadores del contenedor 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 proporciona un parámetro name, el nombre se genera al azar. Para obtener más información sobre los volúmenes de datos y los motivos por los que se prefieren a los montajes enlazados , consulte la documentación: Docker Volúmenes.

Adición de PostgreSQL recurso del servidor con vinculación de montaje de datos

Para agregar una vinculación de datos 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...

Los montajes de enlace de datos dependen del sistema de archivos del equipo host para conservar los datos del servidor de PostgreSQL en los reinicios del contenedor. El montaje vinculado de datos se monta en el C:\PostgreSQL\Data en Windows (o en el /PostgreSQL/Data en Unix) en la ruta de la máquina host dentro del contenedor del servidor PostgreSQL. Para obtener más información sobre los montajes de enlace de datos, consulte: Docker documentación: Montajes de enlace.

Adición del recurso de servidor PostgreSQL con vinculación inicial de montaje

Para agregar un montaje de enlace de inicialización al recurso del servidor de 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 bind de inicialización se basa en el sistema de archivos del equipo host para inicializar la base de datos del servidor con la carpeta init de los contenedores. Esta carpeta se utiliza para la inicialización y para ejecutar scripts de shell ejecutables o archivos de comandos .sql una vez que se haya creado la carpeta postgres-data. El punto de montaje del enlace inicial se monta en la ruta de acceso C:\PostgreSQL\Init en Windows (o /PostgreSQL/Init en Unix) en el equipo host dentro del contenedor del servidor PostgreSQL.

Añadir 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.

Hospedaje de comprobaciones de estado de integración

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.

Client integración

Para empezar a trabajar con la integración del cliente .NET AspirePostgreSQL, instale el paquete NuGet 📦Aspire.Npgsql en el proyecto que consuma el cliente, es decir, el proyecto de la aplicación que usa al cliente PostgreSQL. La integración del cliente de registra una instancia de NpgsqlDataSource que puede usar para interactuar con .

dotnet add package Aspire.Npgsql

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

Adición de un cliente Npgsql

En el archivo Program.cs del proyecto que consume el cliente, llame al método de extensión AddNpgsqlDataSource en cualquier IHostApplicationBuilder para registrar un NpgsqlDataSource 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.AddNpgsqlDataSource(connectionName: "postgresdb");

Después de agregar NpgsqlDataSource al generador, puede obtener la instancia de NpgsqlDataSource 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(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

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

Adición de un cliente Npgsql con clave

Puede haber situaciones en las que quiera registrar varias instancias de NpgsqlDataSource con nombres de conexión diferentes. Para registrar clientes Npgsql con claves, llame al método AddKeyedNpgsqlDataSource:

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

A continuación, puede recuperar las instancias de NpgsqlDataSource usando inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

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

Para obtener más información sobre los servicios con claves, consulte .NET inserción de dependencias: Servicios con claves.

Configuración

La integración de .NET AspirePostgreSQL 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, puede proporcionar el nombre de la cadena de conexión al llamar al método AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

A continuación, la cadena de conexión se recuperará de la sección de configuración ConnectionStrings:

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

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

Uso de proveedores de configuración

La integración de .NET AspirePostgreSQL admite Microsoft.Extensions.Configuration. Carga el NpgsqlSettings desde appsettings.json u otros archivos de configuración mediante la clave Aspire:Npgsql. Ejemplo appsettings.json que configura algunas de las opciones:

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

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

Para obtener el esquema completo PostgreSQL de integración del cliente JSON, consulte Aspire.Npgsql/ConfigurationSchema.json.

Usa delegados en línea

También puede pasar el delegado de Action<NpgsqlSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para desactivar las verificaciones de estado de salud.

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

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 alojamiento también habilitan los puntos de comprobación de estado. Para obtener más información, consulte:

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

• Agrega el NpgSqlHealthCheck, que comprueba que los comandos se pueden ejecutar correctamente en la base de datos Postgres subyacente.
• Se integra con el punto de conexión HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben pasarse para que la aplicación se considere lista para aceptar el 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 Configuración.

Registro

La integración de .NET AspirePostgreSQL usa las siguientes categorías de registro:

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

Seguimiento

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

• Npgsql

Métricas

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

Consulte también

• PostgreSQL documentos
• .NET Aspire Azure PostgreSQL integración
• .NET .NET Aspire integraciones
• .NET Aspire GitHub repositorio