integratie van .NET AspireOracleEntity Framework Core

omvat:hostingintegratie en Client integratie

Oracle Database is een veelgebruikt relationeel databasebeheersysteem dat eigendom is van en ontwikkeld door Oracle. Met de .NET AspireOracleEntity Framework Core-integratie kunt u verbinding maken met bestaande Oracle-servers of nieuwe servers maken op basis van .NET met de container-registry.oracle.com/database/free containerimage.

Hostingintegratie

De .NET AspireOracle die als host fungeert voor integratie wordt de server als het OracleDatabaseServerResource-type en de database als het OracleDatabaseResource-type. Als u toegang wilt krijgen tot deze typen en API's, voegt u het 📦Aspire.Hosting.Oracle NuGet-pakket toe in het app-hostproject.

.NET CLI

dotnet add package Aspire.Hosting.Oracle

PackageReference

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Oracle server- en databasebronnen toevoegen

Roep in uw app-hostproject AddOracle aan om een Oracle serverresourcebouwer toe te voegen en te retourneren. Koppel een aanroep naar de geretourneerde resourcebouwer aan AddDatabaseom een Oracle-database toe te voegen aan de serverresource:

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

Notitie

De Oracle databasecontainer kan traag worden gestart, dus u kunt het beste een permanente levensduur gebruiken om onnodige herstarts te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de container-registry.oracle.com/database/free-installatiekopie, wordt er een nieuwe Oracle server op uw lokale computer gemaakt. Een verwijzing naar de Oracle resourcebouwer (de oracle variabele) wordt gebruikt om een database toe te voegen. De database heeft de naam oracledb en wordt vervolgens toegevoegd aan de ExampleProject. De Oracle-resource bevat een willekeurige password gegenereerd met behulp van de methode CreateDefaultPasswordParameter.

De methode WithReference configureert een verbinding in de ExampleProject met de naam "oracledb". Zie levenscyclus van containerresourcesvoor meer informatie.

Fooi

Als u liever verbinding wilt maken met een bestaande Oracle-server, roept u in plaats daarvan AddConnectionString aan. Raadpleeg Bestaande middelenvoor meer informatie.

Resource toevoegen Oracle met wachtwoordparameter

De Oracle-resource bevat standaardinloggegevens met een willekeurig wachtwoord. Oracle ondersteunt op configuratie gebaseerde standaardwachtwoorden met behulp van de omgevingsvariabele ORACLE_PWD. Wanneer u een wachtwoord expliciet wilt opgeven, kunt u dit als parameter opgeven:

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

Met de voorgaande code wordt een parameter opgehaald die moet worden doorgegeven aan de AddOracle-API en wordt de parameter intern toegewezen aan de omgevingsvariabele ORACLE_PWD van de Oracle-container. De parameter password wordt meestal opgegeven als een gebruikersgeheim:

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

Zie Externe parametersvoor meer informatie.

Oracle resource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de Oracle-resource, roept u de methode WithDataVolume aan:

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

Het gegevensvolume wordt gebruikt om de Oracle gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /opt/oracle/oradata pad in de Oracle container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Zie voor meer informatie over datavolumes en details over waarom ze de voorkeur hebben boven Docker.

Waarschuwing

Het wachtwoord wordt opgeslagen in het gegevensvolume. Wanneer u een gegevensvolume gebruikt en als het wachtwoord wordt gewijzigd, werkt het pas als u het volume verwijdert.

Oracle resource toevoegen met koppeling voor gegevensbinding

Als u een koppeling voor gegevensbinding wilt toevoegen aan de Oracle-resource, roept u de WithDataBindMount methode aan:

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

Belangrijk

Data bind-mounts hebben een beperkte functionaliteit in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor gebruik in productieomgevingen. Bind-mounts bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waarbij realtime wijzigingen nodig zijn.

Koppelen van gegevensbindingen zijn afhankelijk van het bestandssysteem van de hostcomputer om de Oracle gegevens bij het opnieuw opstarten van de container te behouden. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\Oracle\Data in Windows (of /Oracle/Data op Unix) op de hostcomputer in de Oracle container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Gezondheidscontroles voor hostingintegratie

De Oracle hostingintegratie voegt automatisch een statuscontrole toe voor de Oracle resource. De gezondheidscontrole controleert of de Oracle-server draait en of er een verbinding mee kan worden gemaakt.

De hostingintegratie is afhankelijk van de 📦 AspNetCore.HealthChecks.Oracle NuGet-pakket.

integratie van Client

U hebt een Oracle-database en verbindingsreeks nodig voor toegang tot de database. Installeer het NuGet-pakket .NET Aspire in het project dat de client integreert, dat wil zeggen het project voor de toepassing die de Oracle-client gebruikt, om te beginnen met de 📦Aspire-clientintegratie. De Oracle-clientintegratie registreert een DbContext exemplaar dat u kunt gebruiken om met Oraclete communiceren.

.NET CLI

dotnet add package Aspire.Oracle.EntityFrameworkCore

PackageReference

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

Oracle-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddOracleDatabaseDbContext-extensiemethode aan op een IHostApplicationBuilder om een DbContext te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

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

Fooi

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Oracle databaseresource in het app-hostproject. Met andere woorden, wanneer u AddDatabase aanroept en een naam opgeeft van oracledb diezelfde naam moet worden gebruikt bij het aanroepen van AddOracleDatabaseDbContext. Zie Oracle server- en databaseresources toevoegenvoor meer informatie.

