.NET Aspire SQL Server Entity Framework Core 整合

發行項
02/22/2025

SQL Server 是由 Microsoft 所開發的關係資料庫管理系統。 .NET Aspire SQL Server Entity Framework Core 整合可讓您連線到現有的 SQL Server 實例，或使用 mcr.microsoft.com/mssql/server從建立新的實例。

主機整合

SQL Server 的托管整合將伺服器模型化為 SqlServerServerResource 類型，並將資料庫模型化為 SqlServerDatabaseResource 類型。若要存取這些類型和 API，請在 📦 專案中新增 Aspire .Hosting.SqlServer NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.SqlServer

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

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

新增 SQL Server 資源和資料庫資源

在您的應用程式主專案中，呼叫 AddSqlServer 以新增並傳回 SQL Server 資源產生器。將傳回的資源產生器呼叫鏈結至 AddDatabase，以新增 SQL Server 資料庫資源。

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

注意

SQL Server 容器啟動速度很慢，因此最好使用 持續性 存留期，以避免不必要的重新啟動。如需詳細資訊，請參閱容器資源存留期。

當 .NET.NET Aspire 將容器映射新增至應用程式主機時，如上述範例中的 mcr.microsoft.com/mssql/server 映射所示，它會在本機計算機上建立新的 SQL Server 實例。 SQL Server 資源產生器（sql 變數）的參考可用來新增資料庫。資料庫名為 database，然後新增至 ExampleProject。 SQL Server 資源包含預設認證，該認證具有 username 為 sa，並使用 password 方法產生的隨機 CreateDefaultPasswordParameter。

當應用程式主機執行時，密碼會儲存在應用程式主機的秘密存放區中。它被添加到 Parameters 區段，例如：

{
  "Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}

參數的名稱是 sql-password，但實際上只是使用 -password 後綴來格式化資源名稱。如需詳細資訊，請參閱中關於在開發中安全儲存應用程式秘密的資訊，和在 ASP.NET Core、和中使用參數新增 SQL Server 資源的方法。

WithReference 方法會在名為 ExampleProject的 database 中設定連接。

提示

如果您想要連線到現有的 SQL Server，請改為呼叫 AddConnectionString。如需詳細資訊，請參閱參考現有資源。

使用數據量新增 SQL Server 資源

若要將數據磁碟區新增至 SQL Server 資源，請在 WithDataVolume 資源上呼叫 SQL Server 方法：

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume();

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

數據磁碟區可用來將 SQL Server 數據保存在其容器生命週期之外。數據磁碟區會掛接在 /var/opt/mssql 路徑中的 SQL Server 容器，當未提供 name 參數時，會隨機生成名稱。如需深入了解資料卷，以及為何它們比綁定掛載更被偏好，請參閱 Docker 文件：資料卷。

警告

密碼會儲存在數據磁碟區中。使用數據磁碟區時，如果密碼變更，在刪除磁碟區之前將無法運作。

新增 SQL Server 資源並使用數據綁定掛載

若要將數據系結掛接新增至 SQL Server 資源，請呼叫 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataBindMount(source: @"C:\SqlServer\Data");

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

重要

相較於系結掛載的功能有限，磁碟區提供更佳的效能、可移植性和安全性，使其更適合生產環境。不過，綁定掛載允許直接存取和修改主機系統上的檔案，非常適合用於開發和測試需要即時變更的環境。

數據系結裝載依賴主計算機的檔案系統，在容器重新啟動時保存 SQL Server 數據。資料繫結掛載會在 C:\SqlServer\Data 容器中的主機路徑 /SqlServer/Data （或 Unix的 SQL Server ）上掛載。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

使用參數新增 SQL Server 資源

當您想要明確提供容器映像所使用的密碼時，您可以提供這些認證作為參數。請考慮下列替代範例：

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);

var sql = builder.AddSqlServer("sql", password);
var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

如需提供參數的詳細資訊，請參閱外部參數。

