.NET AspireAzurePostgreSQL integración

Incluye: Integración de alojamiento —&— Client integración

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:

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

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

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

La integración de hospedaje de AzurePostgreSQL depende del paquete de 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 de servidor PostgresSQL para que se despliegue como un AzurePostgres Flexible Server.

Bicep generado por el aprovisionamiento

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 la aplicación, el Bicep generado se muestra junto con el 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

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
}

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

output name string = postgres_flexible.name

Bicep anterior es un módulo que aprovisiona un AzurePostgreSQL recurso de servidor flexible. Además, las asignaciones de roles se crean para el Azure recurso en un módulo independiente:

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

param postgres_flexible_outputs_name string

param principalType string

param principalId string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' existing = {
  name: postgres_flexible_outputs_name
}

resource postgres_flexible_admin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = {
  name: principalId
  properties: {
    principalName: principalName
    principalType: principalType
  }
  parent: 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 un punto de partida y se ve influido por los cambios en la infraestructura de aprovisionamiento en C#. Las personalizaciones realizadas directamente en el archivo Bicep se sobrescribirán, por lo que los cambios deben realizarse a través de las API de aprovisionamiento de C# para garantizar que se reflejen en los archivos generados.

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 fluida para configurar los recursos Azure mediante la API 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.AddAzurePostgresFlexibleServer("postgres")
    .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:

• Encadena una llamada a API ConfigureInfrastructure:
  • El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
  • Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
  • Se recupera el único PostgreSqlFlexibleServer.
  • El sku se establece con PostgreSqlFlexibleServerSkuTier.Burstable.
  • Las propiedades de alta disponibilidad se establecen con PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant en la zona de disponibilidad de espera "2".
  • Se agrega una etiqueta al servidor flexible con una clave de ExampleKey y un valor de Example value.

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. Encadenar una llamada para anotar que AzurePostgresFlexibleServerResource es un recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingPostgresName = builder.AddParameter("existingPostgresName");
var existingPostgresResourceGroup = builder.AddParameter("existingPostgresResourceGroup");

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .AsExisting(existingPostgresName, existingPostgresResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(postgres);

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

Para obtener más información sobre cómo tratar AzurePostgreSQL los recursos de servidor flexibles como recursos existentes, consulte Uso de recursos existentesAzure.

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.

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 con Client

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

dotnet add package Aspire.Azure.Npgsql

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

La conexión PostgreSQL puede ser consumida usando la integración cliente llamando al método AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource(connectionName: "postgresdb");

El fragmento de código anterior muestra cómo usar el AddAzureNpgsqlDataSource método para registrar una NpgsqlDataSource instancia que usa Azure la autenticación (Id. de Microsoft Entra). Este "postgresdb" nombre de conexión corresponde a un valor de configuración de cadena de conexión.

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.

Agregar cliente Npgsql con clave Azure

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 AddKeyedAzureNpgsqlDataSource:

builder.AddKeyedAzureNpgsqlDataSource(name: "sales_db");
builder.AddKeyedAzureNpgsqlDataSource(name: "inventory_db");

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

public class ExampleService(
    [FromKeyedServices("sales_db")] NpgsqlDataSource salesDataSource,
    [FromKeyedServices("inventory_db")] NpgsqlDataSource inventoryDataSource)
{
    // 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 .NET AspireAzure integración de Npgsql proporciona varias opciones para configurar la conexión de base de datos en función de los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Cuando se usa una cadena de conexión definida en la ConnectionStrings sección de configuración, se proporciona el nombre de la cadena de conexión al llamar a AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource("postgresdb");

La cadena de conexión se recupera de la sección de configuración ConnectionStrings, por ejemplo, tenga en cuenta la siguiente configuración JSON:

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

Para obtener más información sobre cómo configurar la cadena de conexión, consulte la documentación de la cadena de conexión npgsql.

Uso de proveedores de configuración

La .NET AspireAzure integración de Npgsql admite Microsoft.Extensions.Configuration. Carga el AzureNpgsqlSettings de configuración utilizando la clave Aspire:Azure:Npgsql. Por ejemplo, considere el siguiente archivo appsettings.json que configura algunas de las opciones disponibles:

{
  "Aspire": {
    "Npgsql": {
      "DisableHealthChecks": true,
      "DisableTracing": true
    }
  }
}

Utilice delegados en línea

Puede configurar las opciones en código, pasando el delegado Action<AzureNpgsqlSettings> configureSettings para configurar algunas o todas las opciones inline, por ejemplo para desactivar las comprobaciones de estado desde código:

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

Use la AzureNpgsqlSettings.Credential propiedad para establecer una conexión. Si no se configura ninguna credencial, se usa el DefaultAzureCredential. Cuando la cadena de conexión contiene un nombre de usuario y una contraseña, se omite la credencial.

Client comprobaciones de estado de la 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 hosting también permiten puntos finales de comprobación de estado. Para obtener más información, consulte:

• .NET comprobaciones de estado de la aplicación en C#
• Comprobaciones de mantenimiento 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 /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

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
• Azure Base de datos para PostgreSQL
• .NET AspireAzurePostgreSQLEntity Framework Core integración
• .NET AspirePostgreSQL integración
• .NET.NET Aspire integraciones
• .NET Aspire GitHub repositorio