.NET Aspire SQL Server 集成

包含： - Client 集成

SQL Server 是由Microsoft开发的关系数据库管理系统。 .NET Aspire SQL Server 集成使你能够连接到现有 SQL Server 实例，或使用 .NET从 mcr.microsoft.com/mssql/server 创建新实例。

托管集成

托管集成 SQL Server 将服务器建模为 SqlServerServerResource 类型和数据库作为 SqlServerDatabaseResource 类型。 若要访问这些类型和 API，请在📦项目中添加Aspire.Hosting.SqlServer NuGet 包。

dotnet add package Aspire.Hosting.SqlServer

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

有关详细信息，请参阅 dotnet 添加包 或 管理 .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>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

当 .NET.NET Aspire 向应用主机添加容器映像时，如前例中的 mcr.microsoft.com/mssql/server 映像所示，它会在本地计算机上创建新的 SQL Server 实例。 对 SQL Server 资源生成器（sql 变量）的引用用于添加数据库。 首先将数据库命名为database，然后添加到ExampleProject。

将数据库资源添加到应用模型时，如果数据库尚不存在，则会创建该数据库。 数据库的创建依赖于 应用主机事件 API，具体而言 ResourceReadyEvent。 换句话说，当sql资源准备就绪时，将引发事件并创建数据库资源。

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 资源

默认情况下，当您添加SqlServerDatabaseResource时，它依赖于以下 SQL 脚本来创建数据库：

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

若要更改默认脚本，请在数据库资源生成器上链式调用 WithCreationScript 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

前面的示例创建了一个名为app_db的数据库，其中包含一个todos表。 在创建数据库资源时执行 SQL 脚本。 脚本作为字符串传递给 WithCreationScript 方法，然后在 SQL Server 资源的上下文中执行。

添加具有数据容量的 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

数据卷用于在容器的生命周期之外保留 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

数据绑定挂载依赖于主机的文件系统，以在容器重启时持久化SQL Server数据。 数据绑定装载被安装在 Windows 上的 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

有关提供参数的详细信息，请参阅 外部参数。

连接至数据库资源

运行 .NET.NET Aspire 应用主机时，可以从外部工具（如 SQL Server Management Studio（SSMS） 或 MSSQL 等外部工具访问服务器的数据库资源 Visual Studio Code。 数据库资源的连接字符串在依赖资源环境变量中可用，并使用 .NET.NET Aspire 仪表板进行访问：资源详细信息 窗格。 环境变量被命名为 ConnectionStrings__{name}，其中 {name} 是数据库资源的名称，在本示例中为 database。 使用连接字符串从外部工具连接到数据库资源。 假设你有一个名为 todos 的数据库，其中包含单个 dbo.Todos 表。

托管集成健康检查

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

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

Client 集成

若要开始 .NET AspireSQL Server 客户端集成，请在使用 📦 客户端的应用程序项目中安装 Aspire NuGet 包。 SQL Server 客户端集成注册一个 SqlConnection 实例，你可以使用该实例与 SQL Server交互。

dotnet add package Aspire.Microsoft.Data.SqlClient

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

添加 SQL Server 客户端

在您的客户端消费项目中的 Program.cs 文件中，对任何 AddSqlServerClient 调用 IHostApplicationBuilder 扩展方法，以注册 SqlConnection，以便通过依赖注入容器进行使用。 该方法采用连接名称参数。

builder.AddSqlServerClient(connectionName: "database");

然后，可以使用依赖项注入检索 SqlConnection 实例。 例如，若要从示例服务检索连接，

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

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加键控客户< c0 />

在某些情况下，可能需要使用不同的连接名称注册多个 SqlConnection 实例。 若要注册密钥 SQL Server 客户端，请调用 AddKeyedSqlServerClient 方法：

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "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。 它使用 MicrosoftDataSqlClientSettings 键来从配置中加载 Aspire:Microsoft:Data:SqlClient。 以下代码片段是一个 appsettings.json 文件示例，用于配置某些选项：

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

有关完整的 SQL Server 客户端集成 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 ServerMicrosoft.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

另请参阅

• Azure SQL 数据库
• SQL Server
• .NET .NET Aspire 数据库容器示例
• .NET .NET Aspire 集成方案
• .NET Aspire GitHub 回购
• Azure SQL 和 SQL ServerAspire 示例