連接資料庫資源

當 .NET.NET Aspire 應用程式主機執行時，伺服器的資料庫資源可以從外部工具存取，例如 SQL Server Management Studio （SSMS）或 MSSQL for Visual Studio Code。資料庫資源的連接字串在相依資源的環境變數中可以取得，並透過 .NET.NET Aspire 儀表板中的資源詳細資訊窗格進行存取。環境變數會命名為 ConnectionStrings__{name}，其中 {name} 是資料庫資源的名稱，在此範例中會 database。使用連接字串從外部工具連線到資料庫資源。假設您有一個名為 todos 的資料庫，且具有單一 dbo.Todos 數據表。

SQL Server 管理工作室
MSSQL 適用於 Visual Studio Code

若要從 SQL Server Management Studio 連線到資料庫資源，請遵循下列步驟：

開啟 SSMS。
在 [連線至 Server] 對話框中，選取 [其他連線參數] 索引標籤。
將連接字串貼入 其他連線參數 欄位，然後選取連線。
如果您已連線，您可以在 [物件總管]中看到資料庫資源：

如需詳細資訊，請參閱 SQL Server Management Studio：連線到伺服器。

主機託管系統整合健康檢查

SQL Server 主機整合會自動新增 SQL Server 資源的健康檢查。健康情況檢查會確認 SQL Server 正在執行，而且可以建立與其連線。

主機整合依賴 📦 AspNetCore.HealthChecks.SqlServer NuGet 套件。

Client 整合

若要開始使用 .NET AspireSQL ServerEntity Framework Core 整合，請在使用 SQL ServerEntity Framework Core 用戶端的應用程式專案中，安裝 📦AspireMicrosoft.EntityFrameworkCore.SqlServer NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

新增 SQL Server 資料庫環境

在用戶端取用專案的 Program.cs 檔案中，在任何 AddSqlServerDbContext 上呼叫 IHostApplicationBuilder 擴充方法，來註冊 DbContext，以便透過相依性注入容器使用。方法會採用連接名稱參數。

builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");

提示

connectionName 參數必須符合在應用程式主專案中新增 SQL Server 資料庫資源時所使用的名稱。換句話說，當您呼叫 AddDatabase 並提供 database 的名稱時，在呼叫 AddSqlServerDbContext時應該使用相同的名稱。如需詳細資訊，請參閱新增的 SQL Server 資源和資料庫資源。

若要從服務擷取 ExampleDbContext 物件：

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

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

擴充 SQL Server 資料庫內容

您可能偏好使用標準 Entity Framework 方法來取得資料庫內容，並將它新增至相依性插入容器：

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

注意

您傳遞至 GetConnectionString 方法的連接字串名稱必須符合在應用程式主專案中新增 SQL Server 資源時所使用的名稱。如需詳細資訊，請參閱新增的 SQL Server 資源和資料庫資源。

當您以這種方式建立資料庫內容時，更有彈性，例如：

您可以重複使用資料庫內容的現有組態程式代碼，而不需將它重寫為 .NET.NET Aspire。
您可以使用 Entity Framework Core 攔截器來修改資料庫作業。
您可以選擇不使用 Entity Framework Core 上下文池化，在某些情況下可能會有更好的表現。

如果您使用此方法，您可以呼叫 .NET 方法，透過 .NET AspireEnrichSqlServerDbContext樣式重試、健康情況檢查、記錄和遙測功能來增強資料庫內容：

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

settings 參數是 MicrosoftEntityFrameworkCoreSqlServerSettings 類別的實例。

配置

.NET Aspire SQL Server Entity Framework Core 整合提供多個組態方法和選項，以符合專案的需求和慣例。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 builder.AddSqlServerDbContext<TContext>()時提供連接字串的名稱：

builder.AddSqlServerDbContext<ExampleDbContext>("sql");

連接字串是從組態區段 ConnectionStrings 擷取：

