Freigeben über

.NET Aspire Oracle Entity Framework Core-Integration

Enthält:Hosting-Integration inbegriffen Hosting-Integration —&— Client Integration inbegriffenClient Integration

Oracle Datenbank ist ein weit verbreitetes relationales Datenbankverwaltungssystem, das sich im Besitz von Oracle befindet und von diesem entwickelt wird. Mit der .NET AspireOracleEntity Framework Core Integration können Sie eine Verbindung mit vorhandenen Oracle Servern herstellen oder neue Server von .NET über das container-registry.oracle.com/database/free Containerimage erstellen.

Hostingintegration

Die .NET AspireOracle Hosting-Integration modelliert den Server als OracleDatabaseServerResource Typ und die Datenbank als OracleDatabaseResource Typ. Um auf diese Typen und APIs zuzugreifen, fügen Sie das 📦Aspire.Hosting.Oracle NuGet-Paket in das App-Hostprojekt hinzu.

dotnet add package Aspire.Hosting.Oracle

Weitere Informationen finden Sie unter dotnet add package oder Verwalten von Paketabhängigkeiten in .NET Anwendungen.

Das Hinzufügen der Oracle-Server- und Datenbankressourcen

Rufen Sie in Ihrem App-Hostprojekt AddOracle auf, um einen Oracle Serverressourcen-Generator hinzuzufügen und zurückzugeben. Verketten Sie einen Aufruf des zurückgegebenen Ressourcen-Generators an AddDatabase, um der Serverressource eine Oracle Datenbank hinzuzufügen:

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...

Anmerkung

