.NET Aspire SQL Server Entity Framework Core 整合

發行項
12/18/2024

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

主機整合

在主機整合中，SQL Server 將 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，並使用 CreateDefaultPasswordParameter 方法產生的隨機 password。

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

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

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

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

提示

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

使用數據量新增 SQL Server 資源

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

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 數據。資料繫結掛載會在 SQL Server 容器中的主機路徑 C:\SqlServer\Data （或 Unix的 /SqlServer/Data ）上掛載。如需資料系結掛接的詳細資訊，請參閱 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 Aspire 應用程式主機執行時，可以從外部工具存取 server的資料庫資源，例如 SQL Server Management Studio （SSMS）或 Azure Data Studio。資料庫資源的連接字串在相依資源的環境變數中可以取得，並透過 .NET.NET Aspire 儀表板中的資源詳細資訊窗格進行存取。環境變數會命名為 ConnectionStrings__{name}，其中 {name} 是資料庫資源的名稱，在此範例中會 database。使用連接字串從外部工具連線到資料庫資源。假設您有一個名為 todos 的資料庫，且具有單一 dbo.Todos 數據表。

SQL Server 管理工作室
Azure Data Studio

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

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

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

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

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

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

Client 整合

若要開始使用 .NET AspireSQL ServerEntity Framework Core 整合，請安裝 📦Aspire。Microsoft.EntityFrameworkCore.SqlServerclient取用專案中的 NuGet 套件，也就是使用 SQL ServerEntity Framework Coreclient的應用程式專案。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

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

新增 SQL Server 資料庫環境

在 client取用專案的 Program.cs 檔案中，在任何 IHostApplicationBuilder 上呼叫 AddSqlServerDbContext 擴充方法，以註冊 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 資料庫內容

若要使用其他服務擴充 DbContext，例如自動重試、健康情況檢查、記錄和遙測，請呼叫 EnrichSqlServerDbContext 方法：

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    connectionName: "database",
    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。它使用 Aspire:Microsoft:EntityFrameworkCore:SqlServer 金鑰從像是 appsettings.json 的組態檔中載入 MicrosoftEntityFrameworkCoreSqlServerSettings。如果您已在 [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
          }
        }
      }
    }
  }
}

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

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

組態選項

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

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

健康檢查

根據預設，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

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

共用方式為