.NET Core 6.0类库使用Microsoft.Data.SqlClient ADO.NET报平台不支持异常

在.NET Core 6.0类库项目中，使用Microsoft.Data.SqlClient通过ADO.NET方式查询SQL Server数据库时抛出异常。

异常信息如下：

System.PlatformNotSupportedException: Microsoft.Data.SqlClient is not supported on this platform

问题复现代码：

using (var connection = new SqlConnection(connectionString))
{
    using (var cmd = new SqlCommand(queryString, connection))
    {
        cmd.Connection = connection;
        connection.Open();

        using (SqlDataReader reader = cmd.ExecuteReader())
        {
            while (reader.Read())
            {
                return true;
            }                               
        }
    }
}

该异常和ADO.NET查询逻辑本身无关，属于依赖加载/平台适配层面的错误，常见触发原因：

• 仅在类库项目中引用了Microsoft.Data.SqlClient包，最终实际运行的可执行宿主项目（如ASP.NET Core项目、控制台项目、桌面应用项目等）未引用同版本的包，导致运行时依赖解析失败，加载了不匹配平台的程序集
• 引用的Microsoft.Data.SqlClient版本和.NET 6目标框架不兼容，或误装了仅支持特定平台的版本变体，在非适配系统上运行触发异常
• 发布时开启了程序集裁剪、单文件打包配置，误将SqlClient依赖的平台特定实现程序集排除，导致运行时找不到对应实现
• 编译/发布缓存残留，加载了历史版本的错误程序集

按以下顺序排查修复：

1. 给所有最终会部署运行的可执行宿主项目，安装和类库项目完全同版本的Microsoft.Data.SqlClient稳定版NuGet包，不要仅在类库中添加引用。.NET 6环境推荐使用2.x~5.x区间的稳定正式版本，非Windows环境不要安装带Windows专属依赖的特殊包版本。
2. 如果是发布后运行触发异常，检查发布配置：
   • 关闭不必要的程序集裁剪，或在项目配置中添加SqlClient相关程序集的裁剪排除规则
   • 确认发布时选择的目标运行时标识（RID）和实际部署环境一致，不要将Windows平台的发布包放到Linux/macOS环境运行
3. 清理整个解决方案，删除所有项目下的bin、obj文件夹，重新执行NuGet包还原后完整重新编译，排除旧缓存程序集导致的加载错误。

修复后不需要改动原有ADO.NET查询代码，即可正常连接数据库执行查询。

内容的提问来源于stack exchange，提问作者hbib