Compartir a través de

.NET Aspire Azure PostgreSQL integración

  • Artículo

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

Azure Database for PostgreSQL—Flexible Server es un servicio de base de datos relacional basado en el motor de base de datos de código abierto Postgres. Es una base de datos como servicio totalmente administrada que puede controlar las cargas de trabajo críticas con un rendimiento predecible, seguridad, alta disponibilidad y escalabilidad dinámica. La integración de .NET AspireAzurePostgreSQL proporciona una manera de conectarse a las bases de datos de AzurePostgreSQL 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 de hospedaje .NET AspireAzurePostgreSQL modela un servidor y una base de datos flexibles PostgreSQL como los tipos AzurePostgresFlexibleServerResource y AzurePostgresFlexibleServerDatabaseResource. Otros tipos que están inherentemente disponibles en la integración de hospedaje se representan en los siguientes recursos:

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Para más información, consulte dotnet add package.

La integración de hospedaje de AzurePostgreSQL se basa en el paquete NuGet 📦Aspire.Hosting.PostgreSQL, extendiéndolo para admitir Azure. Todo lo que puede hacer con la integración de .NET AspirePostgreSQL y con la integración de .NET AspirePostgreSQLEntity Framework Core, también puede hacerlo con esta integración.

Adición de recursos del servidor AzurePostgreSQL

Después de instalar la integración de hospedaje .NET AspireAzurePostgreSQL, llame al método de extensión AddAzurePostgresFlexibleServer en el proyecto host de su 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 del servidor PostgresSQL que se va a implementar como un AzurePostgres Flexible Server.

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.

Propina

Al llamar a AddAzurePostgresFlexibleServer, llama implícitamente a AddAzureProvisioning, lo que agrega compatibilidad para generar recursos de Azure dinámicamente durante el inicio de la aplicación. La aplicación debe configurar la suscripción y la ubicación adecuadas. Para obtener más información, consulte aprovisionamiento local: Configuración.

Aprovisionamiento generado de Bicep

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir los recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, ya que las API de aprovisionamiento generan Bicep automáticamente. Al publicar tu aplicación, el Bicep generado se muestra junto al archivo de manifiesto. Cuando agregas un recurso de AzurePostgreSQL, se genera el siguiente Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = {
  name: take('postgresflexible-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    authConfig: {
      activeDirectoryAuth: 'Enabled'
      passwordAuth: 'Disabled'
    }
    availabilityZone: '1'
    backup: {
      backupRetentionDays: 7
      geoRedundantBackup: 'Disabled'
    }
    highAvailability: {
      mode: 'Disabled'
    }
    storage: {
      storageSizeGB: 32
    }
    version: '16'
  }
  sku: {
    name: 'Standard_B1ms'
    tier: 'Burstable'
  }
  tags: {
    'aspire-resource-name': 'postgres-flexible'
  }
}

resource postgreSqlFirewallRule_AllowAllAzureIps 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2024-08-01' = {
  name: 'AllowAllAzureIps'
  properties: {
    endIpAddress: '0.0.0.0'
    startIpAddress: '0.0.0.0'
  }
  parent: postgres_flexible
}

resource postgres_flexible_admin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = {
  name: principalId
  properties: {
    principalName: principalName
    principalType: principalType
  }
  parent: postgres_flexible
  dependsOn: [
    postgres_flexible
    postgreSqlFirewallRule_AllowAllAzureIps
  ]
}

output connectionString string = 'Host=${postgres_flexible.properties.fullyQualifiedDomainName};Username=${principalName}'

Bicep anterior es un módulo que aprovisiona un servidor flexible AzurePostgreSQL con los valores predeterminados siguientes:

  • authConfig: configuración de autenticación del servidor PostgreSQL. El valor predeterminado es ActiveDirectoryAuth habilitado y PasswordAuth deshabilitado.
  • availabilityZone: zona de disponibilidad del servidor PostgreSQL. El valor predeterminado es 1.
  • backup: la configuración de copia de seguridad del servidor PostgreSQL. El valor predeterminado es BackupRetentionDays establecido en 7 y GeoRedundantBackup establecido en Disabled.
  • highAvailability: configuración de alta disponibilidad del servidor PostgreSQL. El valor predeterminado es Disabled.
  • storage: configuración de almacenamiento del servidor PostgreSQL. El valor predeterminado StorageSizeGB se establece en 32.
  • version: la versión del servidor PostgreSQL. El valor predeterminado es 16.
  • sku: SKU del servidor PostgreSQL. El valor predeterminado es Standard_B1ms.
  • tags: etiquetas del servidor de PostgreSQL. El valor predeterminado es aspire-resource-name establecido en el nombre del recurso de Aspire, en este caso postgres-flexible.

