.NET AspireAzurePostgreSQLEntity Framework Core 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 .NET AspireAzurePostgreSQL integración de hospedaje modela un servidor y una base de datos flexibles como los tipos de PostgreSQL y AzurePostgresFlexibleServerResource. 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 a las API para expresarlos dentro de su proyecto app host, instale el paquete 📦Aspire.Hosting.Azure.EventHubsPostgreSQL NuGet:

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 .NET AspirePostgreSQL y la integración .NET AspirePostgreSQLEntity Framework Core también puede hacerlo con esta integración.

Agregar recursos del servidor AzurePostgreSQL

Después de instalar la integración de hospedaje de .NET AspireAzurePostgreSQL, invoque el método de extensión AddAzurePostgresFlexibleServer en el proyecto de host 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 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 AspirePostgreSQLEntity Framework Core, instale el paquete NuGet 📦Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente PostgreSQL. La integración de cliente .NET AspirePostgreSQLEntity Framework Core registra las instancias de subclase de DbContext deseadas que puede usar para interactuar con PostgreSQL.

dotnet add package Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL

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

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

builder.AddAzureNpgsqlDbContext<YourDbContext>(connectionName: "postgresdb");

El fragmento de código precedente demuestra cómo usar el método AddAzureNpgsqlDbContext para registrar una instancia YourDbContext (que se agrupa para el rendimiento) que usa autenticación Azure (Microsoft Entra ID). Este "postgresdb" nombre de conexión corresponde a un valor de configuración de cadena de conexión.

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

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

Enriquecimiento de un contexto de base de datos Npgsql

Es posible que prefiera usar el método de Entity Framework estándar para obtener un contexto de base de datos y agregarlo al contenedor de inserción de dependencias:

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

Tiene más flexibilidad al crear el contexto de la base de datos de esta manera, por ejemplo:

• Puede reutilizar el código de configuración existente para el contexto de la base de datos sin volver a escribirlo para .NET.NET Aspire.
• Puede usar interceptores Entity Framework Core para modificar operaciones de base de datos.
• Puede optar por no usar la agrupación de contextos Entity Framework Core, lo cual podría funcionar mejor en algunas circunstancias.

Si usa este método, puede mejorar el contexto de la base de datos con reintentos de estilo .NET.NET Aspire, comprobaciones de estado, registro y características de telemetría llamando al método EnrichAzureNpgsqlDbContext:

builder.EnrichAzureNpgsqlDbContext<YourDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

El parámetro settings es una instancia de la clase AzureNpgsqlEntityFrameworkCorePostgreSQLSettings.

Podría necesitar también configurar opciones específicas de Npgsql o registrar una DbContext de otras formas. En este caso, lo hace llamando al EnrichAzureNpgsqlDbContext método de extensión, como se muestra en el ejemplo siguiente:

var connectionString = builder.Configuration.GetConnectionString("postgresdb");

builder.Services.AddDbContextPool<YourDbContext>(
    dbContextOptionsBuilder => dbContextOptionsBuilder.UseNpgsql(connectionString));

builder.EnrichAzureNpgsqlDbContext<YourDbContext>();

Configuración

La .NET AspireAzurePostgreSQL integración de EntityFrameworkCore 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.AddAzureNpgsqlDbContext<YourDbContext>("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 AspireAzurePostgreSQL integración de EntityFrameworkCore Npgsql admite Microsoft.Extensions.Configuration. Carga el AzureNpgsqlEntityFrameworkCorePostgreSQLSettings de configuración utilizando la clave Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Por ejemplo, considere el siguiente archivo appsettings.json que configura algunas de las opciones disponibles:

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

Utilice delegados en línea

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

builder.AddAzureNpgsqlDbContext<YourDbContext>(
    "postgresdb",
    settings => settings.DisableHealthChecks = true);

Como alternativa, puede usar el EnrichAzureNpgsqlDbContext método de extensión para configurar las opciones:

builder.EnrichAzureNpgsqlDbContext<YourDbContext>(
    settings => settings.DisableHealthChecks = true);

Use la AzureNpgsqlEntityFrameworkCorePostgreSQLSettings.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.

Solución de problemas

En raras ocasiones, la Username propiedad no se proporciona y la integración no puede detectarla mediante la identidad administrada de la aplicación, Npgsql produce una excepción con un mensaje similar al siguiente:

Npgsql.PostgresException (0x80004005): 28P01: error de autenticación de contraseña para el usuario ...

En este caso, puede configurar la Username propiedad en la cadena de conexión y usar EnrichAzureNpgsqlDbContext, pasando la cadena de conexión en UseNpgsql:

builder.Services.AddDbContextPool<YourDbContext>(
    options => options.UseNpgsql(newConnectionString));

builder.EnrichAzureNpgsqlDbContext<YourDbContext>();

Configuración de varias clases DbContext

Si desea registrar más de una DbContext con una configuración diferente, puede usar el nombre de la sección de configuración $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". La configuración json tendría el siguiente aspecto:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

A continuación, llamar al método AddNpgsqlDbContext con el parámetro de tipo AnotherDbContext cargaría la configuración desde la sección Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddAzureNpgsqlDbContext<AnotherDbContext>();

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

De forma predeterminada, las integraciones de .NET AspirePostgreSQLEntity Framework Core controlan lo siguiente:

• Añade el método DbContextHealthCheck, que llama al método EF Core de CanConnectAsync. El nombre de la comprobación de estado es el nombre del tipo TContext.
• Se integra con el punto de conexión HTTP /health, que especifica que todas las comprobaciones de estado registradas deben superarse para que la aplicación se considere lista para aceptar tráfico

Observabilidad y telemetría

.NET.NET Aspire integraciones configuran automáticamente el registro de eventos, el seguimiento y las 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 AspirePostgreSQLEntity Framework Core usa las siguientes categorías de registro:

• Microsoft.EntityFrameworkCore.ChangeTracking
• Microsoft.EntityFrameworkCore.Database.Command
• Microsoft.EntityFrameworkCore.Database.Connection
• Microsoft.EntityFrameworkCore.Database.Transaction
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

Seguimiento

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

• Npgsql

Métricas

La integración de .NET AspirePostgreSQLEntity Framework Core emitirá las siguientes métricas mediante OpenTelemetry:

• Microsoft.EntityFrameworkCore:

  • ec_Microsoft_EntityFrameworkCore_active_db_contexts
  • ec_Microsoft_EntityFrameworkCore_total_queries
  • ec_Microsoft_EntityFrameworkCore_queries_per_second
  • ec_Microsoft_EntityFrameworkCore_total_save_changes
  • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
  • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
  • ec_Microsoft_Entity_total_execution_strategy_operation_failures
  • ec_Microsoft_E_execution_strategy_operation_failures_per_second
  • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
  • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

• 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 AspirePostgreSQLEntity Framework Core integración
• .NET.NET Aspire integraciones
• .NET AspireGitHub Repo