.NET Aspire Oracle Entity Framework Core 集成

2025-04-22

包含： - Client 集成

Oracle 数据库是一种广泛使用的关系数据库管理系统，由该 Oracle系统拥有和开发。通过.NET AspireOracleEntity Framework Core集成，可以连接到现有Oracle服务器，或使用 .NET 容器映像创建新服务器。

托管集成

托管集成 .NET AspireOracle 将服务器建模为 OracleDatabaseServerResource 类型和数据库作为 OracleDatabaseResource 类型。若要访问这些类型和 API，请在 📦 项目中添加 AspireOracle.Hosting. NuGet 包。

.NETCLI（命令行界面）
包引用

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

前面的代码获取传递给 AddOracle API 的参数，并在内部将参数分配给 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 数据。数据绑定装载被安装在 Windows 上的 C:\Oracle\Data 路径上（或者在 /Oracle/Data上的 Unix 路径上），位于 Oracle 容器中的主机设备上。有关数据挂载绑定的详细信息，请参阅 Docker 文档：挂载绑定。

托管环境集成运行状况检查

Oracle 托管集成会自动为 Oracle 资源添加运行状况检查。运行状况检查验证 Oracle 服务器是否正在运行，并且可以建立与服务器的连接。

托管集成依赖于 📦 AspNetCore.HealthChecks.Oracle NuGet 包。

Client 集成

需要 Oracle 数据库和连接字符串才能访问数据库。若要开始 .NET AspireOracle 客户端集成，请在使用 📦 客户端的应用程序项目中安装 Aspire 的 NuGet 包。 Oracle 客户端集成会注册一个 DbContext 实例，该实例可用于与 Oracle交互。

.NETCLI（命令行界面）
包引用

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 数据库上下文

你可能更喜欢使用标准 Entity Framework 方法获取数据库上下文并将其添加到依赖项注入容器：

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

注释

传递给 GetConnectionString 方法的连接字符串名称必须与在应用主机项目中添加 Oracle 资源时使用的名称匹配。有关详细信息，请参阅添加 Oracle 服务器和数据库资源。

以这种方式创建数据库上下文时具有更大的灵活性，例如：

可以重复使用数据库上下文的现有配置代码，而无需为 .NET.NET Aspire重写它。
可以使用 Entity Framework Core 拦截器来修改数据库操作。
可以选择不使用 Entity Framework Core 上下文池，在某些情况下性能可能更好。

如果使用此方法，可以通过调用 .NET 方法来增强数据库上下文，增强功能包括 .NET AspireEnrichOracleDatabaseDbContext样式的重试、运行状况检查、日志记录和遥测功能。

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

settings 参数是 OracleEntityFrameworkCoreSettings 类的实例。

配置

.NET Aspire Oracle Entity 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 Aspire Oracle Entity 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`	等待命令执行的时间（以秒为单位）。

Client 整合健康检查

默认情况下， .NET.NET Aspire客户端集成为所有服务启用了运行状况检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

在 C# .NET 应用运行状况检查
运行状况检查在 ASP.NET Core 中

默认情况下，.NET AspireOracleEntity Framework Core 集成处理以下内容：

检查 OracleEntityFrameworkCoreSettings.DisableHealthChecks 是否 true。
如果是这样，请添加 DbContextHealthCheck，该内容调用了 EF Core的 CanConnectAsync 方法。健康检查的名称是 TContext 类型的名称。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志、追踪和指标配置，这些有时被称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Oracle Entity 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 Aspire Oracle Entity Framework Core 集成将使用 OpenTelemetry发出以下跟踪活动：

OpenTelemetry。Instrumentation.EntityFrameworkCore

指标

.NET Aspire Oracle Entity Framework Core 集成目前支持以下指标：

Microsoft.EntityFrameworkCore

通过