.NET Aspire Oracle Entity Framework Core-Integration

Artikel
01/27/2025

umfasst:Hosting-Integration und Client Integration

Oracle Datenbank- ist ein weit verbreitetes relationales Datenbankverwaltungssystem, das von Oraclebesessen und entwickelt wird. Mit der .NET AspireOracleEntity Framework Core-Integration können Sie eine Verbindung mit vorhandenen Oracle-Servern herstellen oder neue Server über .NET mit dem container-registry.orcale.com/databse/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 📦AspireHostingOracle NuGet-Paket im Projekt des App-Hosts hinzu.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Oracle

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

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 persistente Lebensdauer zu verwenden, um unnötige Neustarts zu vermeiden. Weitere Informationen finden Sie unter Containerressourcenlebensdauer.

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 Referenzieren vorhandener 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 WithDataVolume-Methode auf, um der Oracle-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 Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt 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 WithDataBindMount-Methode auf, um der Oracle-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

Daten Bindungsmontagen haben eingeschränkte Funktionalität im Vergleich zu Volumes, die bessere Leistungen in Bezug auf Leistung, Portabilität und Sicherheit bieten, was sie für Produktionsumgebungen besser geeignet macht. 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 Daten-Bind-Mounts finden Sie in der Docker-Dokumentation: Bind Mounts.

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 den 📦 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 clientverbrauchenden Projekt, also das Projekt für die Anwendung, die den Oracle Client verwendet. Die Oracle Clientintegration registriert eine DbContext Instanz, die Sie für die Interaktion mit Oracleverwenden können.

.NET CLI
PackageReference

dotnet add package Aspire.Oracle.EntityFrameworkCore

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

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 Oracle Server- und Datenbankressourcen hinzufügen.

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.

Mit Anreicherung des Oracle-Datenbankkontexts hinzufügen

Um die DbContext durch zusätzliche Dienste wie automatische Wiederholungen, Gesundheitsprüfungen, Protokollierung und Telemetrie zu erweitern, rufen Sie die EnrichOracleDatabaseDbContext-Methode auf.

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    connectionName: "oracledb",
    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.NET-Dokumentation.

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.

Gesundheitschecks

Standardmäßig aktivieren .NET.NET Aspire-Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

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

Überprüft, ob die OracleEntityFrameworkCoreSettings.DisableHealthCheckstrueist.
Wenn ja, fügt es die DbContextHealthCheckhinzu, die die CanConnectAsync-Methode von EF Coreaufruft. Der Name des Gesundheitschecks ist der Name der TContext Art.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Konfigurationen für Protokollierung, Ablaufverfolgung und Metriken ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie in der Übersicht über .NET.NET Aspire 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. Telemetrie-Features können auch mithilfe der im Abschnitt Configuration 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

Freigeben über

.NET Aspire Oracle Entity Framework Core-Integration

Hostingintegration

Das Hinzufügen der Oracle-Server- und Datenbankressourcen

Hinzufügen der Oracle-Ressource mit dem Kennwortparameter

Die Oracle-Ressource mit Datenvolumen hinzufügen

Hinzufügen Oracle Ressource mit Datenbindungs-Bereitstellung

Hosten von Integritätsprüfungen für Integration

Client-Integration

Oracle-Kunde hinzufügen

Mit Anreicherung des Oracle-Datenbankkontexts hinzufügen

Konfiguration

Verwenden Sie eine Verbindungszeichenfolge

Verwenden Sie Konfigurationsanbieter

Verwenden von Inlinedelegatn

Konfigurationsoptionen

Gesundheitschecks

Observability und Telemetrie

Protokollierung

Verfolgung

Metriken

Siehe auch

Zusätzliche Ressourcen