integración de .NET AspireOracleEntity Framework Core

Incluye:integración de hospedaje e integración Client

Oracle Database es un sistema de administración de bases de datos relacionales ampliamente utilizado que posee y desarrolla Oracle. La integración de .NET AspireOracleEntity Framework Core permite conectarte a servidores Oracle existentes o crear nuevos servidores desde .NET con la imagen de contenedor de container-registry.oracle.com/database/free.

Integración de hospedaje

El .NET AspireOracle que hospeda la integración modela el servidor como el tipo de OracleDatabaseServerResource y la base de datos como el tipo de OracleDatabaseResource. Para acceder a estos tipos y API, agregue el paquete NuGet 📦Aspire.Hosting.Oracle en el proyecto del host de la aplicación .

.NET CLI

dotnet add package Aspire.Hosting.Oracle

PackageReference

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

Para obtener más información, consulte dotnet add package o administrar las dependencias de paquetes en aplicaciones .NET.

Añadir recursos de servidor y base de datos de Oracle

En el proyecto host de la aplicación, llame a AddOracle para agregar y devolver un generador de recursos de servidor Oracle. Encadene una llamada al generador de recursos devuelto para AddDatabase, para agregar una base de datos de Oracle al recurso de servidor:

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracledb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb);
       .WaitFor(oracledb);

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

Nota

El contenedor de base de datos de Oracle puede ser lento de iniciarse, por lo que es mejor usar un duración de persistente para evitar reinicios innecesarios. Para obtener más información, consulte vida útil de recurso de contenedor.

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 container-registry.oracle.com/database/free, crea un nuevo servidor Oracle en el equipo local. Se usa una referencia al generador de recursos de Oracle (la variable oracle) para agregar una base de datos. La base de datos se denomina oracledb y, a continuación, se agrega al ExampleProject. El recurso Oracle incluye un password aleatorio generado mediante el método CreateDefaultPasswordParameter.

El método WithReference configura una conexión en el ExampleProject denominado "oracledb". Para obtener más información, consulte ciclo de vida de los recursos de contenedor.

Consejo (if context refers to advice)

Si prefiere conectarse a un servidor Oracle existente, llame a AddConnectionString en su lugar. Para obtener más información, vea Consulte los recursos existentes.

Agregar el recurso Oracle con el parámetro de contraseña

El recurso Oracle incluye credenciales predeterminadas con una contraseña aleatoria. Oracle admite contraseñas predeterminadas basadas en la configuración mediante la variable de entorno ORACLE_PWD. Cuando quiera proporcionar una contraseña explícitamente, puede proporcionarla como parámetro:

var password = builder.AddParameter("password", secret: true);

var oracle = builder.AddOracle("oracle", password)
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracledb");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(oracledb)
                       .WaitFor(oracledb);

El código anterior obtiene un parámetro para pasar a la API de AddOracle y asigna internamente el parámetro a la variable de entorno ORACLE_PWD del contenedor de Oracle. El parámetro password normalmente se especifica como secreto de usuario:

{
  "Parameters": {
    "password": "Non-default-P@ssw0rd"
  }
}

Para obtener más información, vea Parámetros externos.

Añadir recurso Oracle con volumen de datos

Para agregar un volumen de datos al recurso de Oracle, llame al método WithDataVolume:

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithDataVolume()
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracle");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb)
       .WaitFor(oracledb);

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

El volumen de datos se utiliza para persistir los datos de Oracle fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /opt/oracle/oradata en el contenedor de Oracle y, cuando no se proporciona un parámetro name, el nombre se genera aleatoriamente. Para obtener más información sobre los volúmenes de datos y detalles sobre por qué se prefieren a montajes de enlace, consulte Docker documentos, Volúmenes.

Advertencia

La contraseña se almacena en el volumen de datos. Al usar un volumen de datos y si cambia la contraseña, no funcionará hasta que elimine el volumen.

Adición del recurso Oracle con montaje de enlace de datos

Para agregar un montaje de vinculación de datos al recurso de Oracle, llame al método WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithDataBindMount(source: @"C:\Oracle\Data");

