Microsoft。Data.Sql客户端命名空间与兼容性

命名Microsoft.Data.SqlClient空间包含支持的 .NET 数据提供者，用于兼容 SQL Server 的数据库。 它最初是从 System.Data.SqlClient 分支而来的，同时保留了人们熟悉的 ADO.NET 编程模型，并且能够独立于 .NET 运行时发布新的 SQL Server 功能。

请使用 Microsoft.Data.SqlClient 进行新开发。

安装并导入命名空间

添加NuGet包：

dotnet add package Microsoft.Data.SqlClient

导入命名空间：

using Microsoft.Data.SqlClient;

大多数应用使用 SqlConnection、 SqlCommand、 SqlParameter、 SqlDataReader和 SqlTransaction。 完整的公开表面，请参见 Microsoft.Data.SqlClient API 参考。

与ADO.NET的关系

ADO.NET 是内置于 .NET 的数据访问模型。 它在 System.Data.Common 命名空间中定义了与提供程序无关的抽象，而 Microsoft.Data.SqlClient 提供了具体实现。

ADO.NET 抽象 SqlClient 类型 Purpose
DbConnection SqlConnection 打开与某个数据库的逻辑连接。
DbCommand SqlCommand 执行 Transact-SQL（T-SQL）文本或存储过程。
DbParameter SqlParameter 发送一个与命令文本分开的输入值。
DbDataReader SqlDataReader 从服务器流式传输结果行。
DbTransaction SqlTransaction 将命令分组到一个事务中，作为一个整体提交或回滚。
DbDataAdapter SqlDataAdapter 填充并更新已断开连接的 DataSet 和 DataTable 对象。
DbBatch SqlBatch 在支持的目标框架上，将多个命令作为一个批次发送。

Microsoft.Data.SqlClient 还提供针对 SQL Server 的专用 API，例如：

  • SqlBulkCopy
  • SqlConnectionStringBuilder
  • SqlConfigurableRetryFactory
  • SqlDependency
  • SQL Server 专用的认证、加密和数据类型支持

当库需要支持多个数据库提供者时，针对ADO.NET抽象进行编程。 当应用以 SQL Server 为目标并需要提供程序特定功能时，可以使用 SqlClient 类型，如 Microsoft Entra 身份验证、Always Encrypted、批量复制、表值参数或可配置的重试逻辑。 如果应用的其他部分必须保持提供者独立，则将特定提供者代码保留在数据访问边界后。

已连接和已断开访问

连接式访问 在命令运行期间以及应用程序读取其结果时保持连接开启。 典型请求通常遵循以下顺序：

  1. 从一个连接字符串创建一个SqlConnection，然后打开它。
  2. 创建一个 SqlCommand 并添加 SqlParameter 值。
  3. 执行命令。
  4. 处理标量值、受影响行计数或 SqlDataReader。
  5. 丢弃读卡器、命令和连接。

对大多数 Web API、服务、Worker 和命令行应用程序使用连接式访问。 SqlDataReader 以流式方式处理行数据，通常比将整个结果加载到 DataSet 中占用更少的内存。

已断开访问使用 SqlDataAdapter 将数据复制到内存中的 DataSet 或 DataTable。 应用程序可以在读取或更改内存数据时关闭连接，然后重新连接以提交更新。 将其用于数据绑定、内存关系和约束、稍后协调的离线编辑，或用于围绕 DataAdapters 构建的现有应用程序。 对于新的请求导向服务，请从SqlDataReader和SqlCommand开始。

对象生命周期与并发

为每个工作单元打开并释放一个 SqlConnection。 连接池会重用底层的物理连接，所以不要在应用生命周期内保持一个全局连接开放。 及时丢弃连接、命令、读取器、事务和批量复制对象。 在异步代码中，对于在目标框架上实现 SqlConnection 的类型，使用 IAsyncDisposable，例如 .NET 上的 SqlDataReader 和 using；而对于仅实现 await using 的类型，则使用普通的 IDisposable，例如 SqlBulkCopy。

SqlConnection、SqlCommand、SqlDataReader和SqlTransaction不支持多个线程并发使用。 为每个并发操作分配各自独立的连接，并利用连接池。 多激活结果集（MARS）允许连接上有多个活跃结果集，但并不保证 SqlClient 对象是线程安全的。

与System.Data.SqlClient的关系

System.Data.SqlClient是较早的供应商，提供 .NET 框架和更早的 .NET 版本。 Microsoft.Data.SqlClient 它使用许多相同的类型名称，但包、命名空间、默认值、功能和支持策略不同。

不要在新的申请代码中提及两个提供者。 来自这两个包的同名类型不能互换使用。 例如，一个 System.Data.SqlClient.SqlConnection 不能传递给需要 Microsoft.Data.SqlClient.SqlConnection 的地方。

迁移通常从添加 Microsoft.Data.SqlClient 包和更改命名空间引用开始，但你还必须审查连接加密、参数、配置、传递依赖和运行时行为。 在部署之前，请先按照 从 System.Data.SqlClient 迁移到 Microsoft.Data.SqlClient 进行操作。

版本兼容性

驱动程序包版本独立于应用程序的 .NET 版本和数据库引擎版本。 请查看这三部作品：

组件 需要验证的内容
Microsoft.Data.SqlClient 发布行是支持的，包含你的应用所用的功能。
.NET 或 .NET 框架 该应用程序的目标运行时由该驱动版本支持。
兼容SQL Server的数据库 驱动版本支持数据库版本，服务器支持任何请求的协议功能，如TDS 8.0。

关于当前矩阵，请参见 SqlClient 驱动支持生命周期。

版本特定的更改

驱动程序发布可以添加API、移动可选依赖，并更改安全默认。 每次进行次要更新或重大更新前，都要检查更改。

示例包括：

  • 4.0版本默认改 Encrypt 为 true。
  • 5.0 版本引入了用于 TDS 8.0 的 SqlConnectionEncryptOption 和 Encrypt=Strict。
  • 5.2版本引入SqlBatch于支持的现代.NET目标上。
  • 7.0版本将驱动程序提供的Microsoft Entra认证迁移到了 Microsoft.Data.SqlClient.Extensions.Azure。

请参阅 Microsoft.Data.SqlClient 中的新增功能，了解发布说明链接和升级摘要。

部分功能使用主命名空间外的类型或可选包。

命名空间或包 Purpose
Microsoft.Data.SqlClient.Server SqlDataRecord 和 SqlMetaData 的 SqlClient 实现。
Microsoft.Data.SqlTypes SqlClient 专有类型，例如 SqlFileStream、SqlJson 和 SqlVector<T>。
Microsoft.Data.SqlClient.Diagnostics 强类型的诊断事件负载。
Microsoft.Data.SqlClient.Extensions.Azure 适用于 7.0 及更高版本的由驱动程序提供的 Microsoft Entra 身份验证
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider Azure 密钥保管库 与 Always Encrypted 集成。

不要仅凭命名空间推断包的需求。 请参照专题文章以及针对所使用驱动程序版本的 NuGet 包依赖信息。

相关内容

  • 上次更新时间为