.NET Aspire SQL Server 整合

發行項
12/13/2024

SQL Server 是由 Microsoft 所開發的關係資料庫管理系統。 .NET Aspire SQL Server 整合可讓您連線到現有的 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 資源包含具有 sausername 的預設認證，以及使用 CreateDefaultPasswordParameter 方法產生的隨機 password。

當應用程式主機執行時，密碼會儲存在應用程式主機的秘密存放區中。將其新增到 Parameters 區段，例如：

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

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

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 容器中，數據系結掛接被掛接在主計算機上的 Windows 的 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] 對話框中，選取 [其他連線參數] 分頁。
將連接字串貼入 其他連線參數 欄位，然後選取 Connect。
如果您已連線，您可以在 [物件總管]中看到資料庫資源：

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

主機整合健康檢查

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

托管整合依賴 📦 AspNetCore.HealthChecks.SqlServer NuGet 套件。

Client 整合

若要開始使用 .NET AspireSQL Serverclient 整合，請安裝 📦Aspire。Microsoft.Data.SqlClientclient-consuming 專案中的 NuGet 套件，也就是使用 SQL Serverclient的應用程式專案。 SQL Server client 整合會註冊一個 SqlConnection 實例，您可以用它來與 SQL Server互動。

.NET 命令行界面
套件引用

dotnet add package Aspire.Microsoft.Data.SqlClient

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

新增 SQL Serverclient

在 client消耗專案的 Program.cs 檔案中，在任何 IHostApplicationBuilder 上呼叫 AddSqlServerClient 擴充方法，以註冊 SqlConnection，並透過依賴注入容器來使用。方法會採用連接名稱參數。

builder.AddSqlServerClient(connectionName: "database");

提示

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

接著，您可以使用依賴注入來擷取 SqlConnection 實例。例如，若要從範例服務擷取連線：

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

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

新增索引鍵 SQL Serverclient

在某些情況下，您可能想要以不同的連線名稱註冊多個 SqlConnection 實例。若要註冊 SQL Server 用戶端，請呼叫 AddKeyedSqlServerClient 方法：

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

重要

使用索引鍵服務時，預期您的 SQL Server 資源已設定兩個具名資料庫，一個用於 mainDb，另一個用於 loggingDb。

然後，您可以使用依賴注入來擷取 SqlConnection 實例。例如，若要從範例服務擷取連線：

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

如需鍵控服務的詳細資訊，請參閱 .NET 相依注入：鍵控服務。

配置

.NET Aspire SQL Server 整合提供多個選項，可根據專案的需求和慣例來設定連線。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 AddSqlServerClient 方法時提供連接字串的名稱：

builder.AddSqlServerClient(connectionName: "sql");

然後，從 ConnectionStrings 組態區段擷取連接字串：

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

如需如何格式化此連接字串的詳細資訊，請參閱 ConnectionString。

使用組態提供者

.NET Aspire SQL Server 整合支援 Microsoft.Extensions.Configuration。它會使用 Aspire:Microsoft:Data:SqlClient 鍵從配置中載入 MicrosoftDataSqlClientSettings。下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

如需完整的 SQL Serverclient 整合 JSON 架構，請參閱 Aspire。Microsoft.Data.SqlClient/ConfigurationSchema。json。

使用內聯委派

您也可以傳遞 Action<MicrosoftDataSqlClientSettings> configureSettings 委託函式來內嵌設定部分或全部選項，例如通過程式碼停用健康檢測：

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client 整合性健康檢查

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

.NET Aspire SQL Server 整合：

當 MicrosoftDataSqlClientSettings.DisableHealthChecks 為 false時，新增健康檢查，並嘗試連線到 SQL Server。
與 /health HTTP 端點整合，這個端點指定所有已註冊的健康檢查必須通過，應用程式才被視為準備好接收流量。

可檢視性和遙測

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

伐木

.NET Aspire SQL Server 整合目前不會預設啟用記錄功能，因為 Microsoft.Data.SqlClient的限制。

追蹤

.NET Aspire SQL Server 整合會使用 OpenTelemetry產生以下追蹤活動：

OpenTelemetry.Instrumentation.SqlClient

指標

.NET Aspire SQL Server 整合會使用 OpenTelemetry發出下列計量：

Microsoft.Data.SqlClient.EventSource
- active-hard-connections
- hard-connects
- hard-disconnects
- active-soft-connects
- soft-connects
- soft-disconnects
- number-of-non-pooled-connections
- number-of-pooled-connections
- number-of-active-connection-pool-groups
- number-of-inactive-connection-pool-groups
- number-of-active-connection-pools
- number-of-inactive-connection-pools
- number-of-active-connections
- number-of-free-connections
- number-of-stasis-connections
- number-of-reclaimed-connections

共用方式為