Microsoft.Data.SqlClient报平台不支持异常的排查解决方法

异常基本信息 #

运行项目时抛出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 (var reader = cmd.ExecuteReader())
        {
            while (reader.Read())
            {
                return true;
            }                              
        }
    }
}

核心产生原因 #

该异常本质是当前运行环境下，加载到的Microsoft.Data.SqlClient程序集没有对应平台的适配实现，常见触发场景包括：

• 运行环境不在SqlClient支持范围内：比如在Blazor WASM浏览器沙箱、非Windows平台引用了Windows专属的SNI版本SqlClient，或者在ARM架构设备上使用了仅支持x86/x64架构的老版本SqlClient
• 依赖加载冲突：项目同时引用了旧版System.Data.SqlClient和新版Microsoft.Data.SqlClient，或者解决方案下不同项目引用了差异过大的SqlClient版本，导致运行时加载了错误平台的适配程序集
• 发布/编译异常：自包含发布、单文件发布时开启了激进裁剪，误删了SqlClient的平台原生依赖；或者bin/obj目录缓存了旧版本损坏的依赖文件，编译时没有正确拷贝对应平台的runtime文件
• SDK已知bug：.NET 6、.NET 7早期版本的SDK在创建类库、控制台项目时，存在NuGet依赖解析错误，不会自动拉取SqlClient对应的平台runtime包

分步修复方案 #

按优先级从高到低依次排查：

• 先确认运行环境兼容性
  Microsoft.Data.SqlClient 从2.0版本开始拆分了平台适配逻辑：如果在Linux/macOS环境运行，不要手动引用Windows专属的Microsoft.Data.SqlClient.SNI包；如果是Blazor WASM等受沙箱限制的前端环境，不要直接用SqlClient直连数据库，必须通过后端服务接口中转数据库访问。
• 统一项目依赖版本
  打开csproj项目文件，删除所有旧的System.Data.SqlClient引用、重复的不同版本Microsoft.Data.SqlClient引用，单独安装最新稳定版Microsoft.Data.SqlClient包，标准引用格式如下：

  <PackageReference Include="Microsoft.Data.SqlClient" Version="5.1.5" />
  

  解决方案下所有类库、可执行项目如果用到SqlClient，必须统一引用同一个大版本，避免版本冲突。
• 清理缓存重新编译
  关闭开发编辑器，手动删除解决方案下所有bin、obj文件夹，打开终端在解决方案根目录执行以下命令重新拉取依赖编译：

  dotnet restore
  dotnet build
  

  排除旧缓存文件导致的程序集加载错误。
• 调整发布配置
  如果是做自包含部署、单文件部署，先临时关闭程序集裁剪功能测试是否恢复正常。如果确认是裁剪导致的异常，在csproj中添加SqlClient相关的裁剪排除配置；部署后检查部署目录下的runtimes文件夹，确认存在对应运行平台的SqlClient原生动态库文件。
• 程序集加载校验
  如果以上步骤都无效，在程序启动入口添加调试代码，打印运行时加载的Microsoft.Data.SqlClient程序集的实际路径、版本号，确认没有加载到系统全局程序集缓存（GAC）中残留的其他版本错误程序集。

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