Microsoft.Data.SqlClient for SQL Server

下载 ADO.NET

Microsoft.Data.SqlClient 是用于 SQL Server、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics 和 Microsoft Fabric 中的 SQL 数据库的受支持的 .NET 数据提供程序。 它以 NuGet 包的形式提供，独立于 .NET 运行时单独演进，并在新的开发项目中取代 System.Data.SqlClient。 它用于打开连接、执行命令、处理结果、管理事务、批量加载数据，以及使用 .NET 应用程序中 SQL Server 特有的功能。

选择起点

Azure SQL的生产基线

将此片段作为面向生产环境的 Azure SQL 数据访问路径的起点。 它从 IConfiguration 读取服务器和数据库名称，因此这些值来自主机连接的各种配置提供程序（appsettings.json、环境变量、Azure 应用配置、密钥保管库 支持的设置等）。 该配置结合了传输层安全（TLS）、托管身份、空闲连接弹性、通过可配置重试逻辑（CRL）进行初始连接重试，并配有结构化日志、命令级重试以处理查询中触发的瞬态错误，以及快速故障转移组恢复。

为了提高安全性并支持跨环境配置，建议将连接信息保留在代码之外。 在生产环境中，将连接信息存储在应用的配置系统中，敏感值则使用 Azure 密钥保管库。 有关详细信息，请参阅 保护连接信息。

为简洁起见，本文中的 C# 代码片段省略了 using 指令和类包装。

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

此代码片段适用于任何配置为使用 Microsoft Entra 身份验证的 SQL 数据库引擎 终结点：Azure SQL 数据库、Azure SQL 托管实例、Microsoft Fabric 中的 SQL 数据库，以及在 Azure 虚拟机 上运行的或由 Azure Arc 启用的 SQL Server 2022 及更高版本。

Encrypt = SqlConnectionEncryptOption.Strict 选择TDS 8.0加密。 它需要Microsoft。Data.SqlClient 5.0及以后版本，以及支持TDS 8.0的服务器（SQL Server 2022及以后版本）、Azure SQL 数据库、Azure SQL 托管实例和Microsoft Fabric中的SQL数据库。 当你连接到较旧的服务器时，回退到 SqlConnectionEncryptOption.Mandatory。

ConnectRetryCount 并 ConnectRetryInterval 启用 空闲连接弹性：成功后 Open() ，驱动程序在下一个命令中透明地重新连接已断开的空闲连接。 他们不会重试首次的 Open()。 初始连接重试来自分配给 SqlConnection.RetryLogicProvider 的 openRetry 提供程序。 这两者是互补的。

每个提供者的 Retrying 事件在每次重试前触发，并包含重试计数、下一次尝试前的延迟以及迄今为止观察到的异常情况。 将其路由到 ILogger 或你的遥测管道，以便在生产环境中让重试循环保持可见。

当目标对象是 Azure SQL 数据库、Azure SQL 托管实例、Microsoft Fabric 中的 SQL 数据库、可用性组监听器或故障转移集群实例时，设置MultiSubnetFailover = true。 它会选择一条并行连接代码路径，尝试并行地对所有已解析出的 IP 地址发起 TCP 连接，并使用首个成功建立的连接，从而避免逐个 IP 依次尝试的缓慢顺序遍历，以免这些连接因此发生阻塞。 对于单IP目标，设置是安全的。 当你连接到命名实例、使用 TCP 以外的协议，或连接到配置了 64 个以上 IP 地址的实例时，不支持 MultiSubnetFailover。 你也不能将其与数据库镜像配合使用，因为数据库镜像在所有受支持的 SQL Server 版本中都已弃用。 请使用 Always On 可用性组来替代其他解决方案。 更多信息请参见 高可用性与灾难恢复 以及 禁用透明网络IP解析。

如果目标是启用了自动暂停的 Azure SQL 数据库无服务器，请将 ConnectTimeout 提高到至少 60 秒。 自动暂停的数据库会在首次 Open() 时恢复，而在数据库恢复期间，该首次 Open() 可能会失败，并返回错误 40613。 错误 40613 在内置的瞬态错误列表中，所以 openRetry 重试它。 客户端超时会以错误 -2的形式出现，但不在列表中，所以 openRetry 无法挽救 Open() 中途超时的情况。 单个连接尝试的尝试时间必须足够长，以覆盖恢复的整个过程。 更多信息请参见 自动暂停和自动恢复。

是否进行命令级重试，由调用方针对每个命令分别决定。 仅当重放命令安全时，才将 commandRetry 附加到 SqlCommand.RetryLogicProvider 上：包括读取操作、由自然键保护的 MERGE、通过存储过程执行的插入以及其他幂等操作。 内置命令提供者在事务活跃时跳过重试，因此多语句事务必须由能够重新开启事务的应用代码重试。 设置TransientErrors取代了驱动内置的错误列表;要扩展内置基线，请使用 SqlConfigurableRetryFactory.BaselineTransientErrors （Microsoft.Data.SqlClient 7.0及以后版本）。

