使用 Microsoft.Data.SqlClient 连接到数据源

SqlConnection 表示一个到 SQL Server、Azure SQL 数据库、Azure SQL 托管实例 或 Microsoft Fabric 中的 SQL 数据库的逻辑连接。 打开该对象时,如果连接池中有可用连接,就会从连接池获取一个物理连接。 关闭或丢弃它会恢复到池的物理连接。

使用 SqlConnection 短命的对象作为工作单元。 不要为应用开启一个全局连接。

Prerequisites

  • .NET 10 SDK 或更高版本且受支持的 .NET SDK。 该SDK可在Windows、Linux和macOS上运行。 它还构建了每个样本的 .NET Framework 版本,该版本仅在 Windows 上运行,需要 .NET Framework 4.8.1。
  • 可在 SQL Server、Azure SQL 数据库、Azure SQL 托管实例 或 Microsoft Fabric 的 SQL 数据库中连接的数据库。

创建项目

Microsoft.Data.SqlClient 7.0及更高版本需要版本匹配Microsoft.Data.SqlClient.Extensions.Azure包以支持驱动程序提供的Microsoft Entra ID认证模式,例如Active Directory Default。 如果你的应用只使用 SQL 认证或 Windows 集成认证,可以省略它。

在一个空文件夹中,执行以下命令:

dotnet new console --framework net10.0 --name SqlClientConnect
cd SqlClientConnect
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

本文中的示例从 SQL_CONNECTION_STRING 环境变量中读取连接字符串。 在运行样本之前先设置好它。 关于连接字符串格式,请参见连接字符串。

除事务样本外,所有样本都是完整的程序。 要运行一个,先用它替换 Program.cs 的内容,然后运行 dotnet run。 事务示例是一个片段,可用于你自己的方法。 .NET标签页使用顶层语句、隐式using指令和await using。 .NET框架标签页使用 C# 7.3,而 C# 7.3 不支持 await using,所以它改用 using 语句。

开启连接

在异步代码中调用 OpenAsync,或在同步代码中调用 Open。 使用 await using 或 using 声明连接,这样在代码离开作用域时,即使抛出异常,连接也会被释放。

通过Windows集成的认证,连接使用进程的身份。 对于网页应用或 Windows 服务,那是应用池或服务账户,而不是登录用户。 欲了解更多信息,请参见 选择认证模式。

该完整程序会打开连接,报告每次状态变化,并读取两个服务器属性:

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString);
connection.StateChange += (_, e) =>
    Console.WriteLine($"State: {e.OriginalState} to {e.CurrentState}");

await connection.OpenAsync();

await using var command = new SqlCommand(
    """
    SELECT CAST(SERVERPROPERTY('Edition') AS nvarchar(128)),
           CAST(SERVERPROPERTY('EngineEdition') AS int);
    """,
    connection);

await using (SqlDataReader reader = await command.ExecuteReaderAsync())
{
    await reader.ReadAsync();
    Console.WriteLine($"Edition: {reader.GetString(0)}");
    Console.WriteLine($"EngineEdition: {reader.GetInt32(1)}");
}

针对SQL Server 2025 Enterprise版,输出为:

State: Closed to Open
Edition: Enterprise Edition: Core-based Licensing (64-bit)
EngineEdition: 3
State: Open to Closed

最后一行出现在程序结束时连接被释放。

关闭并处置连接

每次完成连接后一定要关闭连接,这样物理连接才能回到池子。 using 和 await using 语句会在代码退出该块时释放连接,包括在引发未处理的异常时。 你也可以直接打电话 Close 或 Dispose 联系。 Close 并且 Dispose 对物理连接产生相同的影响。

遵循以下规则:

  • 先释放读取器和命令,再释放拥有它们的连接。
  • 不要依赖垃圾回收将连接返回到连接池。 如果连接超出作用域且未关闭,它就不会被及时归还,连接池中的连接可能会耗尽。
  • 不要在类终结器中对连接、读取器或任何其他托管对象调用 Close 或 Dispose。 终结器应只释放其类直接拥有的未管理资源。 更多信息请参见 垃圾收集。
  • 之后 Close,你可以在同一对象上再次调用 Open 。 在 Dispose 之后,创建一个新对象。

