.NET Aspire Oracle Entity Framework Core 集成

2025-08-12

包含： 托管集成 —&— Client 集成

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

托管集成

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

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

dotnet add package Aspire.Hosting.Oracle

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

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖项。

添加 Oracle 服务器和数据库资源

在 AppHost 项目中，调用 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 将容器映像添加到 AppHost 时，如前面的 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 数据。在 C:\Oracle\Data 容器中的主机上，数据绑定装载将安装在 Windows 上的 /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 必须与在 AppHost 项目中添加 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 连接字符串名称必须与在 AppHost 项目中添加 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 托管集成也会启用运行状况检查终结点。有关详细信息，请参阅：

默认情况下，.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