.NET Aspire Oracle Entity Framework Core 整合

發行項
2025/02/22

Oracle 資料庫是 Oracle所擁有和開發的廣泛使用關係資料庫管理系統。 .NET Aspire Oracle Entity Framework Core 整合可讓您連線到現有的 Oracle 伺服器，或從 .NET 使用 container-registry.oracle.com/database/free 容器映像建立新的伺服器。

託管整合

裝載整合 .NET AspireOracle 會將伺服器模型化為 OracleDatabaseServerResource 類型，並將資料庫模型化為 OracleDatabaseResource 類型。若要存取這些類型和 API，請在 📦 專案中新增 AspireOracle.Hosting. NuGet 套件。

.NET 命令列介面
PackageReference

.NET CLI

dotnet add package Aspire.Hosting.Oracle

XML

<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 參數通常指定為 用戶密碼：

JSON

{
  "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 路徑（或 /Oracle/Data上的 Unix 路徑），位於 Oracle 容器中。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

託管整合健康檢查

託管整合 Oracle 會自動新增對於 Oracle 資源的健康檢查。健康檢查會驗證 Oracle 伺服器正在運行，並且能夠建立連線。

裝載整合依賴 📦 的 AspNetCore.HealthChecks 套件和Oracle 的 NuGet 套件。

Client 整合

您需要 Oracle 資料庫和連接字串，才能存取資料庫。若要開始使用 .NET AspireOracle 用戶端整合，請安裝 📦Aspire。Oracle。EntityFrameworkCore 用戶端取用專案中的 NuGet 套件，也就是使用 Oracle 用戶端的應用程式專案。 Oracle 用戶端整合會註冊可用來與 DbContext互動的 Oracle 實例。

.NET 命令列介面
PackageReference

.NET CLI

dotnet add package Aspire.Oracle.EntityFrameworkCore

XML

<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 擷取：

JSON

{
  "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 範例：

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 在 C# 中應用程式健康情況檢查
中的健康情況檢查

根據預設，.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

共用方式為

.NET Aspire Oracle Entity Framework Core 整合

託管整合

新增 Oracle 伺服器和資料庫資源

使用密碼參數新增 Oracle 資源

以數據量添加 Oracle 資源

使用數據系結掛接新增 Oracle 資源

託管整合健康檢查

Client 整合

新增 Oracle 用戶端

擴充 Oracle 資料庫內容

配置

使用連接字串

使用組態提供者

使用內嵌委派

組態選項

Client 整合性健康檢查

可檢視性和遙測

伐木

追蹤

指標

另請參閱

其他資源