Compartir a través de

integración de .NET AspireAzurePostgreSQLEntity Framework Core

  • Artículo

Incluye:integración de hospedaje y 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

El .NET AspireAzurePostgreSQL hospedar modelos de integración de un servidor y una base de datos flexibles PostgreSQL como tipos de 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 e interfaces de programación de aplicaciones (API) para expresarlos como recursos en el host de la aplicación del proyecto , instale el paquete NuGet 📦Aspire.Hosting.Azure.PostgreSQL.

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

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 PostgreSQL que se va a implementar como un AzurePostgres flexible Server.

Importante

De forma predeterminada, AddAzurePostgresFlexibleServer configura la autenticación de la ID de Microsoft Entra. 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.

integración de Client

Para empezar a trabajar con la integración del cliente de .NET AspirePostgreSQLEntity Framework Core, instale el paquete NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL en el proyecto cliente, es decir, en el proyecto de la aplicación que utiliza el cliente de 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.Npgsql.EntityFrameworkCore.PostgreSQL

Añadir contexto de base de datos Npgsql

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

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

Propina

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 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.")));

Nota

El nombre de la cadena de conexión que se pasa al método GetConnectionString 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.

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 Entity Framework Core interceptores para modificar las 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 EnrichNpgsqlDbContext:

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

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

Configuración

La integración de .NET AspirePostgreSQLEntity Framework Core 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, proporcione el nombre de la cadena de conexión al llamar al método AddNpgsqlDbContext:

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

La cadena de conexión se recupera de la sección de configuración denominada ConnectionStrings.

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

El EnrichNpgsqlDbContext no hará uso de la sección de configuración de ConnectionStrings, ya que espera que se registre un DbContext en el momento en que se le llama.

Para obtener más información, consulte el ConnectionString .

Uso de proveedores de configuración

La integración de .NET AspirePostgreSQLEntity Framework Core admite Microsoft.Extensions.Configuration. Carga el NpgsqlEntityFrameworkCorePostgreSQLSettings desde archivos de configuración como appsettings.json mediante la clave Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Si ha configurado las configuraciones en la sección Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, simplemente puede llamar al método sin pasar ningún parámetro.

En el ejemplo siguiente se muestra un archivo appsettings.json que configura algunas de las opciones disponibles:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "Host=myserver;Database=postgresdb",
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Para obtener el esquema de integración de cliente completo PostgreSQLEntity Framework CoreJSON, consulte Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Usa delegados en línea

También puede pasar el delegado de Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> para configurar algunas o todas las opciones directamente, por ejemplo, para configurar el ConnectionString:

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

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.AddNpgsqlDbContext<AnotherDbContext>();

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 también habilitan los puntos de conexión de comprobación de estado. Para obtener más información, consulte:

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

  • Agrega el DbContextHealthCheck, que llama al método EF Core de CanConnectAsync. El nombre de la comprobación de salud es el nombre del tipo TContext.
  • 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 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

Rastreo

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

Agregar cliente Npgsql autenticado Azure

De forma predeterminada, al llamar a AddAzurePostgresFlexibleServer en la integración de hospedaje de PostgreSQL, requiere 📦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 del cliente y Azure.Identity:

builder.AddNpgsqlDbContext<YourDbContext>(
    "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