.NET Aspire Azure PostgreSQL integración
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 esActiveDirectoryAuth
habilitado yPasswordAuth
deshabilitado. -
availabilityZone
: zona de disponibilidad del servidor PostgreSQL. El valor predeterminado es1
. -
backup
: la configuración de copia de seguridad del servidor PostgreSQL. El valor predeterminado esBackupRetentionDays
establecido en7
yGeoRedundantBackup
establecido enDisabled
. -
highAvailability
: configuración de alta disponibilidad del servidor PostgreSQL. El valor predeterminado esDisabled
. -
storage
: configuración de almacenamiento del servidor PostgreSQL. El valor predeterminadoStorageSizeGB
se establece en32
. -
version
: la versión del servidor PostgreSQL. El valor predeterminado es16
. -
sku
: SKU del servidor PostgreSQL. El valor predeterminado esStandard_B1ms
. -
tags
: etiquetas del servidor de PostgreSQL. El valor predeterminado esaspire-resource-name
establecido en el nombre del recurso de Aspire, en este casopostgres-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:
- 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 deExample value
.
- El parámetro
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
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:
- .NET comprobaciones de estado de la aplicación en C#
- comprobaciones 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
/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.