Der Oracle Datenbankcontainer kann langsam gestartet werden, daher ist es am besten, eine dauerhafte Lebensdauer zu verwenden, um unnötige Neustarts zu vermeiden. Weitere Informationen finden Sie unter Lebensdauer der Containerressourcen.

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem container-registry.oracle.com/database/free-Image gezeigt, wird ein neuer Oracle-Server auf dem lokalen Computer erstellt. Ein Verweis auf den Oracle Ressourcen-Generator (die oracle Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank wird oracledb benannt und dann dem ExampleProjecthinzugefügt. Die Oracle Ressource enthält eine zufällige password, die mithilfe der CreateDefaultPasswordParameter-Methode generiert wird.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens "oracledb". Weitere Informationen finden Sie unter Containerressourcenlebenszyklus.

Trinkgeld

Wenn Sie lieber eine Verbindung mit einem vorhandenen Oracle Server herstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Verweisen auf vorhandene Ressourcen.

Hinzufügen der Oracle-Ressource mit dem Kennwortparameter

Die Oracle Ressource enthält Standardanmeldeinformationen mit einem zufälligen Kennwort. Oracle unterstützt konfigurationsbasierte Standardwörter mithilfe der Umgebungsvariablen ORACLE_PWD. Wenn Sie ein Kennwort explizit angeben möchten, können Sie es als Parameter angeben:

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

Der vorangehende Code ruft einen Parameter ab, der an die AddOracle-API übergeben werden soll, und weist den Parameter intern der ORACLE_PWD Umgebungsvariable des Oracle Containers zu. Der parameter password wird in der Regel als des geheimen Benutzerschlüssels angegeben:

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

Weitere Informationen finden Sie unter "Externe Parameter".

Die Oracle-Ressource mit Datenvolumen hinzufügen

Rufen Sie die Oracle-Methode auf, um der WithDataVolume-Ressource ein Datenvolume hinzuzufügen:

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...

Das Datenvolume wird verwendet, um die Oracle Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird am Pfad /opt/oracle/oradata im Container Oracle eingehängt, und wenn kein name-Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumen und Details dazu, warum sie gegenüber Bindmounts bevorzugt werden, finden Sie in der Docker Dokumentation: Volumes.

Warnung

Das Kennwort wird im Datenvolume gespeichert. Wenn Sie ein Datenvolumen verwenden und sich das Kennwort ändert, funktioniert es nicht mehr, bis Sie das Volumen löschen.

Hinzufügen Oracle Ressource mit Datenbindungs-Bereitstellung

Rufen Sie die Oracle-Methode auf, um der WithDataBindMount-Ressource eine Datenbindung hinzuzufügen:

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...

Wichtig

Datenbindungs-Mounts verfügen über eingeschränkte Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie für Produktionsumgebungen besser geeignet sind. Bind-Einhängepunkte ermöglichen jedoch direkten Zugriff und die Änderung von Dateien auf dem Hostsystem. Diese sind ideal für die Entwicklung und das Testen, bei denen Echtzeitänderungen erforderlich sind.

Daten-Bind-Einhängepunkte basieren auf dem Dateisystem des Hostcomputers, um die Oracle-Daten über Neustarts von Containern hinweg beibehalten zu können. Die Datenbind-Mount wird auf dem Pfad C:\Oracle\Data unter Windows (oder auf dem Pfad /Oracle/Data auf Unix) auf dem Hostcomputer im Container Oracle bereitgestellt. Weitere Informationen zu Datenbindemontierungen finden Sie in den Docker Dokumentationen: Bindemontierungen.

Hosten von Integritätsprüfungen für Integration

Die Oracle Hostingintegration fügt automatisch eine Integritätsprüfung für die Oracle Ressource hinzu. Die Gesundheitsprüfung überprüft, ob der Oracle-Server läuft und ob eine Verbindung zu ihm hergestellt werden kann.

Die Hostingintegration basiert auf aspNetCore.HealthChecks📦.Oracle NuGet-Paket.

Client-Integration

Sie benötigen eine Oracle-Datenbank und eine Verbindungszeichenfolge für den Zugriff auf die Datenbank. Um mit der .NET AspireOracle-Clientintegration zu beginnen, installieren Sie das NuGet-Paket 📦Aspire.Oracle.EntityFrameworkCore im Projekt der Anwendung, die den Oracle-Client verwendet. Die Oracle Clientintegration registriert eine DbContext Instanz, die Sie für die Interaktion mit Oracleverwenden können.

dotnet add package Aspire.Oracle.EntityFrameworkCore

Oracle-Kunde hinzufügen

Rufen Sie in der Program.cs-Datei Ihres clientnutzenden Projekts die AddOracleDatabaseDbContext-Erweiterungsmethode bei einem beliebigen IHostApplicationBuilder auf, um eine DbContext zur Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddOracleDatabaseDbContext<ExampleDbContext>(connectionName: "oracledb");

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der Oracle-Datenbankressource im App-Hostprojekt verwendet wird. Anders ausgedrückt: Wenn Sie AddDatabase aufrufen und einen Namen von oracledb angeben, sollte dieser Name beim Aufrufen von AddOracleDatabaseDbContextverwendet werden. Weitere Informationen finden Sie unter Hinzufügen von Oracle Server- und Datenbankressourcen.

Anschließend können Sie die DbContext Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Anreichern Oracle Datenbankkontexts

Möglicherweise möchten Sie die standardmäßige Entity Framework-Methode verwenden, um einen Datenbankkontext abzurufen und ihn dem Abhängigkeitsinjektionscontainer hinzuzufügen.

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseOracle(builder.Configuration.GetConnectionString("oracledb")
        ?? throw new InvalidOperationException("Connection string 'oracledb' not found.")));

Anmerkung

Der Verbindungszeichenfolgenname, den Sie an die GetConnectionString-Methode übergeben, muss mit dem Namen übereinstimmen, der beim Hinzufügen der Oracle Ressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Hinzufügen von Oracle Server- und Datenbankressourcen.

Sie haben mehr Flexibilität, wenn Sie den Datenbankkontext auf diese Weise erstellen, z. B.:

  • Sie können vorhandenen Konfigurationscode für den Datenbankkontext wiederverwenden, ohne ihn für .NET.NET Aspireneu zu schreiben.
  • Sie können Entity Framework Core Interceptors verwenden, um Datenbankvorgänge zu ändern.
  • Sie können sich entscheiden, Entity Framework Core Kontextpooling nicht zu verwenden, was unter bestimmten Umständen besser funktioniert.

Wenn Sie diese Methode verwenden, können Sie den Datenbankkontext mit .NET.NET Aspire-style-Wiederholungen, Integritätsüberprüfungen, Protokollierungs- und Telemetriefunktionen verbessern, indem Sie die EnrichOracleDatabaseDbContext-Methode aufrufen:

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