Además del servidor flexible PostgreSQL, también proporciona una regla de Firewall Azure para permitir todas las direcciones IP de Azure. Por último, se crea un administrador para el servidor de PostgreSQL y la cadena de conexión se genera como una variable de salida. El Bicep generado es solo un punto de partida y puede personalizarse para satisfacer sus requisitos específicos.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo permite la personalización del Bicep generado, proporcionando una API flexible para configurar los recursos de Azure mediante la API de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el kind, consistencyPolicy, locations, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de servidor de PostgreSQL:

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var flexibleServer = infra.GetProvisionableResources()
                                  .OfType<PostgreSqlFlexibleServer>()
                                  .Single();

        flexibleServer.Sku = new PostgreSqlFlexibleServerSku
        {
            Tier = PostgreSqlFlexibleServerSkuTier.Burstable,
        };
        flexibleServer.HighAvailability = new PostgreSqlFlexibleServerHighAvailability
        {
            Mode = PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant,
            StandbyAvailabilityZone = "2",
        };
        flexibleServer.Tags.Add("ExampleKey", "Example value");
    });

El código anterior:

Hay muchas más opciones de configuración disponibles para personalizar el recurso de servidor flexible PostgreSQL. Para obtener más información, consulte Azure.Provisioning.PostgreSql y Azure. Personalización del aprovisionamiento.

Conexión a un servidor flexible de AzurePostgreSQL existente

Es posible que tenga un servidor flexible AzurePostgreSQL existente al que desea conectarse. En lugar de representar un nuevo recurso de servidor flexible AzurePostgreSQL, puede agregar una cadena de conexión al host de la aplicación. Para agregar una conexión a un servidor flexible de AzurePostgreSQL existente, llame al método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddConnectionString("postgres");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(postgres);

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

Nota

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en secretos de usuario, en la sección ConnectionStrings. El host de la aplicación inserta esta cadena de conexión como una variable de entorno en todos los recursos dependientes, por ejemplo:

{
    "ConnectionStrings": {
        "postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
    }
}

El recurso dependiente puede acceder a la cadena de conexión insertada llamando al método GetConnectionString y pasando el nombre de conexión como parámetro, en este caso "postgres". La API de GetConnectionString es una abreviación de IConfiguration.GetSection("ConnectionStrings")[name].

Ejecuta el recurso AzurePostgreSQL como un contenedor

La integración de hospedaje de AzurePostgreSQL admite la ejecución del servidor PostgreSQL como contenedor local. Esto es beneficioso para situaciones en las que desea ejecutar el servidor de PostgreSQL localmente con fines de desarrollo y pruebas, evitando la necesidad de aprovisionar un recurso de Azure o conectarse a un servidor de AzurePostgreSQL existente.

Para ejecutar el servidor de PostgreSQL como contenedor, llame al método RunAsContainer:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer();

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

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

El código anterior configura un recurso de AzurePostgreSQLServer flexible para que se ejecute localmente en un contenedor.

Propina

El método RunAsContainer es útil para el desarrollo y las pruebas locales. La API expone un delegado opcional que le permite personalizar la configuración de PostgresServerResource subyacente. Por ejemplo, puede agregar pgAdmin y pgWeb, añadir un volumen de almacenamiento de datos o un enlace de montaje de datos, y agregar un enlace de montaje de inicialización. Para obtener más información, consulte la sección .NET AspirePostgreSQL de integración de hospedaje.

Configuración del servidor AzurePostgreSQL para usar la autenticación con contraseña

De forma predeterminada, el servidor AzurePostgreSQL está configurado para usar autenticación de Microsoft Entra ID. Si desea usar la autenticación de contraseñas, puede configurar el servidor para que use la autenticación de contraseña llamando al método WithPasswordAuthentication:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .WithPasswordAuthentication(username, password);

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

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

El código anterior configura el servidor de AzurePostgreSQL para usar la autenticación de contraseña. Los parámetros username y password se agregan al host de la aplicación como parámetros y se llama al método WithPasswordAuthentication para configurar el servidor AzurePostgreSQL para usar la autenticación con contraseña. Para obtener más información, vea Parámetros externos.

integración Client

Para comenzar con la integración del cliente de , instale el paquete NuGet .Npgsql en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que utiliza el cliente . La integración del cliente PostgreSQL registra una instancia de NpgsqlDataSource que puede utilizar para interactuar con PostgreSQL.

dotnet add package Aspire.Npgsql

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 inserción de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Propina / Consejo / Sugerencia

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 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 mediante inyección de dependencia. 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 de ConnectionStrings:

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

Para obtener más información, consulte 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 del cliente de PostgreSQLJSON, consulte Aspire.Npgsql/ConfigurationSchema.json.

Usar delegados en línea

También puede pasar el Action<NpgsqlSettings> configureSettings delegado para configurar algunas o todas las opciones directamente, por ejemplo, para deshabilitar los chequeos 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 hospedaje habilitan también los puntos de conexión de comprobación de estado. Para obtener más información, consulte:

  • 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 /health, que especifica que todas las comprobaciones de estado registradas deben aprobarse 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 AspirePostgreSQL usa las siguientes categorías de registro:

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

Rastreo

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

Añadir cliente Npgsql autenticado Azure

De forma predeterminada, al llamar a AddAzurePostgresFlexibleServer en la integración de hosting de su PostgreSQL, se configura el paquete NuGet 📦Azure.Identity para habilitar la autenticación.

dotnet add package Azure.Identity

La conexión PostgreSQL se puede consumir mediante la integración del cliente 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