Dela via

.NET Aspire Oracle Entity Framework Core integrering

  • Artikel

omfattar:Hostingintegrering och Client integrering

Oracle Database är ett allmänt använt relationsdatabashanteringssystem som ägs och utvecklas av Oracle. Med integreringen .NET AspireOracleEntity Framework Core kan du ansluta till befintliga Oracle servrar eller skapa nya servrar från .NET med container-registry.orcale.com/databse/free containeravbildning.

Värdintegrering

.NET Aspire Oracle integreringen modellerar servern som typ OracleDatabaseServerResource och databasen som typ OracleDatabaseResource. Om du vill komma åt dessa typer och API:er lägger du till 📦Aspire.Hosting.Oracle NuGet-paketet i appvärdprojektet.

dotnet add package Aspire.Hosting.Oracle

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET-applikationer.

Lägga till Oracle server- och databasresurser

I ditt apphostprojekt anropar du AddOracle för att lägga till och returnera en Oracle serverresursbyggare. Länka ett anrop till den returnerade resursbyggaren till AddDatabaseför att lägga till en Oracle databas till serverresursen.

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

Note

Det kan ta lång tid att starta den Oracle databascontainern, så det är bäst att använda en beständig livslängd för att undvika onödiga omstarter. För mer information, se containerresursens livslängd.

När .NET.NET Aspire lägger till en container-image till appvärden, vilket visas i det föregående exemplet med container-registry.oracle.com/database/free-image, skapas en ny Oracle-server på din lokala dator. En referens till din Oracle resursbyggare (variabeln oracle) används för att lägga till en databas. Databasen heter oracledb och läggs sedan till i ExampleProject. Den Oracle resursen innehåller en slumpmässig password som genereras med hjälp av metoden CreateDefaultPasswordParameter.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "oracledb". Mer information finns i Livscykel för containerresurser.

Tips

Om du hellre vill ansluta till en befintlig Oracle server anropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägga till Oracle resurs med lösenordsparameter

Den Oracle resursen innehåller standardautentiseringsuppgifter med ett slumpmässigt lösenord. Oracle stöder konfigurationsbaserade standardlösenord med hjälp av miljövariabeln ORACLE_PWD. När du uttryckligen vill ange ett lösenord kan du ange det som en parameter:

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

Föregående kod hämtar en parameter som skickas till AddOracle-API:et och tilldelar parametern internt till ORACLE_PWD miljövariabeln för Oracle-containern. Parametern password anges vanligtvis som en användarhemlighet:

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

Mer information finns i externa parametrar.

Lägga till Oracle resurs med datavolym

Om du vill lägga till en datavolym i den Oracle resursen anropar du metoden 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...

Datavolymen används för att bevara Oracle data utanför containerns livscykel. Datavolymen monteras på sökvägen /opt/oracle/oradata i containern Oracle och när en name parameter inte anges genereras namnet slumpmässigt. Mer information om datavolymer och varför de föredras framför bindningsmonteringarfinns i dokumentationen Docker: Volymer.

Varning

Lösenordet lagras i datavolymen. När du använder en datavolym och om lösenordet ändras fungerar det inte förrän du tar bort volymen.

Lägg till Oracle resurs med databindningsmontering

Om du vill lägga till en databindningsmontering till den Oracle resursen anropar du metoden 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...

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningar förlitar sig på värddatorns filsystem för att bevara Oracle-datan mellan omstarter av containrar. Databindningsfästet monteras på C:\Oracle\Data-sökvägen i Windows (eller /Oracle/Data på Unix) på värddatorn i Oracle-containern. Mer information om databindningsmonteringar finns i Docker dokument: Bind monteringar.

Utför hälsokontroller för integrationshosting

Oracle värdintegrering lägger automatiskt till en hälsokontroll för den Oracle resursen. Hälsokontrollen verifierar att Oracle-servern körs och att en anslutning kan upprättas till den.

Värdintegrering förlitar sig på 📦 AspNetCore.HealthChecks.Oracle NuGet-paket.

