integrace .NET AspireOracleEntity Framework Core

Článek
01/27/2025

zahrnuje:integraci hostování a integraci Client

Oracle Database je široce používaný systém pro správu relačních databází, který vlastní a vyvíjí Oracle. Integrace .NET AspireOracleEntity Framework Core umožňuje připojit se k existujícím serverům Oracle nebo vytvořit nové servery z .NET s imagí kontejneru container-registry.orcale.com/databse/free.

Integrace hostování

.NET Aspire Oracle integrace hostování modeluje server jako typ OracleDatabaseServerResource a databázi jako typ OracleDatabaseResource. Pokud chcete získat přístup k těmto typům a rozhraním API, přidejte balíček NuGet 📦Aspire.Hosting.Oracle do projektu hostitele aplikace .

rozhraní příkazového řádku
Reference balíčku

dotnet add package Aspire.Hosting.Oracle

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

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v aplikacích .NET.

Přidání Oracle serverových a databázových prostředků

V projektu hostitele aplikace zavolejte AddOracle a přidejte a vraťte tvůrce prostředků serveru Oracle. Zřetězte volání na tvůrce prostředků vráceného na AddDatabasea přidejte databázi Oracle do prostředku serveru:

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

Poznámka

Kontejner databáze Oracle může být pomalý, takže je nejlepší použít trvalou dobu života, abyste se vyhnuli zbytečným restartováním. Další informace najdete v tématu Životnost prostředků kontejneru.

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí container-registry.oracle.com/database/free, vytvoří na místním počítači nový server Oracle. K přidání databáze se používá odkaz na tvůrce zdrojů Oracle (proměnná oracle). Databáze se jmenuje oracledb a pak se přidá do ExampleProject. Prostředek Oracle obsahuje náhodný password vygenerovaný pomocí metody CreateDefaultPasswordParameter.

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "oracledb". Další informace naleznete v tématu životní cyklus pro zdroje kontejneru.

Rada

Pokud byste se raději připojili k existujícímu serveru Oracle, volejte místo toho AddConnectionString. Další informace naleznete v tématu Odkaz na existující prostředky.

Přidejte prostředek Oracle s parametrem hesla

Prostředek Oracle obsahuje výchozí přihlašovací údaje s náhodným heslem. Oracle podporuje výchozí hesla založená na konfiguraci pomocí environmentální proměnné ORACLE_PWD. Pokud chcete zadat heslo explicitně, můžete ho zadat jako parametr:

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

Předchozí kód získá k předání do rozhraní AddOracle API parametr a ten následně interně přiřadí do proměnné prostředí ORACLE_PWD kontejneru Oracle. Parametr password je obvykle určen jako tajný kód uživatele:

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

Další informace naleznete v tématu Externí parametry.

Přidat prostředek Oracle s datovým objemem

Pokud chcete do prostředku Oracle přidat datový svazek, zavolejte metodu 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...

Objem dat se používá k zachování Oracle dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /opt/oracle/oradata v kontejneru Oracle a když není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před připojení pomocí vazeb, najdete v dokumentaci Docker: Svazky.

Varování

Heslo je uloženo v datovém svazku. Při použití datového svazku, pokud se heslo změní, nebude fungovat, dokud svazek neodstraníte.

Přidání prostředku Oracle s připojením vazby dat

Chcete-li přidat vazbu datového úložiště k prostředku Oracle, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Připojení pomocí vazeb však umožňují přímý přístup a úpravy souborů v hostitelském systému, což je ideální pro vývoj a testování, kde jsou potřebné změny v reálném čase.

Datové svazky typu bind využívají systém souborů hostitelského počítače k zachování Oracle dat při restartování kontejneru. Úložiště dat je připojeno na C:\Oracle\Data ve Windows (nebo na /Oracle/Data na Unix) v hostitelském systému v rámci kontejneru Oracle. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Hostování kontrol stavu integrace

Integrace hostování Oracle automaticky přidá kontrolu stavu prostředku Oracle. Kontrola stavu ověřuje, jestli je server Oracle spuštěný a že se k němu dá navázat připojení.

Integrace hostování spoléhá na 📦 AspNetCore.HealthChecks.Oracle balíček NuGet.

integrace Client

Pro přístup k databázi potřebujete Oracle databázi a připojovací řetězec. Pokud chcete začít s integrací klienta .NET AspireOracle, nainstalujte 📦Aspire.Oracle. EntityFrameworkCore balíček NuGet v projektu využívajícím klienta, tj. projekt aplikace, která používá klienta Oracle. Integrace klienta Oracle registruje instanci DbContext, kterou můžete použít k interakci s Oracle.

rozhraní příkazového řádku
Reference balíčku

dotnet add package Aspire.Oracle.EntityFrameworkCore

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

Přidejte klienta Oracle

