.NET Aspire SQL Server 集成

包括：托管集成 和 Client 集成

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

dotnet add package Aspire.Hosting.SqlServer

PackageReference

<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 后缀的形式。 有关详细信息，请参阅 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 数据。 数据绑定装载被安装在 Windows 上的 C:\SqlServer\Data 路径上（或者在 Unix上的 /SqlServer/Data 路径上），位于 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 Aspire 应用主机运行时，可以从外部工具（如 SQL Server Management Studio（SSMS） 或 Azure Data Studio等外部工具访问 server的数据库资源。 数据库资源的连接字符串在依赖资源环境变量中可用，并使用 .NET.NET Aspire 仪表板进行访问：资源详细信息 窗格。 环境变量被命名为 ConnectionStrings__{name}，其中 {name} 是数据库资源的名称，在本示例中为 database。 使用连接字符串从外部工具连接到数据库资源。 假设你有一个名为 todos 的数据库，其中包含单个 dbo.Todos 表。

SQL Server 管理工作室

若要从 SQL Server Management Studio 连接到数据库资源，请执行以下步骤：

1. 打开 SSMS。

2. 在“连接到 Server”对话框中，选择 “其他连接参数” 选项卡。

3. 将连接字符串粘贴到“附加连接参数”字段中，然后选择“连接。

   

4. 如果已连接，可以在 对象资源管理器中看到数据库资源：

   

有关详细信息，请参阅 SQL Server Management Studio：连接到 server。

Azure Data Studio（数据工作室）

若要从 Azure Data Studio 连接到数据库资源，请执行以下步骤：

1. 打开 Azure Data Studio。

2. 选择 “新建”下拉列表，然后选择 “新建连接”。

   

3. 将 输入类型 更改为 连接字符串，并将连接字符串粘贴到 连接字符串 字段中。

4. 选择“”连接“”。

   

5. 如果已连接，可以在活动选项卡中看到数据库资源：

   

有关详细信息，请参阅 Azure Data Studio：连接到 SQL Server。

托管集成运行状况检查

SQL Server 托管集成会自动为 SQL Server 资源添加运行状况检查。 运行状况检查验证 SQL Server 是否正在运行，并确认能够建立与其的连接。

托管集成依赖于 📦 AspNetCore.HealthChecks.SqlServer NuGet 包。

Client 集成

若要开始 .NET AspireSQL Serverclient 集成，请安装 📦Aspire。Microsoft.Data.SqlClientclient使用项目中的 NuGet 包，即使用 SQL Serverclient的应用程序的项目。 SQL Server client 集成注册一个 SqlConnection 实例，以便用于与 SQL Server交互。

.NET CLI

dotnet add package Aspire.Microsoft.Data.SqlClient

PackageReference

<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 集成概述。 根据支持服务，某些集成可能仅支持其中一些功能。 例如，某些集成支持日志记录和跟踪，但不支持指标。 也可以使用 配置 部分中介绍的技术禁用遥测功能。

伐木

由于 Microsoft.Data.SqlClient的限制，.NET AspireSQL Server 集成目前默认不启用日志记录。

追踪

.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

另请参阅

• Azure SQL 数据库
• SQL Server
• .NET .NET Aspire 数据库容器示例
• .NET .NET Aspire 集成
• .NET Aspire GitHub 存储库