Client integrering

Du behöver en Oracle databas och anslutningssträng för åtkomst till databasen. Kom igång med .NET AspireOracle-klientintegrering genom att installera 📦Aspire.Oracle. EntityFrameworkCore NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder Oracle-klienten. Oracle-klientintegrering registrerar en DbContext instans som du kan använda för att interagera med Oracle.

dotnet add package Aspire.Oracle.EntityFrameworkCore

Lägg till Oracle klient

I den Program.cs filen för ditt klientkrävande projekt anropar du AddOracleDatabaseDbContext-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en DbContext för användning via containern för beroendeinmatning. Metoden tar en parameter för anslutningsnamn.

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

Tips

Parametern connectionName måste matcha namnet som används när du lägger till Oracle-databasresursen i appvärdprojektet. Med andra ord, när du anropar AddDatabase och anger ett namn på oracledb ska samma namn användas när du anropar AddOracleDatabaseDbContext. Mer information finns i Lägg till Oracle server- och databasresurser.

Du kan sedan hämta DbContext-instansen med hjälp av dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägga till Oracle databaskontext med berikning

Om du vill utöka DbContext med ytterligare tjänster, till exempel automatiska återförsök, hälsokontroller, loggning och telemetri, anropar du metoden EnrichOracleDatabaseDbContext:

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

Parametern settings är en instans av klassen OracleEntityFrameworkCoreSettings.

Konfiguration

Den .NET AspireOracleEntity Framework Core integreringen innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet anger du namnet på anslutningssträngen när du anropar builder.AddOracleDatabaseDbContext<TContext>():

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

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration:

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

EnrichOracleDatabaseDbContext använder inte ConnectionStrings-konfigurationsavsnittet eftersom det förväntar sig att en DbContext registreras vid den tidpunkt då den anropas.

Mer information finns i ODP.NET-dokumentationen.

Använda konfigurationsprovidrar

.NET Aspire Oracle Entity Framework Core-integreringen stöder Microsoft.Extensions.Configuration från konfigurationsfiler som appsettings.json med hjälp av Aspire:Oracle:EntityFrameworkCore-nyckeln. Om du har konfigurerat konfigurationerna i avsnittet Aspire:Oracle:EntityFrameworkCore kan du bara anropa metoden utan att skicka någon parameter.

Följande är ett exempel på en appsettings.json som konfigurerar några av de tillgängliga alternativen:

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

Tips

Egenskapen CommandTimeout är i sekunder. När den anges som i föregående exempel är tidsgränsen 30 sekunder.

Använda inline-delegater

Du kan också skicka delegaten Action<OracleEntityFrameworkCoreSettings> för att ställa in vissa eller alla alternativ direkt i koden, till exempel för att inaktivera hälsokontroller från kod.

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

eller

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

Konfigurationsalternativ

Här är de konfigurerbara alternativen med motsvarande standardvärden:

Namn Beskrivning
ConnectionString Anslutningssträngen för Oracle-databasen som man ansluter till.
DisableHealthChecks Ett booleskt värde som anger om databasens hälsokontroll är inaktiverad eller inte.
DisableTracing Ett booleskt värde som anger om OpenTelemetry spårning är inaktiverad eller inte.
DisableRetry Ett booleskt värde som anger om kommandoförsök ska inaktiveras eller inte.
CommandTimeout Tiden i sekunder som man väntar för att kommandot ska köras.

Hälsokontroller

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Som standard hanterar .NET AspireOracleEntity Framework Core-integreringen följande:

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire Oracle Entity Framework Core-integreringen använder följande loggkategorier:

  • 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

Spårning

Integreringen .NET AspireOracleEntity Framework Core genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

  • OpenTelemetry. Instrumentation.EntityFrameworkCore

Mätvärden

Den .NET AspireOracleEntity Framework Core integreringen stöder för närvarande följande mått:

  • Microsoft.EntityFrameworkCore

Se även