Vervolgens kunt u het DbContext exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET.

Verrijk de Oracle-databasecontext

U kunt liever de standaard Entity Framework-methode gebruiken om een databasecontext te verkrijgen en deze toe te voegen aan de container voor afhankelijkheidsinjectie:

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

Notitie

De naam van de verbindingsreeks die u doorgeeft aan de methode GetConnectionString moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Oracle resource in het app-hostproject. Zie Oracle server- en databaseresources toevoegenvoor meer informatie.

U hebt meer flexibiliteit wanneer u de databasecontext op deze manier maakt, bijvoorbeeld:

• U kunt bestaande configuratiecode opnieuw gebruiken voor de databasecontext zonder deze opnieuw te schrijven voor .NET.NET Aspire.
• U kunt Entity Framework Core interceptors gebruiken om databasebewerkingen te wijzigen.
• U kunt ervoor kiezen om Entity Framework Core contextpooling niet te gebruiken, wat in sommige omstandigheden beter kan presteren.

Als u deze methode gebruikt, kunt u de databasecontext verbeteren met .NET.NET Aspire-stijl retries, statuscontroles, logging en telemetriefuncties door de methode EnrichOracleDatabaseDbContext aan te roepen.

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

De parameter settings is een exemplaar van de klasse OracleEntityFrameworkCoreSettings.

Configuratie

De .NET AspireOracleEntity Framework Core-integratie biedt meerdere configuratiemethoden en opties om te voldoen aan de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, geeft u de naam van de verbindingsreeks op bij het aanroepen van builder.AddOracleDatabaseDbContext<TContext>():

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

De verbindingsreeks wordt opgehaald uit de ConnectionStrings configuratiesectie:

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

De EnrichOracleDatabaseDbContext maakt geen gebruik van de ConnectionStrings configuratiesectie, omdat er een DbContext moet worden geregistreerd op het punt dat deze wordt aangeroepen.

Zie de ODP-documentatie.NETvoor meer informatie.

Configuratieproviders gebruiken

De .NET AspireOracleEntity Framework Core-integratie ondersteunt Microsoft.Extensions.Configuration van configuratiebestanden zoals appsettings.json met behulp van de Aspire:Oracle:EntityFrameworkCore-sleutel. Als u uw configuraties in de sectie Aspire:Oracle:EntityFrameworkCore hebt ingesteld, kunt u de methode gewoon aanroepen zonder een parameter door te geven.

Hier volgt een voorbeeld van een appsettings.json waarmee een aantal van de beschikbare opties wordt geconfigureerd:

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

Fooi

De eigenschap CommandTimeout is binnen enkele seconden. Als deze is ingesteld zoals in het vorige voorbeeld, is de time-out 30 seconden.

Inline gedelegeerden gebruiken

U kunt ook de Action<OracleEntityFrameworkCoreSettings> delegate doorgeven om bepaalde of alle opties inline te configureren, bijvoorbeeld om de statuscontroles in code uit te schakelen:

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

of

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

Configuratieopties

Dit zijn de configureerbare opties met bijbehorende standaardwaarden:

Naam	Beschrijving
ConnectionString	De verbindingsreeks van de Oracle-database waarmee verbinding moet worden gemaakt.
DisableHealthChecks	Een Booleaanse waarde die aangeeft of de databasestatuscontrole is uitgeschakeld of niet.
DisableTracing	Een booleaanse waarde die aangeeft of de OpenTelemetry tracering is uitgeschakeld of niet.
DisableRetry	Een booleaanse waarde die aangeeft of het opnieuw proberen van opdrachten moet worden uitgeschakeld of niet.
CommandTimeout	De tijd in seconden om te wachten totdat de opdracht is uitgevoerd.

Gezondheidscontroles voor Client-integratie

.NET .NET Aspire clientintegraties hebben standaard gezondheidscontroles ingeschakeld voor alle diensten. Evenzo, schakelen veel .NET.NET Aspirehostingintegraties ook eindpunten voor gezondheidscontrole in. Zie voor meer informatie:

• .NET app-gezondheidscontroles in C#
• Gezondheidscontroles in ASP.NET Core

De .NET AspireOracleEntity Framework Core-integratie verwerkt standaard het volgende:

• Controleert of de OracleEntityFrameworkCoreSettings.DisableHealthChecks is true.
• Zo ja, voegt u de DbContextHealthChecktoe, waarmee de EF Core-methode van CanConnectAsyncwordt aangeroepen. De naam van de gezondheidscontrole is de naam van het TContext type.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch configuraties in voor logging, tracing en metrics, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De .NET AspireOracleEntity Framework Core-integratie maakt gebruik van de volgende logboekcategorieën:

• 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

Opsporing

De integratie van .NET AspireOracleEntity Framework Core verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• OpenTelemetry. Instrumentation.EntityFrameworkCore

Statistieken

De integratie van .NET AspireOracleEntity Framework Core ondersteunt momenteel de volgende metrische gegevens:

• Microsoft.EntityFrameworkCore

Zie ook

• Oracle Database
• Oracle Database Documentatie
• Entity Framework Core documenten
• .NET .NET Aspire integraties
• .NET Aspire GitHub opslagplaats