V souboru Program.cs klientského projektu zavolejte metodu rozšíření AddOracleDatabaseDbContext na libovolném IHostApplicationBuilder a zaregistrujte DbContext pro použití prostřednictvím kontejneru injekce závislostí. Metoda přebírá parametr názvu připojení.

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

Rada

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku databáze Oracle do hostitelského projektu aplikace. Jinými slovy, když voláte AddDatabase a zadáte jméno oracledb, ten samý název by měl být použit při volání AddOracleDatabaseDbContext. Další informace najdete v tématu Přidání Oracle serverových a databázových prostředků.

Potom můžete načíst instanci DbContext pomocí dependency injection. Pro načtení připojení z příkladové služby například:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání kontextu databáze Oracle s obohacením

Pokud chcete rozšířit DbContext dalšími službami, jako jsou automatické opakování, kontroly stavu, protokolování a telemetrie, zavolejte metodu EnrichOracleDatabaseDbContext:

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

Parametr settings je instance třídy OracleEntityFrameworkCoreSettings.

Konfigurace

Integrace .NET AspireOracleEntity Framework Core poskytuje několik přístupů a možností konfigurace pro splnění požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings zadáte název připojovacího řetězce při volání builder.AddOracleDatabaseDbContext<TContext>():

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

Připojovací řetězec se načte z konfiguračního oddílu ConnectionStrings.

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

EnrichOracleDatabaseDbContext nevyužije konfigurační oddíl ConnectionStrings, protože očekává, že DbContext bude registrován v okamžiku, kdy se volá.

Další informace naleznete vODP dokumentaci .

Použití zprostředkovatelů konfigurace

Integrace .NET AspireOracleEntity Framework Core podporuje Microsoft.Extensions.Configuration z konfiguračních souborů, jako je appsettings.json pomocí klíče Aspire:Oracle:EntityFrameworkCore. Pokud jste nastavili konfigurace v oddílu Aspire:Oracle:EntityFrameworkCore, stačí volat metodu bez předání jakéhokoli parametru.

Následuje příklad appsettings.json, který konfiguruje některé z dostupných možností:

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

Rada

Vlastnost CommandTimeout je v sekundách. Pokud je nastavený jako v předchozím příkladu, časový limit je 30 sekund.

Používejte vložené delegáty

Můžete také předat delegáta Action<OracleEntityFrameworkCoreSettings> a nastavit některé nebo všechny možnosti přímo, například zakázat kontroly stavu přímo v kódu.

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

nebo

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

Možnosti konfigurace

Tady jsou konfigurovatelné možnosti s odpovídajícími výchozími hodnotami:

Jméno	Popis
`ConnectionString`	Připojovací řetězec Oracle databáze, ke které se chcete připojit.
`DisableHealthChecks`	Logická hodnota, která označuje, jestli je kontrola stavu databáze zakázaná nebo ne.
`DisableTracing`	Logická hodnota označující, jestli je trasování OpenTelemetry zakázané nebo ne.
`DisableRetry`	Logická hodnota, která označuje, jestli se mají opakování příkazů zakázat, nebo ne.
`CommandTimeout`	Doba v sekundách čekání na spuštění příkazu.

Kontroly stavu

Ve výchozím nastavení integrace .NET.NET Aspire aktivují kontroly stavu pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

Integrace .NET AspireOracleEntity Framework Core ve výchozím nastavení zpracovává následující:

Zkontroluje, jestli je OracleEntityFrameworkCoreSettings.DisableHealthCheckstrue.
Pokud ano, přidá DbContextHealthCheck, které volá metodu CanConnectAsync objektu EF Core. Název kontroly zdraví je odvozen od názvu typu TContext.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace pro protokolování, trasování a metriky, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireOracleEntity Framework Core používá následující kategorie protokolů:

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

Trasování

Integrace .NET AspireOracleEntity Framework Core pomocí OpenTelemetryvygeneruje následující aktivity trasování:

OpenTelemetry. Instrumentation.EntityFrameworkCore

Metriky

Integrace .NET AspireOracleEntity Framework Core aktuálně podporuje následující metriky:

Microsoft.EntityFrameworkCore

Viz také

Oracle databáze
Dokumentace k databázi Oracle
docs
integrace .NET.NET Aspire
.NET Aspire GitHub úložiště

Sdílet prostřednictvím

integrace .NET AspireOracleEntity Framework Core

Integrace hostování

Přidání Oracle serverových a databázových prostředků

Přidejte prostředek Oracle s parametrem hesla

Přidat prostředek Oracle s datovým objemem

Přidání prostředku Oracle s připojením vazby dat

Hostování kontrol stavu integrace

integrace Client

Přidejte klienta Oracle

Přidání kontextu databáze Oracle s obohacením

Konfigurace

Použijte připojovací řetězec

Použití zprostředkovatelů konfigurace

Používejte vložené delegáty

Možnosti konfigurace

Kontroly stavu

Pozorovatelnost a telemetrie

Protokolování

Trasování

Metriky

Viz také

Další materiály