Der settings-Parameter ist eine Instanz der OracleEntityFrameworkCoreSettings Klasse.

Konfiguration

Die .NET AspireOracleEntity Framework Core Integration bietet mehrere Konfigurationsmethoden und -optionen, um die Anforderungen und Konventionen Ihres Projekts zu erfüllen.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, geben Sie beim Aufrufen von builder.AddOracleDatabaseDbContext<TContext>()den Namen der Verbindungszeichenfolge an:

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

Die Verbindungszeichenfolge wird aus dem Konfigurationsabschnitt ConnectionStrings abgerufen:

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

Der EnrichOracleDatabaseDbContext wird den ConnectionStrings-Konfigurationsabschnitt nicht verwenden, da er erwartet, dass eine DbContext registriert ist, wenn er aufgerufen wird.

Weitere Informationen finden Sie in der ODP-Dokumentation.NET.

Verwenden Sie Konfigurationsanbieter

Die .NET AspireOracleEntity Framework Core-Integration unterstützt Microsoft.Extensions.Configuration aus Konfigurationsdateien wie appsettings.json mithilfe des Aspire:Oracle:EntityFrameworkCore Schlüssels. Wenn Sie Ihre Konfigurationen im Abschnitt Aspire:Oracle:EntityFrameworkCore eingerichtet haben, können Sie die Methode einfach aufrufen, ohne Parameter zu übergeben.

Im Folgenden finden Sie ein Beispiel für eine appsettings.json, die einige der verfügbaren Optionen konfiguriert:

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

Trinkgeld

Die Eigenschaft CommandTimeout ist in Sekunden angegeben. Wenn sie wie im vorherigen Beispiel dargestellt festgelegt ist, beträgt das Timeout 30 Sekunden.

Verwenden von Inlinedelegatn

Sie können auch den Action<OracleEntityFrameworkCoreSettings> Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B., um Health Checks im Code zu deaktivieren:

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

oder

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

Konfigurationsoptionen

Hier sind die konfigurierbaren Optionen mit entsprechenden Standardwerten:

Name Beschreibung
ConnectionString Die Verbindungszeichenfolge der Oracle Datenbank, mit der eine Verbindung hergestellt werden soll.
DisableHealthChecks Ein boolescher Wert, der angibt, ob die Datenbankintegritätsprüfung deaktiviert ist oder nicht.
DisableTracing Ein boolescher Wert, der angibt, ob die OpenTelemetry-Ablaufverfolgung deaktiviert ist.
DisableRetry Ein boolescher Wert, der angibt, ob Befehlserneuerungen deaktiviert werden sollen oder nicht.
CommandTimeout Die Zeit in Sekunden, bis der Befehl ausgeführt wird.

Client Integrationsgesundheitsprüfungen

Standardmäßig haben .NET.NET AspireKundenintegrationenIntegritätsprüfungen für alle Dienste aktiviert. Ebenso aktivieren viele .NET.NET AspireHostingintegrationen auch Integritätsprüfungsendpunkte. Weitere Informationen finden Sie unter:

Standardmäßig behandelt die .NET AspireOracleEntity Framework Core-Integration Folgendes:

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als Säulen der Observability bezeichnet werden. Weitere Informationen zur Observability und Telemetrie von Integrationen finden Sie in der Übersicht über Integrationen. Abhängig vom Backend-Service unterstützen einige Integrationen möglicherweise nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefeatures können auch mithilfe der im Abschnitt "Konfiguration " dargestellten Techniken deaktiviert werden.

Protokollierung

Die .NET AspireOracleEntity Framework Core Integration verwendet die folgenden Protokollkategorien:

  • 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

Verfolgung

Die .NET AspireOracleEntity Framework Core Integration gibt die folgenden Tracing-Aktivitäten mittels OpenTelemetryaus:

  • OpenTelemetry. Instrumentation.EntityFrameworkCore

Metriken

Die .NET AspireOracleEntity Framework Core-Integration unterstützt derzeit die folgenden Metriken:

  • Microsoft.EntityFrameworkCore

Siehe auch