Compartir a través de

integración de .NET AspirePostgreSQL

  • Artículo

Incluye:,,integración de hospedaje y ,,Client integración

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

El modelo de integración de PostgreSQL estructura un PostgreSQLserver como tipo PostgresServerResource. Para acceder a este tipo y APIs que le permiten agregarlo a la 📦Aspire.Hosting.PostgreSQL paquete NuGet en el proyecto del host de la aplicación .

dotnet add package Aspire.Hosting.PostgreSQL

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

Agregar PostgreSQLserver recurso

En el proyecto host de la aplicación, llame a AddPostgres en la instancia de builder para agregar un recurso de PostgreSQLserver 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 PostgreSQLserver en el equipo local. Se usa una referencia a PostgreSQLyserver y a la instancia de la base de datos PostgreSQL (la variable postgresdb) para agregar una dependencia a la ExampleProject. El recurso PostgreSQLserver incluye credenciales predeterminadas con un username de "postgres" y password generados 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 PostgreSQLserverexistente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.

Agregar el recurso de pgAdmin PostgreSQL.

Al agregar recursos de al con el método , puede encadenar llamadas a para agregar el contenedor de dpage/pgadmin4. Este contenedor es una client multiplataforma para PostgreSQL bases de datos, que sirve a 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 PostgreSQLserver. El método WithPgAdmin agrega un contenedor que sirve un panel de administración basado en web para PostgreSQL bases de datos.

Agregar recurso de 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 una client multiplataforma para PostgreSQL bases de datos, 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 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.

Añadir recursos PostgreSQLserver con volumen de datos

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

El volumen de datos se utiliza para persistir los datos de PostgreSQLserver fuera del ciclo de vida del contenedor. El volumen de datos se monta en la ruta de acceso /var/lib/postgresql/data del contenedor de PostgreSQLserver y, cuando no se proporciona un parámetro name, el nombre se genera de forma aleatoria. Para obtener más información sobre los volúmenes de datos y por qué se prefieren sobre los montajes enlazados , consulte la documentación de Docker: Volúmenes.

Adición de PostgreSQLserver recurso con montaje de enlace de datos

Para agregar un montaje de enlace de datos al recurso de PostgreSQLserver, 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 montajes de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen un mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes de enlace permiten el acceso directo y la modificación de archivos en el sistema host, ideal para el desarrollo y las pruebas donde se necesitan cambios en tiempo real.

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

Adición de recurso PostgreSQLserver con montaje tipo bind de init

Para agregar un montaje de enlace de inicialización al recurso de PostgreSQLserver, 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 de inicialización se basa en el sistema de archivos del equipo host para inicializar la base de datos de PostgreSQLserver con los contenedores carpeta init. Esta carpeta se utiliza para la inicialización, ejecutando los scripts de shell ejecutables o los archivos de comandos .sql después de crear la carpeta postgres-data. El montaje bind de init se monta en la ruta C:\PostgreSQL\Init en Windows (o /PostgreSQL/Init en Unix) en la máquina host en el contenedor PostgreSQLserver.

Añadir el recurso PostgreSQLserver con los 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 PostgreSQL agrega automáticamente una comprobación de estado para el recurso PostgreSQLserver. La verificación de estado comprueba que el PostgreSQLserver está en funcionamiento y que se puede establecer una conexión con él.

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

integración de Client

Para empezar a trabajar con la integración de .NET AspirePostgreSQLclient, instale el 📦AspireNpgsql paquete de NuGet en el clientproyecto consumidor, es decir, el proyecto de la aplicación que usa el PostgreSQLclient. La integración de PostgreSQLclient registra una instancia de NpgsqlDataSource que puede usar para interactuar con PostgreSQL.

dotnet add package Aspire.Npgsql

Añadir Npgsql client

En el archivo Program.cs del proyecto que consume client, llame al método de extensión AddNpgsqlDataSource en cualquier IHostApplicationBuilder para registrar un NpgsqlDataSource para su uso a través del contenedor de inserción de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Propina

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

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 client 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 de integración PostgreSQLclientJSON, consulte Aspire. Npgsql/ConfigurationSchema.json.

Usa delegados insertados

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 comprobaciones de estado.

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

Comprobaciones de estado

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan los chequeos de salud de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

  • Agrega el NpgSqlHealthCheck, que comprueba que los comandos se pueden ejecutar correctamente en la base de datos de 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

Azure PostgreSQL integración de hospedaje

Para implementar los recursos de PostgreSQL en Azure, instale el 📦Aspire. Hospitalidad.Azure.PostgreSQL paquete NuGet:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Agregar AzurePostgreSQLserver recurso

Después de haber instalado la integración de hospedaje de .NET AspireAzurePostgreSQL, llame al método de extensión llamado AddAzurePostgresFlexibleServer en el proyecto anfitrión de la aplicación.

var builder = DistributedApplication.CreateBuilder(args);

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

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

La llamada anterior a AddAzurePostgresFlexibleServer configura el recurso de PostgreSQL server que se va a implementar como un flexible AzurePostgresServer.

Importante

De forma predeterminada, AddAzurePostgresFlexibleServer configura la autenticación de Microsoft Entra ID. Esto requiere cambios en las aplicaciones que necesitan conectarse a estos recursos. Para obtener más información, consulte Client integración.

Agregar Azure autenticado Npgsql client

De forma predeterminada, al llamar a AddAzurePostgresFlexibleServer en la integración de hospedaje de PostgreSQL, configura 📦Azure. Identidad paquete NuGet para habilitar la autenticación:

dotnet add package Azure.Identity

La conexión PostgreSQL se puede consumir mediante la integración de client y Azure.Identity:

builder.AddNpgsqlDataSource(
    "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));
});

El fragmento de código anterior muestra cómo usar la clase DefaultAzureCredential del paquete de Azure.Identity para autenticarse con id. de Microsoft Entra y recuperar un token para conectarse a la base de datos de PostgreSQL. El método UsePeriodicPasswordProvider se usa para proporcionar el token al generador de cadenas de conexión.

Consulte también