有关此配置的每个部分的详细信息，请参阅：

主要功能

  • 现代 .NET 支持：运行在当前的 .NET 和 .NET 框架版本上。 关于各版本的详细分解，请参见 支持生命周期。
  • 默认加密：默认使用 Encrypt=true 的 TLS 加密连接。 为 Microsoft.Data.SqlClient 5.0 及更高版本的 TDS 8.0 加密设置 Encrypt=Strict。
  • Microsoft Entra ID 身份验证：通过托管标识、服务主体、交互、集成、默认凭据链和访问令牌流实现无密码连接。
  • Kerberos 和 NTLM：用于本地 Active Directory 和遗留场景的集成式 Windows 身份验证。
  • Always Encrypted：针对敏感列的客户端加密，并支持用于就地操作的可选安全隔离区。
  • 批量复制导入：使用 SqlBulkCopy 进行高吞吐量插入。
  • 连接弹性：内置连接重试（ConnectRetryCount 和 ConnectRetryInterval）以及可选择可配置的重试逻辑，用于连接和命令。
  • 丰富的SQL Server数据类型：datetimeoffset、、sql_variantJSON、向量、空间、XML和表值参数。
  • 诊断：事件源追踪、诊断计数器、提供者统计数据以及专门的故障排除指南。

开始

文章 Description
SqlClient 驱动程序入门 搭建项目，创建数据库，连接、查询，并添加连接弹性。
SqlClient 驱动程序概述 了解 Microsoft.Data.SqlClient 如何融入 ADO.NET。
下载Microsoft。Data.SqlClient 安装 NuGet 包并查找源代码发布版本。
支持生命周期 请查看支持的驱动版本和支持日期。
Microsoft。Data.SqlClient 命名空间 从 System.Data.SqlClient 迁移，并检查命名空间的差异。

配置和连接

文章 Description
连接到数据源 打开并管理对SQL Server和Azure SQL的连接。
连接字符串 配置服务器、数据库、认证、加密和连接行为。
加密和证书验证 配置加密连接和服务器证书验证。
SQL Server 连接池 高效地重复利用物理连接。
连接事件 响应连接状态和信息消息。

认证与安全

文章 Description
SQL Server 安全性 请查看认证、授权和应用安全指南。
Microsoft Entra 身份验证 连接托管身份、服务主体、密码和交互流。
保护连接信息 不要把凭据和连接设置写进应用代码。
始终加密 保护敏感列值免受数据库系统影响。
具有安全隔区的 Always Encrypted 在加密数据上运行丰富的操作，并设置一个安全的隔离区。

检索和更新数据

文章 Description
命令和参数 执行参数化的SQL语句和存储过程。
DataAdapter 和 DataReader 流式传输结果集，或填充断开连接的数据结构。
事务和并发性 使用本地和分布式事务以及并发控制。
检索数据库模式信息 探索模式集合和限制。
批量复制操作 借助 SqlBulkCopy 高效加载大型数据集。
表值参数 向参数化语句或存储过程发送多行数据。
异步编程 使用异步连接、命令和数据操作。
多重活动结果集 (MARS) 在同一连接上交错执行多个批次。

数据类型

文章 Description
ADO.NET 数据类型映射 将常用语言运行时类型映射到提供者类型和 SQL Server 类型。
SQL Server 数据类型 使用 SQL Server 特有的值和 System.Data.SqlTypes 类型。
JSON 数据 发送和检索 SQL Server json 数据类型。
向量数据 发送和检索向量值。
XML数据 读取、写入并参数化XML值。
二进制和大值数据 流式处理并更新二进制、FILESTREAM 和大值数据。

可靠性与诊断

文章 Description
可配置的重试逻辑 使用有边界的策略重试瞬态连接故障和命令故障。
高可用性和灾难恢复 连接可用性组侦听器和故障转移伙伴。
诊断计数器 监控活跃连接、合并连接及其他驱动指标。
启用事件源追踪 详细记录驾驶事件以供诊断。
数据追踪 追踪ADO.NET操作和数据访问。
SqlClient 故障排除指南 诊断常见连接和驱动问题。
查询通知 查询结果变更时收到通知。

SQL Server功能

文章 Description
SQL Server 功能和 ADO.NET 浏览通过 SqlClient 提供的 SQL Server 专属功能。
本地数据库 连接到 SQL Server Express LocalDB 实例。
数据发现和分类 从结果集中读取敏感性分类元数据。

参考和资源

文章 Description
Microsoft.Data.SqlClient API 参考 浏览驱动程序的 .NET API 参考。
AppContext 开关 配置兼容性和安全行为。
查找更多 SqlClient 信息 查找源代码、支持和社区资源。

相关内容

  • Last updated on