Udostępnij za pośrednictwem

integracja .NET AspireOracleEntity Framework Core

  • Artykuł

obejmuje:,,integracja hostingu i integracja ,,Client,

Oracle Database to powszechnie używany system zarządzania relacyjnymi bazami danych należący do Oracle. Integracja .NET AspireOracleEntity Framework Core umożliwia łączenie się z istniejącymi serwerami Oracle lub tworzenie nowych serwerów z .NET przy użyciu obrazu kontenera container-registry.orcale.com/databse/free.

Integracja hostingu

Modele integracji .NET AspireOracle przedstawiają serwer jako typ OracleDatabaseServerResource, a bazę danych jako typ OracleDatabaseResource. Aby uzyskać dostęp do tych typów i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.Oracle w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Oracle

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietów w .NET aplikacjach.

Dodawanie zasobów serwera Oracle i bazy danych

W projekcie hosta aplikacji wywołaj AddOracle, aby dodać i zwrócić konstruktor zasobów serwera Oracle. Aby dodać bazę danych Oracle do zasobu serwera, połącz wywołanie z zwróconym konstruktorem zasobów do AddDatabase.

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

Notatka

Kontener bazy danych Oracle może być uruchamiany wolno, dlatego najlepiej użyć trwałego okresu istnienia, aby uniknąć niepotrzebnych ponownych uruchomień. Aby uzyskać więcej informacji, zobacz okres istnienia zasobu kontenera.

Gdy .NET.NET Aspire dodaje obraz kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem container-registry.oracle.com/database/free, tworzy nowy serwer Oracle na komputerze lokalnym. Odwołanie do konstruktora zasobów Oracle (zmiennej oracle) służy do dodawania bazy danych. Baza danych nosi nazwę oracledb, a następnie jest dodawana do ExampleProject. Zasób Oracle zawiera losowe password wygenerowane przy użyciu metody CreateDefaultPasswordParameter.

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie "oracledb". Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Napiwek

Jeśli wolisz nawiązać połączenie z istniejącym serwerem Oracle, wywołaj AddConnectionString zamiast tego. Aby uzyskać więcej informacji, odwołaj się do istniejących zasobów .

Dodawanie zasobu Oracle przy użyciu parametru hasła

Zasób Oracle zawiera poświadczenia domyślne z losowym hasłem. Oracle obsługuje domyślne hasła oparte na konfiguracji przy użyciu zmiennej środowiskowej ORACLE_PWD. Jeśli chcesz jawnie podać hasło, możesz podać je 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);

Powyższy kod pobiera parametr do przekazania do interfejsu API AddOracle i wewnętrznie przypisuje parametr do zmiennej środowiskowej ORACLE_PWD kontenera Oracle. Parametr password jest zwykle określany jako klucz tajny użytkownika:

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

Aby uzyskać więcej informacji, zobacz Parametry zewnętrzne.

Dodawanie zasobu Oracle z woluminem danych

Aby dodać wolumin danych do zasobu Oracle, wywołaj metodę 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...

Wolumen danych służy do przechowywania danych Oracle poza cyklem życia kontenera. Wolumin danych jest instalowany w ścieżce /opt/oracle/oradata w kontenerze Oracle, a gdy nie podano parametru name, nazwa jest generowana losowo. Aby uzyskać więcej informacji na temat woluminów danych i szczegółów na temat tego, dlaczego są preferowane w przypadku instalacji wiązania, zobacz Docker dokumentacji: woluminy.

Ostrzeżenie

Hasło jest przechowywane w woluminie danych. W przypadku korzystania z woluminu danych i zmiany hasła nie będzie działać, dopóki wolumin nie zostanie usunięty.

Dodawanie zasobu Oracle z instalacją powiązania danych

Aby dodać punkt montowania danych do zasobu Oracle, wywołaj metodę 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...

Ważny

Instalacje powiązane danych mają ograniczoną funkcjonalność w porównaniu z woluminami , co zapewnia lepszą wydajność, przenośność i bezpieczeństwo, co czyni je bardziej odpowiednimi dla środowisk produkcyjnych. Jednak instalacje wiązania umożliwiają bezpośredni dostęp i modyfikację plików w systemie hosta, idealne do programowania i testowania, w których potrzebne są zmiany w czasie rzeczywistym.

Montowanie powiązań danych polega na systemie plików maszyny hosta w celu zachowania danych Oracle podczas ponownych uruchomień kontenera. Instalacja powiązania danych jest instalowana w C:\Oracle\Data w systemie Windows (lub /Oracle/Data w Unix) ścieżki na maszynie hosta w kontenerze Oracle. Aby uzyskać więcej informacji na temat instalacji powiązań danych, zobacz Docker docs: Bind mounts.

Sprawdzanie stanu integracji w hostingu

