интеграция .NET AspireOracleEntity Framework Core

Статья
01/28/2025

Включает:интеграция размещения и Client интеграция

Oracle База данных — это широко используемая система управления реляционными базами данных, принадлежавшая Oracle. Интеграция .NET AspireOracleEntity Framework Core позволяет подключаться к существующим серверам Oracle или создавать новые серверы из .NET с помощью образа контейнера container-registry.orcale.com/databse/free.

Интеграция хостинга

.NET Aspire Oracle в модели размещения рассматриваются сервер как тип OracleDatabaseServerResource, а базу данных как тип OracleDatabaseResource. Чтобы получить доступ к этим типам и API, добавьте пакет NuGet 📦Aspire.Хостинг.Oracle в проект хоста приложения .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Oracle

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

Дополнительные сведения см. в разделах dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавление ресурсов сервера и базы данных Oracle

В проекте узла приложения используйте вызов AddOracle, чтобы добавить и вернуть конструктор ресурсов сервера Oracle. Свяжите вызов возвращаемого конструктора ресурсов к AddDatabase, чтобы добавить базу данных Oracle к ресурсу сервера.

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

Заметка

Контейнер базы данных Oracle может запускаться медленно, поэтому лучше использовать для постоянного срока существования, чтобы избежать ненужных перезапусков. Для получения дополнительной информации см. срок существования ресурса контейнера.

Когда .NET.NET Aspire добавляет контейнерное изображение на хост приложения, как показано в предыдущем примере с образом container-registry.oracle.com/database/free, на вашем локальном компьютере создается новый сервер Oracle. Для добавления базы данных используется ссылка на ресурсный конструктор Oracle (переменная oracle). База данных называется oracledb, а затем добавляется в ExampleProject. Ресурс Oracle включает случайный password, созданный с помощью метода CreateDefaultPasswordParameter.

Метод WithReference настраивает подключение в ExampleProject с именем "oracledb". Для получения дополнительной информации см. в разделе Жизненный цикл ресурсов контейнера.

Совет

Если вы хотите подключиться к существующему серверу Oracle, вызовите AddConnectionString вместо этого. Дополнительные сведения см. в разделе Справочник по существующим ресурсам.

Добавление ресурса Oracle с параметром пароля

Ресурс Oracle включает учетные данные по умолчанию со случайным паролем. Oracle поддерживает пароли по умолчанию на основе конфигурации с помощью переменной среды ORACLE_PWD. Если вы хотите явно указать пароль, его можно указать в качестве параметра:

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

Приведенный выше код получает параметр для передачи в API AddOracle и внутренне назначает параметр переменной среды ORACLE_PWD контейнера Oracle. Параметр password обычно указывается как секрет пользователя:

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

Дополнительные сведения см. в разделе Внешние параметры.

Добавить ресурс Oracle с объемом данных

Чтобы добавить том данных в ресурс Oracle, вызовите метод 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...

Том данных используется для сохранения Oracle данных за пределами жизненного цикла контейнера. Том данных подключается по пути /opt/oracle/oradata в контейнере Oracle, и если параметр name не предоставлен, имя создается случайным образом. Дополнительную информацию о томах данных и о том, почему они предпочтительнее привязок, см. в документации по томам Docker.

Предупреждение

Пароль хранится в томе данных. При использовании тома данных и при изменении пароля он не будет работать, пока не удалите том.

Добавление ресурса Oracle с подключением привязки данных

Чтобы добавить подключение привязки данных к ресурсу Oracle, вызовите метод 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...

Важный

Подключения привязки данных имеют ограниченные функциональные возможности по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для рабочих сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, идеально подходят для разработки и тестирования, где требуются изменения в реальном времени.

Монтирование привязки данных зависит от файловой системы хост-компьютера, чтобы сохранить данные Oracle после перезапуска контейнера. Монтирование привязки данных происходит по пути C:\Oracle\Data в Windows (или /Oracle/Data на Unix) на компьютере хоста в контейнере Oracle. Дополнительные сведения о монтировании привязок данных см. в документации по Docker: монтирование привязок.

Проверка работоспособности интеграции хостинга

Интеграция хостинга Oracle автоматически добавляет проверку состояния ресурса Oracle. Проверка работоспособности проверяет, запущен ли сервер Oracle и что к нему можно установить подключение.

Интеграция размещения зависит от пакета NuGetOracle📦 AspNetCore.HealthChecks.

интеграция Client

Чтобы получить доступ к базе данных, вам потребуется база данных Oracle и строка подключения. Чтобы приступить к работе с интеграцией клиента .NET AspireOracle, установите пакет NuGet 📦Aspire.Oracle.EntityFrameworkCore в проект, который использует клиент Oracle, то есть в проект приложения, использующего клиент Oracle. Интеграция Oracle клиента регистрирует экземпляр DbContext, который можно использовать для взаимодействия с Oracle.