{
  "ConnectionStrings": {
    "sql": "Data Source=myserver;Initial Catalog=master"
  }
}

EnrichSqlServerDbContext 不會使用 ConnectionStrings 組態區段，因為它預期在被呼叫時，DbContext 應已註冊。

如需詳細資訊，請參閱 ConnectionString。

使用組態提供者

.NET Aspire SQL Server Entity Framework Core 整合支援 Microsoft.Extensions.Configuration。它使用 MicrosoftEntityFrameworkCoreSqlServerSettings 金鑰從像是 appsettings.json 的組態檔中載入 Aspire:Microsoft:EntityFrameworkCore:SqlServer。如果您已在 [Aspire:Microsoft:EntityFrameworkCore:SqlServer] 區段中設定組態，您可以直接呼叫方法，而不傳遞任何參數。

以下是 appsettings.json 檔案的範例，可設定一些可用的選項：

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "SqlServer": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "DisableMetrics": false
        }
      }
    }
  }
}

使用內嵌組態

您也可以傳遞 Action<MicrosoftEntityFrameworkCoreSqlServerSettings> 委派函式來設定部分或全部的內建選項，例如關閉指標：

builder.AddSqlServerDbContext<YourDbContext>(
    "sql",
    static settings =>
        settings.DisableMetrics = true);

設定多個 DbContext 連線

如果您想要以不同的組態註冊多個 DbContext，您可以使用 $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}" 組態區段名稱。 json 組態看起來會像這樣：

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
          "SqlServer": {
            "ConnectionString": "YOUR_CONNECTIONSTRING",
            "DbContextPooling": true,
            "DisableHealthChecks": true,
            "DisableTracing": true,
            "DisableMetrics": false,
          "AnotherDbContext": {
            "ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

然後使用 AddSqlServerDbContext 類型參數呼叫 AnotherDbContext 方法，會從 Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext 區段載入設定。

builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");

組態選項

以下是具有對應預設值的可設定選項：

名字	描述
`ConnectionString`	要連線之 SQL Server 資料庫的連接字串。
`DbContextPooling`	布林值，指出每次要求資料庫上下文時，是否會集區或明確建立該上下文。
`MaxRetryCount`	重試次數上限。默認值為 6，將它設定為 0 以停用重試機制。
`DisableHealthChecks`	布爾值，指出是否停用資料庫健康情況檢查。
`DisableTracing`	布爾值，指出是否停用 OpenTelemetry 追蹤。
`DisableMetrics`	布爾值，指出是否停用 OpenTelemetry 計量。
`Timeout`	等候命令執行的時間，以秒為單位。

Client 整合性健康檢查

根據預設，.NET.NET Aspire客戶端整合的健康檢查已對所有服務啟用。同樣地，許多 .NET.NET Aspire代管整合也會啟用健康檢查端點。如需詳細資訊，請參閱：

.NET 在 C# 中應用程式健康情況檢查
中的健康情況檢查

根據預設，.NET Aspire Sql ServerEntity Framework Core 整合會處理下列各項：

加入 DbContextHealthCheck，它會呼叫 EF Core的 CanConnectAsync 方法。健康檢查的名稱是 TContext 類型的名稱。
與 /health HTTP 端點整合，此端點指定所有已註冊的健康檢查必須通過，應用程式才能被視為準備好接收流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和度量組態，有時被稱為 可觀察性的要素。如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。視支援服務而定，某些整合可能只支援其中一些功能。例如，某些整合支援記錄和追蹤，但不支援計量。您也可以使用組態一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire SQL Server 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 SQL Server Entity Framework Core 的整合將使用 OpenTelemetry發出以下追蹤活動：

“OpenTelemetry.Instrumentation.EntityFrameworkCore”

指標

.NET Aspire SQL Server Entity Framework Core 整合將會使用 OpenTelemetry發出下列指標：

Microsoft.EntityFrameworkCore：
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

共用方式為