Integración de .NET AspirePostgreSQLEntity Framework Core
Incluye: de integración de hospedaje y
Client
PostgreSQL es un potente sistema de bases de datos relacionales de objetos de código abierto con muchos años de desarrollo activo que le ha ganado una sólida reputación de confiabilidad, solidez de características y rendimiento. La integración de .NET AspirePostgreSQLEntity Framework Core proporciona una manera de conectarse a las bases de datos de PostgreSQL existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor de docker.io/library/postgres
.
Integración de hospedaje
La integración de alojamiento de PostgreSQL modela varios recursos PostgreSQL como los tipos siguientes.
Para acceder a estos tipos y APIs y expresarlos como recursos en el proyecto de host de la aplicación , instale el paquete NuGet 📦Aspire.Hosting.PostgreSQL.
dotnet add package Aspire.Hosting.PostgreSQL
Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en aplicaciones .NET.
Agregar PostgreSQL recurso de servidor
En el proyecto host de la aplicación, llame a AddPostgres en la instancia de builder
para agregar un recurso de servidor de PostgreSQL y, a continuación, llame a AddDatabase en la instancia de postgres
para agregar un recurso de base de datos, como se muestra en el ejemplo siguiente:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/library/postgres
, crea una nueva instancia de servidor PostgreSQL en el equipo local. Se usa una referencia al servidor de PostgreSQL y a la instancia de base de datos de PostgreSQL (la variable postgresdb
) para agregar una dependencia al ExampleProject
. El recurso del servidor de PostgreSQL incluye credenciales predeterminadas con un username
de "postgres"
y password
que se generan aleatoriamente mediante el método CreateDefaultPasswordParameter.
El método WithReference configura una conexión en el ExampleProject
denominado "messaging"
. Para obtener más información, consulte Ciclo de Vida de los Recursos de Contenedor.
Propina
Si prefiere conectarse a un servidor PostgreSQL existente, llame a AddConnectionString en su lugar. Para obtener más información, consulte Referencia de recursos existentes.
Agregar recurso PostgreSQL pgAdmin
Al agregar recursos de
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithPgAdmin();
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
El código anterior agrega un contenedor basado en la imagen de docker.io/dpage/pgadmin4
. El contenedor se usa para administrar los recursos de base de datos y servidor de PostgreSQL. El método WithPgAdmin
agrega un contenedor que sirve un panel de administración basado en web para PostgreSQL bases de datos.
Configuración del puerto de host pgAdmin
Para configurar el puerto de host para el contenedor pgAdmin, llame al método WithHostPort en el recurso del servidor PostgreSQL. En el ejemplo siguiente se muestra cómo configurar el puerto de host para el contenedor pgAdmin:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
El código anterior agrega y configura el puerto de host para el contenedor pgAdmin. De lo contrario, se asigna aleatoriamente el puerto de host.
Agregar el recurso pgWeb PostgreSQL
Al añadir recursos PostgreSQL al builder
utilizando el método AddPostgres
, puedes encadenar llamadas a WithPgWeb para agregar el contenedor sosedoff/pgweb. Este contenedor es un cliente multiplataforma para bases de datos PostgreSQL, que proporciona un panel de administración basado en la web. Tenga en cuenta el ejemplo siguiente:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithPgWeb();
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
El código anterior agrega un contenedor basado en la imagen de docker.io/sosedoff/pgweb
. Todas las instancias de PostgresDatabaseResource registradas se usan para crear un archivo de configuración por instancia, y cada configuración está vinculada al directorio de marcadores del contenedor de pgweb. Para obtener más información, consulte documentación de PgWeb: Server marcadores de conexión.
Configuración del puerto de host pgWeb
Para configurar el puerto de host para el contenedor pgWeb, llame al método WithHostPort en el recurso del servidor de PostgreSQL. En el ejemplo siguiente se muestra cómo configurar el puerto de host para el contenedor pgAdmin:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithPgWeb(pgWeb => pgWeb.WithHostPort(5050));
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
El código anterior agrega y configura el puerto de host para el contenedor pgWeb. De lo contrario, se asigna aleatoriamente el puerto de host.
Agregar PostgreSQL recurso de servidor con volumen de datos
Para agregar un volumen de datos al recurso del servidor de PostgreSQL, llame al método WithDataVolume en el recurso del servidor de PostgreSQL:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithDataVolume(isReadOnly: false);
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
El volumen de datos se usa para conservar los datos del servidor de PostgreSQL fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /var/lib/postgresql/data
en el contenedor del servidor PostgreSQL y cuando no se especifica un parámetro name
, el nombre se genera de forma aleatoria. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a enlazar montajes, consulte Docker documentos: Volúmenes.
Agregar recurso del servidor PostgreSQL con montaje de vinculación de datos
Para agregar un montaje de datos vinculado al recurso del servidor PostgreSQL, llame al método WithDataBindMount.
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithDataBindMount(
source: @"C:\PostgreSQL\Data",
isReadOnly: false);
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
Importante
Los montajes de datos tipo bind de tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, haciéndolos más adecuados para entornos de producción. Sin embargo, los montajes enlazados permiten el acceso directo y la modificación de archivos en el sistema host, ideal para el desarrollo y las pruebas donde se requieren cambios en tiempo real.
Las vinculaciones de datos dependen del sistema de archivos de la máquina anfitriona para mantener los datos del servidor de PostgreSQL durante los reinicios de contenedores. El enlace de datos se monta en la ruta C:\PostgreSQL\Data
en Windows (o /PostgreSQL/Data
en Unix) del equipo host en el contenedor del servidor PostgreSQL. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: Enlazar montajes.
Añadir recurso de servidor PostgreSQL con montaje inicial de enlace
Para agregar un enlace de montaje inicial al recurso del servidor PostgreSQL, llame al método WithInitBindMount:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres")
.WithInitBindMount(@"C:\PostgreSQL\Init");
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
El montaje de enlace init se basa en el sistema de archivos del equipo host para inicializar la base de datos del servidor C:\PostgreSQL\Init
en Windows (o en /PostgreSQL/Init
en Unix) en la ruta del equipo host dentro del contenedor del servidor PostgreSQL.
Añada el recurso de servidor PostgreSQL con parámetros
Si desea proporcionar explícitamente el nombre de usuario y la contraseña usados por la imagen de contenedor, puede proporcionar estas credenciales como parámetros. Considere el siguiente ejemplo alternativo:
var builder = DistributedApplication.CreateBuilder(args);
var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);
var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(postgresdb);
// After adding all resources, run the app...
Para obtener más información sobre cómo proporcionar parámetros, consulte Parámetros externos.
Integración de comprobaciones de salud de alojamiento
La integración de hospedaje de PostgreSQL agrega automáticamente una comprobación de estado para el recurso del servidor de PostgreSQL. La comprobación de estado comprueba que el PostgreSQL servidor se está ejecutando y que se puede establecer una conexión a él.
La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.Npgsql.
integración de Client
Para empezar a trabajar con la integración de cliente de .NET AspirePostgreSQLEntity Framework Core, instale el 📦Aspire. Npgsql.EntityFrameworkCore.PostgreSQL paquete NuGet en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa 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 cliente, llame al método de extensión AddNpgsqlDbContext en cualquier IHostApplicationBuilder para registrar su subclase 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 inserción de dependencias, consulte .NET inserció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 obtiene de la sección de configuración ConnectionStrings
.
{
"ConnectionStrings": {
"pgdb": "Host=myserver;Database=test"
}
}
El EnrichNpgsqlDbContext
no usará 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 .NET AspirePostgreSQLEntity Framework Core es compatible con 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 el esquema completo de integración de cliente PostgreSQLEntity Framework CoreJSON, consulte Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.
Utilice delegados en línea
También puede pasar el delegado de Action<NpgsqlEntityFrameworkCorePostgreSQLSettings>
para configurar algunas o todas las opciones en línea, por ejemplo, para establecer 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 un 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:
- .NET comprobaciones de estado de la aplicación en C#
- comprobaciones de estado de en ASP.NET Core
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 verificación de salud es el nombre del tipoTContext
. - Se integra con el punto de conexión HTTP de
/health
, que especifica que todas las comprobaciones de estado registradas deben ser superadas 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 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
Consulte también
- PostgreSQL documentos
- de integración de .NET AspireAzurePostgreSQLEntity Framework Core
- Integraciones .NET.NET Aspire
- .NET Aspire GitHub repo del repositorio