Microsoft.Data.SqlClient 是适用于 SQL Server、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics、Microsoft Fabric 中的 SQL 数据库以及 Microsoft Fabric 中的 Warehouse 的受支持的 .NET 数据提供程序。 驱动程序作为 NuGet 包发布，独立于 .NET 运行时。
选择版本
对于生产应用，请使用受支持的正式发布版（GA）。 最新的GA 版本是Microsoft.Data.SqlClient 7.1.1。
| 发布系列 | 最新版本 | 支持级别 | 在以下情况下选择它 |
|---|---|---|---|
| 7.1 | 7.1.1 | 标准期限支持（STS） | 你需要当前的驱动功能，并且可以按常规发布节奏更新。 |
| 7.0 | 7.0.3 | 标准期限支持（STS） | 在 2026 年 12 月 17 日支持终止前，在准备升级时需要服务修补程序。 |
| 6.1 | 6.1.7 | 长期支持 (LTS) | 你更喜欢更长的支持时间，不需要7.x引入的功能。 |
有关当前补丁版本、支持日期、目标框架和数据库兼容性，请参见 SqlClient 驱动支持生命周期。
安装核心包
从包含你项目文件的目录执行以下命令：
dotnet add package Microsoft.Data.SqlClient
该命令选择与项目兼容的最新稳定版本。 要锁定版本以实现可重现构建，请指定版本：
dotnet add package Microsoft.Data.SqlClient --version <version>
该命令会向你的项目文件添加一个 PackageReference 元素。 在7.1.1版本中，项目文件包含以下行：
<PackageReference Include="Microsoft.Data.SqlClient" Version="7.1.1" />
如果你也加上 Microsoft.Data.SqlClient.Extensions.Azure，其 PackageReference 也使用相同的版本。
恢复依赖并构建项目：
dotnet restore
dotnet build
如果恢复或构建报告了关于具有已知漏洞的软件包的警告，如 NU1902 或 NU1903，请按照 报告含已知漏洞的包时要执行的操作中的步骤进行操作。
导入驱动命名空间，用C#语言：
using Microsoft.Data.SqlClient;
对于新应用，不要引用旧的 System.Data.SqlClient 软件包或命名空间。 要更新现有应用程序，请参见从 System.Data.SqlClient 迁移到 Microsoft。Data.SqlClient。
使用 Visual Studio 安装
- 在 解决方案资源管理器 中，右键点击项目，选择管理 NuGet 包。
- 在 浏览标签 中，搜索
Microsoft.Data.SqlClient。 - 选择Microsoft拥有的软件包。
- 选择一个支持的稳定版本，然后选择 安装。
有关详细信息，请参阅 在 Visual Studio 中使用 NuGet 包管理器来安装和管理包。
添加可选套餐
只有当你的应用使用相关功能时，才安装可选包。
| Package | 在以下情况下添加 |
|---|---|
Microsoft.Data.SqlClient.Extensions.Azure |
Microsoft。Data.SqlClient 7.0及更高版本使用驱动程序提供的Microsoft Entra认证模式，如Active Directory Default、、Active Directory Interactive或Active Directory Managed Identity。 |
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider |
Always Encrypted 将列主密钥存储在 Azure 密钥保管库 中。 |
对于使用 SqlClient 7.0 或更高版本进行 Microsoft Entra 身份验证的情况，请运行：
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>
7.0 核心包不再包含 Azure Identity 依赖。 从7.0.2版本开始，核心驱动和配套包使用对齐版本。 引用同一版本的 Microsoft.Data.SqlClient 和 Microsoft.Data.SqlClient.Extensions.Azure。 不使用驱动程序提供的 Microsoft Entra 认证的应用不需要 Azure 扩展包。 关于身份验证设置，请参见 Microsoft Entra 对 Microsoft.Data.SqlClient 的身份验证。
更新驱动程序
在更新之前，请查看以下内容：
阅读 Microsoft.Data.SqlClient 的新增功能以及此次更新所跨越的每个版本的上游发行说明。
列出应用程序的直接和传递包引用：
dotnet list package --include-transitive注意应用程序直接引用的每个配套包，如
Microsoft.Data.SqlClient.Extensions.Azure或Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider。
更新包引用。
dotnet add package Microsoft.Data.SqlClient --version <version>对于7.0.2及更高版本，将每个直接引用的伴随包更新为同一版本。
恢复、构建并运行应用程序测试。
测试连接建立、认证、证书验证、连接池、数据类型转换、事务以及针对每个支持数据库目标的重试行为。
主要和补丁发布可能需要对应用程序进行更改。 例如，4.0 版本默认启用加密，5.0 版本从 SqlConnectionStringBuilder.Encryptbool 变SqlConnectionEncryptOption为 ，7.0 版本将驱动程序提供的 Microsoft Entra 认证移入独立包。
从 7.0.2 版本开始，Microsoft.Data.SqlClient.Extensions.Azure、Microsoft.Data.SqlClient.Extensions.Abstractions 和 Microsoft.Data.SqlClient.Internal.Logging 的程序集版本已从 7.0.0.0 更改为 1.0.0.0。 .NET Framework 应用程序必须基于统一版本的包重新生成，或添加绑定重定向。 当前 .NET 上的应用程序不会受到这次装配身份更改的影响。
理解目标框架
Microsoft.Data.SqlClient 7.1 支持以下平台上的应用程序：
- 支持Windows、Linux和macOS版本的.NET 8或更高版本。
- .NET Framework 4.6.2 或更高版本，适用于 Windows。
NuGet 包还包含一个适用于库的 .NET Standard 2.0 兼容性资产。 可执行应用程序必须以受支持的 .NET 或 .NET Framework 运行时为目标。 库的 .NET Standard 目标并不意味着所有消耗型运行时都被支持。
该包通过 NuGet 恢复其托管依赖和本地依赖。 不要在应用程序之间复制单个驱动程序组件或本地SQL网络接口（SNI）库。
.NET框架项目
这些文章中的示例面向 .NET。 新开发时，使用.NET代替.NET框架。 更多信息请参见 .NET 框架概述。
针对 .NET Framework 的项目默认使用 C# 7.3，因此为 .NET 编写的示例如果不做修改就无法在那里编译。 快速入门：连接并查询 Microsoft.Data.SqlClient 有一个 .NET Framework 标签页，里面有 C# 7.3 版本的示例。
准备部署
发布时，使用与生产中使用的操作系统和架构相同的版本。 对于框架依赖型部署：
dotnet publish --configuration Release针对特定运行时的部署：
dotnet publish --configuration Release --runtime <runtime-identifier>部署完整的发布输出。 不要只选择
Microsoft.Data.SqlClient.dll。确认目标是否具备所需的 .NET 运行时，除非你发布一个自包含的应用程序。
在目标操作系统和架构上测试已发布的输出。
测试生产中使用的所有认证模式。 集成认证、Kerberos、证书、管理身份和Azure 密钥保管库访问取决于部署环境。
扫描已解决的依赖图，寻找已知漏洞，并在有修复时更新支持的包行。
不支持全球化不变模式。 有关当前平台资格认证，请参见 支持的操作系统。
离线软件包安装
从 NuGet.org 下载包及其依赖，复制到内部包源，然后从该源恢复。 为了实现可复现的离线构建，请固定软件包版本并保留完整的依赖项集合。