var oracledb = oracle.AddDatabase("oracledb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb)
       .WaitFor(oracledb);

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

Importante

Los montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen un mejor rendimiento, portabilidad y seguridad, haciéndolos más adecuados para entornos de producción. Sin embargo, los bind mounts permiten el acceso directo y la modificación de archivos en el sistema host, ideal para el desarrollo y las pruebas en los que se requieren cambios en tiempo real.

Los montajes de ligadura de datos dependen del sistema de archivos de la máquina anfitriona para conservar los datos de Oracle a través de los reinicios del contenedor. El montaje de enlace de datos se monta en la ruta C:\Oracle\Data en Windows (o /Oracle/Data en Unix) en la máquina host en el contenedor de Oracle. Para obtener más información sobre los montajes de enlace de datos, consulte los documentos Docker: montajes de enlace.

Hospedaje de comprobaciones de estado de integración

La integración de hospedaje Oracle agrega automáticamente una comprobación de estado para el recurso Oracle. La comprobación de estado comprueba que el Oracle 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.Oracle.

integración de Client

Necesita una base de datos Oracle y una cadena de conexión para acceder a la base de datos. Para empezar a trabajar con la integración de cliente de .NET AspireOracle, instale el paquete NuGet 📦Aspire.Oracle.EntityFrameworkCore en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente de Oracle. La integración de cliente Oracle registra una instancia de DbContext que puede usar para interactuar con Oracle.

.NET CLI

dotnet add package Aspire.Oracle.EntityFrameworkCore

PackageReference

<PackageReference Include="Aspire.Oracle.EntityFrameworkCore"
                  Version="*" />

Agregar cliente Oracle

En el archivo Program.cs del proyecto cliente-consumidor, llame al método de extensión AddOracleDatabaseDbContext en cualquier IHostApplicationBuilder para registrar un 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.AddOracleDatabaseDbContext<ExampleDbContext>(connectionName: "oracledb");

Consejo (if context refers to advice)

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso de base de datos Oracle en el proyecto host de la aplicación. Es decir, cuando se llama a AddDatabase y se proporciona un nombre de oracledb ese mismo nombre se debe usar al llamar a AddOracleDatabaseDbContext. Para obtener más información, consulte Agregar Oracle recursos de servidor y base de datos.

A continuación, puede recuperar la instancia de DbContext mediante inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(ExampleDbContext context)
{
    // Use database context...
}

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

Enriquecer el contexto de la base de datos Oracle

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<ExampleDbContext>(options =>
    options.UseOracle(builder.Configuration.GetConnectionString("oracledb")
        ?? throw new InvalidOperationException("Connection string 'oracledb' 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 Oracle en el proyecto host de la aplicación. Para obtener más información, consulte Agregar Oracle recursos de servidor y base de datos.

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

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

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

Configuración

La integración de .NET AspireOracleEntity 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 a builder.AddOracleDatabaseDbContext<TContext>():

builder.AddOracleDatabaseDbContext<ExampleDbContext>("oracleConnection");

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

{
  "ConnectionStrings": {
    "oracleConnection": "Data Source=TORCL;User Id=OracleUser;Password=Non-default-P@ssw0rd;"
  }
}

El EnrichOracleDatabaseDbContext no usará la sección de configuración de ConnectionStrings, ya que espera que un DbContext esté registrado en el momento en que se llama.

Para obtener más información, consulte la documentación ODP.NET.

Uso de proveedores de configuración

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

A continuación se muestra un ejemplo de un appsettings.json que configura algunas de las opciones disponibles:

{
  "Aspire": {
    "Oracle": {
      "EntityFrameworkCore": {
        "DisableHealthChecks": true,
        "DisableTracing": true,
        "DisableRetry": false,
        "CommandTimeout": 30
      }
    }
  }
}

Consejo (if context refers to advice)

La propiedad CommandTimeout se mide en segundos. Cuando se establece como se muestra en el ejemplo anterior, el tiempo de espera es de 30 segundos.

Usa delegados en línea

También puede pasar el delegado de Action<OracleEntityFrameworkCoreSettings> para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar las verificaciones de salud desde el código:

builder.AddOracleDatabaseDbContext<ExampleDbContext>(
    "oracle",
    static settings => settings.DisableHealthChecks  = true);

o

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    static settings => settings.DisableHealthChecks  = true);

Opciones de configuración

Estas son las opciones configurables con los valores predeterminados correspondientes:

Nombre	Descripción
ConnectionString	Cadena de conexión de la base de datos de Oracle a la que se va a conectar.
DisableHealthChecks	Valor booleano que indica si la comprobación de estado de la base de datos está deshabilitada o no.
DisableTracing	Valor booleano que indica si el seguimiento de OpenTelemetry está deshabilitado o no.
DisableRetry	Valor booleano que indica si los reintentos de comandos deben deshabilitarse o no.
CommandTimeout	Tiempo en segundos para esperar a que se ejecute el comando.

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, la integración de .NET AspireOracleEntity Framework Core controla lo siguiente:

• Comprueba si el OracleEntityFrameworkCoreSettings.DisableHealthChecks es true.
• Si es así, agrega el DbContextHealthCheck, que llama al método EF Core de CanConnectAsync. El nombre de la verificación de salud es el nombre del tipo TContext.

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 AspireOracleEntity 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.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

Trazado

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

• OpenTelemetry. Instrumentation.EntityFrameworkCore

Métricas

La integración de .NET AspireOracleEntity Framework Core admite actualmente las siguientes métricas:

• Microsoft.EntityFrameworkCore

Consulte también

• Base de datos Oracle
• Oracle Documentación de la base de datos
• Entity Framework Core documentos
• .NET .NET Aspire integraciones
• del repositorio