Integracja hostowania Oracle automatycznie dodaje kontrolę kondycji zasobu Oracle. Sprawdzanie kondycji sprawdza, czy serwer Oracle jest uruchomiony i czy można nawiązać z nim połączenie.

Integracja hostingu bazuje na pakiecie NuGet 📦 AspNetCore.HealthChecks.Oracle.

integracja Client

Aby uzyskać dostęp do bazy danych, potrzebujesz bazy danych Oracle oraz parametrów połączenia. Aby rozpocząć integrację z klientem .NET AspireOracle, zainstaluj pakiet NuGet 📦Aspire.Oracle.EntityFrameworkCore w projekcie aplikacji korzystającej z klienta Oracle. Integracja klienta Oracle rejestruje wystąpienie DbContext, którego można użyć do interakcji z Oracle.

dotnet add package Aspire.Oracle.EntityFrameworkCore

Dodaj klienta Oracle

W pliku Program.cs projektu korzystającego z klienta wywołaj metodę rozszerzenia AddOracleDatabaseDbContext na dowolnym IHostApplicationBuilder, aby zarejestrować DbContext do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

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

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu bazy danych Oracle w projekcie hosta aplikacji. Innymi słowy, podczas wywoływania AddDatabase i podawania nazwy oracledb, tej samej nazwy należy użyć podczas wywoływania AddOracleDatabaseDbContext. Aby uzyskać więcej informacji, zobacz Dodaj zasoby serwera i bazy danych Oracle.

Następnie można pobrać instancję DbContext, korzystając z mechanizmu wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET wstrzykiwanie zależności.

Dodaj kontekst bazy danych Oracle wzbogacony o dodatkowe informacje

Aby wzbogacić DbContext o dodatkowe usługi, takie jak automatyczne ponawianie prób, kontrole kondycji, rejestrowanie i telemetria, wywołaj metodę EnrichOracleDatabaseDbContext:

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

Parametr settings jest wystąpieniem klasy OracleEntityFrameworkCoreSettings.

Konfiguracja

Integracja .NET AspireOracleEntity Framework Core zapewnia wiele metod konfiguracji i opcji spełniających wymagania i konwencje projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings należy podać nazwę parametrów połączenia podczas wywoływania builder.AddOracleDatabaseDbContext<TContext>():

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

Parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

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

EnrichOracleDatabaseDbContext nie będzie korzystać z sekcji konfiguracji ConnectionStrings, ponieważ oczekuje ona zarejestrowania DbContext w momencie jego wywołania.

Aby uzyskać więcej informacji, zobacz dokumentację ODP.NET.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireOracleEntity Framework Core obsługuje Microsoft.Extensions.Configuration z plików konfiguracji, takich jak appsettings.json przy użyciu klucza Aspire:Oracle:EntityFrameworkCore. Jeśli konfiguracje zostały skonfigurowane w sekcji Aspire:Oracle:EntityFrameworkCore, możesz wywołać metodę bez przekazywania żadnego parametru.

Poniżej przedstawiono przykład appsettings.json, który konfiguruje niektóre z dostępnych opcji:

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

Napiwek

Właściwość CommandTimeout jest wyrażona w sekundach. W przypadku ustawienia, jak pokazano w poprzednim przykładzie, limit czasu wynosi 30 sekund.

Używaj delegatów wbudowanych

Możesz również przekazać delegata Action<OracleEntityFrameworkCoreSettings>, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu wyłączenia kontroli kondycji z kodu:

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

lub

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

Opcje konfiguracji

Poniżej przedstawiono opcje konfigurowalne z odpowiednimi wartościami domyślnymi:

Nazwa Opis
ConnectionString Parametry połączenia bazy danych Oracle do nawiązania połączenia.
DisableHealthChecks Wartość logiczna wskazująca, czy sprawdzanie kondycji bazy danych jest wyłączone, czy nie.
DisableTracing Wartość logiczna wskazująca, czy śledzenie OpenTelemetry jest wyłączone, czy nie.
DisableRetry Wartość logiczna wskazująca, czy ponowne próby poleceń powinny być wyłączone, czy nie.
CommandTimeout Czas w sekundach oczekiwania na wykonanie polecenia.

Kontrole kondycji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Domyślnie integracja .NET AspireOracleEntity Framework Core obsługuje następujące elementy:

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Wyrąb

Integracja .NET AspireOracleEntity Framework Core używa następujących kategorii dzienników:

  • 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

Śledzenie

Integracja .NET AspireOracleEntity Framework Core spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • OpenTelemetry. Instrumentation.EntityFrameworkCore

Metryki

Integracja .NET AspireOracleEntity Framework Core obecnie obsługuje następujące metryki:

  • Microsoft.EntityFrameworkCore

Zobacz też