.NET CLI
PackageReference

dotnet add package Aspire.Oracle.EntityFrameworkCore

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

Добавьте клиента Oracle

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения AddOracleDatabaseDbContext для любой IHostApplicationBuilder, чтобы зарегистрировать DbContext для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

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

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса базы данных Oracle в проект узла приложения. Другими словами, при вызове AddDatabase и указании имени oracledb то же имя следует использовать при вызове AddOracleDatabaseDbContext. Дополнительные сведения см. раздел Добавление Oracle ресурсов сервера и базы данных.

Затем можно получить экземпляр DbContext с помощью инъекции зависимостей. Например, чтобы получить подключение к образцовому сервису:

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

Дополнительные сведения о внедрении зависимостей см. в .NETо внедрении зависимостей.

Добавление контекста базы данных Oracle с обогащением

Чтобы расширить DbContext дополнительными службами, такими как автоматические повторные попытки, проверки работоспособности, ведение журнала и телеметрия, вызовите метод EnrichOracleDatabaseDbContext.

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

Параметр settings является экземпляром класса OracleEntityFrameworkCoreSettings.

Конфигурация

Интеграция .NET AspireOracleEntity Framework Core предоставляет несколько подходов к конфигурации и параметров для удовлетворения требований и соглашений проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings при вызове builder.AddOracleDatabaseDbContext<TContext>()укажите имя строки подключения:

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

Строка подключения извлекается из раздела конфигурации ConnectionStrings:

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

EnrichOracleDatabaseDbContext не будет использовать раздел конфигурации ConnectionStrings, так как ожидается, что DbContext будет зарегистрирован в момент его вызова.

Дополнительные сведения см. в документации ODP.NET.

Использование поставщиков конфигураций

Интеграция .NET AspireOracleEntity Framework Core поддерживает Microsoft.Extensions.Configuration из файлов конфигурации, таких как appsettings.json, используя ключ Aspire:Oracle:EntityFrameworkCore. Если вы настроили конфигурации в разделе Aspire:Oracle:EntityFrameworkCore, можно просто вызвать метод без передачи любого параметра.

Ниже приведен пример appsettings.json, который настраивает некоторые доступные варианты:

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

Совет

Свойство CommandTimeout измеряется в секундах. Если задано, как показано в предыдущем примере, время ожидания составляет 30 секунд.

Используйте инлайн-делегаты

Можно также передать делегат Action<OracleEntityFrameworkCoreSettings> для настройки некоторых или всех параметров непосредственно в коде, например, чтобы отключить проверку работоспособности прямо из кода.

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

или

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

Параметры конфигурации

Ниже приведены настраиваемые параметры с соответствующими значениями по умолчанию:

Имя	Описание
`ConnectionString`	Строка подключения для базы данных Oracle.
`DisableHealthChecks`	Логическое значение, указывающее, отключена ли проверка работоспособности базы данных.
`DisableTracing`	Логическое значение, которое указывает, включена или отключена трассировка OpenTelemetry.
`DisableRetry`	Логическое значение, указывающее, следует ли отключить повторные попытки команды.
`CommandTimeout`	Время ожидания выполнения команды в секундах.

Проверки состояния

По умолчанию .NET.NET Aspire интеграции включают проверки работоспособности для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.

По умолчанию интеграция .NET AspireOracleEntity Framework Core обрабатывает следующее:

Проверяет, является ли OracleEntityFrameworkCoreSettings.DisableHealthCheckstrue.
Если да, добавляет DbContextHealthCheck, который вызывает метод CanConnectAsync объекта EF Core. Название проверки работоспособности совпадает с названием типа TContext.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации журналирования, трассировки и метрик, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireOracleEntity Framework Core использует следующие категории журналов:

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

Отслеживание

Интеграция .NET AspireOracleEntity Framework Core будет выполнять следующие операции трассировки с помощью OpenTelemetry:

OpenTelemetry. Инструментирование.EntityFrameworkCore

Метрика

В настоящее время интеграция .NET AspireOracleEntity Framework Core поддерживает следующие метрики:

Microsoft.EntityFrameworkCore

Поделиться через

интеграция .NET AspireOracleEntity Framework Core

Интеграция хостинга

Добавление ресурсов сервера и базы данных Oracle

Добавление ресурса Oracle с параметром пароля

Добавить ресурс Oracle с объемом данных

Добавление ресурса Oracle с подключением привязки данных

Проверка работоспособности интеграции хостинга

интеграция Client

Добавьте клиента Oracle

Добавление контекста базы данных Oracle с обогащением

Конфигурация

Используйте строку подключения

Использование поставщиков конфигураций

Используйте инлайн-делегаты

Параметры конфигурации

Проверки состояния

Наблюдаемость и телеметрия

Лесозаготовка

Отслеживание

Метрика

См. также

Дополнительные ресурсы