启用池化时,关闭连接会将其返回池,但不关闭网络连接。 当连接被重新使用时,池会重置会话状态。 更多信息请参见 SQL Server 连接池。

使用异步 API

在网络服务器、服务、用户界面和工作者中,使用异步调用进行网络绑定数据库工作:

  • OpenAsync(cancellationToken)
  • ExecuteNonQueryAsync(cancellationToken)
  • ExecuteReaderAsync(cancellationToken)
  • ExecuteScalarAsync(cancellationToken)
  • ReadAsync(cancellationToken)

在当前异步操作结束前,不要对连接、命令或读卡器启动另一个操作。

应用取消和超时

在每一次异步数据库调用中传递调用方的 CancellationToken。 取消操作会请求驱动程序停止尚未完成的工作,但不能保证立即完成。 继续使用有边界的连接超时和命令超时。

这些控制有不同的范围:

控制 Scope
Connect Timeout 建立连接,或等待共用连接
SqlCommand.CommandTimeout 执行一条命令
CancellationToken 调用方请求取消异步操作

超时或取消并不意味着服务器已回滚该操作。 当多个变更必须作为一个单元提交或回滚时,使用事务,并根据操作的幂等性和事务结果做出重试决策。

跟踪连接状态

State 属性从 ConnectionState 枚举中返回快照。

State Meaning
Closed 逻辑连接未打开。
Connecting 一场公开行动正在进行中。
Open 逻辑联系是开放的。

当状态发生变化时,事件 StateChange 就会触发。 其 StateChangeEventArgs 参数有两个属性:

  • OriginalState 是变更前的状态。
  • CurrentState 是变更后的状态。

驱动程序报告从 Closed 到 Open 以及从 Open 到 Closed 的转换,如 打开连接 中的示例所示。 不要依赖于将Executing、Fetching或Broken视为应用生命周期阶段。

不要在每次下指令前都用 State 来做健康检查。 网络在任何检查后都可能失败。 运行该操作并处理由此产生的异常。 StateChange用于诊断,不用于协调并发工作。

接收信息类消息

InfoMessage 事件传递的是服务器在不引发错误的情况下发送的消息。 这些消息包括 PRINT 输出、 RAISERROR 严重程度为10或更低的消息以及服务器警告。 错误严重度为 11 或更高时,则会改为引发 SqlException。 关于严重程度级别,请参见数据库引擎错误严重度。

事件处理程序接收一个 SqlInfoMessageEventArgs 对象。 其 Errors 属性包含一组 SqlError 对象。 每个信息都包含消息编号、文本、严重程度类别、程序和行号。

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString);
connection.InfoMessage += (_, e) =>
{
    foreach (SqlError error in e.Errors)
    {
        Console.WriteLine(
            $"Message {error.Number}, severity {error.Class}: {error.Message}");
    }
};

await connection.OpenAsync();

await using var command = new SqlCommand(
    """
    PRINT 'Starting the batch.';
    RAISERROR('Processed %d rows.', 10, 1, 42);
    """,
    connection);

await command.ExecuteNonQueryAsync();

输出为:

Message 0, severity 0: Starting the batch.
Message 50000, severity 0: Processed 42 rows.

服务器会将严重级别为 10 的 RAISERROR 报告为类 0,因此 SqlError.Class 对这两条消息都会显示 0。

将用户错误处理为信息消息

默认情况下,驱动程序通过抛出 SqlException 来报告严重程度为 11 及以上的错误。 该异常并不意味着服务器已停止执行批处理。 许多错误,包括 RAISERROR 严重度为16的错误,允许服务器运行剩余语句,因此后续语句即使代码捕捉到异常,也可能更改数据。 要将这些错误以消息形式接收而非异常,请设 FireInfoMessageEventOnUserErrors 为 true。 驱动程序随后会将严重性为 16 或以下的错误发送到 InfoMessage 事件,而不是直接引发异常。 这一属性改变了驱动程序报告错误的方式。 它不会改变服务器运行哪些语句。

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString)
{
    FireInfoMessageEventOnUserErrors = true,
};
connection.InfoMessage += (_, e) =>
{
    foreach (SqlError error in e.Errors)
    {
        Console.WriteLine(
            $"Message {error.Number}, severity {error.Class}: {error.Message}");
    }
};

await connection.OpenAsync();

await using var command = new SqlCommand(
    """
    RAISERROR('Row 7 failed validation.', 16, 1);
    SELECT 'The batch continued.';
    """,
    connection);

await using (SqlDataReader reader = await command.ExecuteReaderAsync())
{
    do
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine(reader.GetString(0));
        }
    }
    while (await reader.NextResultAsync());
}

输出为:

Message 50000, severity 16: Row 7 failed validation.
The batch continued.

即使错误严重度达到17或以上,仍会抛出 SqlException,无论该设置如何。 启用此属性后,你的处理程序负责检测失败。 预期每个错误都引发异常的代码并没有遇到异常。

报告应用程序标识

从 Microsoft.Data.SqlClient 7.1.0 开始,一个框架、工具或其他中间件可以报告是哪个应用程序打开了连接。 在打开连接之前,先将 RegisteredApplication 设置为 RegisteredApplication 值。 驱动程序在登录时将该值发送一次给服务器。

遵循以下规则:

  • 通过属性设置数值。 不存在适用于它的 连接字符串 关键字。
  • 在打开连接前先设置好数值。 在连接正在打开或已打开时设置它,会引发 InvalidOperationException。
  • 把这个值当作遥测数据来处理。 客户端提供该值并可以报告任何标识符,因此服务器不会对其进行认证。
  • 共用连接报告原始标识是预期行为。 该值不是池键的一部分。 从池中提供的连接会报告导致物理连接创建的逻辑连接的身份。

Caution

绝不要使用 RegisteredApplication 进行授权或任何其他安全决策。 任何客户端都可以报告任何标识符。

选择一个标识符

默认值为 Unknown,即 0。 枚举有一个底层类型ushort,因此标识符范围从0到0xFFFF。

范围 Use
0x0001 到 0x7FFF Microsoft 定义的应用程序。 已命名的枚举成员使用该范围。
0x8000 到 0xBFFF 仅限小规模使用。
0xC000 到 0xFFFF 公共和开发者使用。

被命名的成员包括 EntityFrameworkCore、SemanticKernel、ManagementStudio、DataTierApplicationFramework、AspNetCoreDistributedSqlServerCache、EntityFramework、SqlToolsService、SqlManagementObjects、OrleansAdoNet、DurableTaskSqlServer、AzureFunctionsSqlExtension、SqlPackage 和 DataApiBuilder。 要报告没有命名成员的标识符,请将该数字强制转换为 RegisteredApplication。

RegisteredApplication类型和属性不符合CLS,因为枚举使用了ushort。 C# 代码可以直接使用它们。

设置标识符

该程序报告开发者范围的标识符,然后显示连接打开后代码更改值时发生的情况:

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString)
{
    RegisteredApplication = (RegisteredApplication)0xC001,
};

await connection.OpenAsync();
Console.WriteLine(
    $"Reported identifier: 0x{(ushort)connection.RegisteredApplication:X4}");

try
{
    connection.RegisteredApplication = RegisteredApplication.Unknown;
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}

输出为:

Reported identifier: 0xC001
InvalidOperationException: Not allowed to change the 'RegisteredApplication' property. The connection's current state is open.

理解池化效应

驱动程序只有在创建新的物理连接时才会报告标识符。 启用池化:

  • 重复使用池化物理连接的连接会报告创建物理连接的连接身份,而非自身连接。
  • 池为满足 Min Pool Size 而在后台打开的物理连接会报告 Unknown。

如果一个 连接字符串 服务于多个身份,则将报告的值视为近似值。 当你需要精确归因时,关闭该连接字符串的池化,并先测量额外的连接成本。

SqlConnection.Clone 将 RegisteredApplication 该值复制到新的连接上。

不要同时共享连接

SqlConnection SqlCommand, , SqlDataReader, , SqlTransaction 不支持多个线程同时使用。 给每个并发操作单独的连接,让连接池重用物理连接。

多激活结果集(MARS)允许在支持的场景下,在同一连接上同时运行多个活跃批次。 它并不能使 SqlClient 对象具备线程安全性,并且还引入了会话和事务规则。 除非某个操作特别需要,否则保持禁用。

不要在依赖注入中将开放泛型 SqlConnection 注册为单例。 注册连接字符串、不可变的选项对象,或用于创建新连接的工厂。

有意使用事务

本地事务属于其连接。 事务中的每个命令都必须使用该连接并设置其 Transaction 属性。

await using var connection = new SqlConnection(connectionString);
await connection.OpenAsync(cancellationToken);

await using SqlTransaction transaction =
    (SqlTransaction)await connection.BeginTransactionAsync(cancellationToken);

using var command = new SqlCommand(sql, connection, transaction);
command.Parameters.Add(
    new SqlParameter("@value", SqlDbType.Int) { Value = value });
await command.ExecuteNonQueryAsync(cancellationToken);

await transaction.CommitAsync(cancellationToken);

如果操作在提交前失败,丢弃事务会将其回滚。 保持交易简短。 数据库事务持有锁时,不要做网络调用、用户交互或无关计算。

当 System.Transactions.Transaction.Current 处于活动状态时,Open 和 OpenAsync 默认会自动加入。 仅当该操作必须位于当前事务上下文之外时,才设置 Enlist=false。

测量一个逻辑连接

将 StatisticsEnabled 设置为 true 以收集一个 SqlConnection 对象的驱动程序统计数据:

using System.Collections;
using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

await using var connection = new SqlConnection(connectionString)
{
    StatisticsEnabled = true,
};

await connection.OpenAsync();
connection.ResetStatistics();

await using var command = new SqlCommand("SELECT name FROM sys.databases;", connection);
await using (SqlDataReader reader = await command.ExecuteReaderAsync())
{
    while (await reader.ReadAsync())
    {
    }
}

IDictionary statistics = connection.RetrieveStatistics();
Console.WriteLine($"ServerRoundtrips: {statistics["ServerRoundtrips"]}");
Console.WriteLine($"SelectRows: {statistics["SelectRows"]}");
Console.WriteLine($"BytesReceived > 0: {(long)statistics["BytesReceived"]! > 0}");

输出显示为一次往返。 行数取决于服务器上的数据库数量:

ServerRoundtrips: 1
SelectRows: 14
BytesReceived > 0: True

RetrieveStatistics 返回快照。 ResetStatistics 开始新的测量边界。 将 StatisticsEnabled 设置为 false 以停止收集。 迄今收集的值仍可用。 统计数据是针对连接对象的,增加了开销,所以应启用它们用于有针对性诊断,而不是每次生产请求。

处理连接失败

在可记录、转换或重试失败操作的边界处捕获 SqlException。 记录:

  • Number
  • State
  • Class
  • ClientConnectionId
  • 操作名称以及配置的服务器和数据库标识符

不要记录连接字符串、密码、客户端机密或访问令牌。

释放已断开的连接。 池检测到无效物理连接时会删除它们。 如果凭证、令牌、证书、DNS目标或服务器发生变化,请在重试前修正配置。

仅对瞬态故障使用有界重试逻辑。 初始开放重试、空闲连接恢复和命令重试是不同的机制。 更多信息请参见“可配置重试逻辑”以及“连接选项”中的连接恢复选项。