.NET8类库DLL加载Microsoft.Data.SqlClient版本不匹配异常求助

场景重现 #

使用Visual Studio 2022 Community v17.9.6创建目标框架为.NET8的类库项目，项目文件如下：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <AssemblyName>AchieveResource</AssemblyName>
    <RootNamespace>Achieve.AchieveResource</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Azure.Identity" Version="1.11.0" />
    <PackageReference Include="Microsoft.Data.SqlClient" Version="5.2.0" />
  </ItemGroup>

  <ItemGroup>
    <Reference Include="Achieve.Common">
      <HintPath>..\Achieve.Common\bin\Debug\net8.0\Achieve.Common.dll</HintPath>
    </Reference>
  </ItemGroup>

  <ItemGroup>
    <Compile Update="AchieveResource1.Designer.cs">
      <DesignTime>True</DesignTime>
      <AutoGen>True</AutoGen>
      <DependentUpon>AchieveResource1.resx</DependentUpon>
    </Compile>
  </ItemGroup>

</Project>

现有控制台应用直接引用该类库DLL，调用静态方法：

OUConstr = Achieve.AchieveReserouce.ConnectionStrings.GetConnectionSringForOU(1004);

抛出如下异常：

FileNotFoundException: Could not load file or assembly 'Microsoft.Data.SqlClient, Version=5.0.0.0, Culture=neutral, PublicKeyToken=23ec7fc2d6eaa4a5'. The system cannot find the file specified.
System.TypeInitializationException
  HResult=0x80131534
  Message=The type initializer for 'Achieve.AchieveReserouce.ConnectionStrings' threw an exception.
  Source=AchieveResource
  StackTrace:
   at Achieve.AchieveReserouce.ConnectionStrings.GetEnterpriseConnectionString()
   at Program.<Main>$(String[] args) in C:\Dev\Achieve\2022Projects\ConsoleApp1\Program.cs:line 4

  This exception was originally thrown at this call stack:
    [External Code]

Inner Exception 1:
FileNotFoundException: Could not load file or assembly 'Microsoft.Data.SqlClient, Version=5.0.0.0, Culture=neutral, PublicKeyToken=23ec7fc2d6eaa4a5'. The system cannot find the file specified.

此前尝试引用System.Data.SqlClient 4.8.6时，也出现类似的依赖找不到异常。

原因分析 #

1. 直接引用DLL的依赖传递问题：控制台项目直接引用类库DLL时，类库依赖的NuGet包（如Microsoft.Data.SqlClient）不会自动被复制到控制台项目的输出目录，运行时CLR无法找到这些依赖程序集。
2. 程序集版本不匹配：类库引用的是Microsoft.Data.SqlClient 5.2.0，但运行时请求的是5.0.0.0，可能是类库的间接依赖（如Achieve.Common）引用了旧版本，或者版本重定向配置缺失导致CLR无法找到正确版本的程序集。

解决方案 #

方案1：改用项目引用（推荐） #

• 将类库项目添加到控制台应用所在的解决方案中
• 右键控制台项目 → 添加 → 项目引用，勾选AchieveResource类库
• 构建解决方案后，NuGet管理系统会自动处理依赖传递，将所有必要的程序集复制到控制台项目的输出目录，避免缺失问题。

方案2：手动复制依赖程序集（适用于无法添加项目引用的场景） #

• 找到类库项目输出目录（如..\AchieveResource\bin\Debug\net8.0）下的Microsoft.Data.SqlClient.dll及相关依赖文件（如Microsoft.Data.SqlClient.SNI.dll）
• 将这些文件复制到控制台项目的输出目录（如bin\Debug\net8.0）

方案3：配置程序集版本重定向（解决版本不匹配问题） #

如果是版本不匹配导致的异常，可在控制台项目中添加版本重定向配置：

对于.NET 8控制台项目，修改runtimeconfig.template.json：

{
  "runtimeOptions": {
    "assemblyBinding": {
      "dependentAssembly": [
        {
          "assemblyIdentity": {
            "name": "Microsoft.Data.SqlClient",
            "publicKeyToken": "23ec7fc2d6eaa4a5",
            "culture": "neutral"
          },
          "bindingRedirect": {
            "oldVersion": "0.0.0.0-5.2.0.0",
            "newVersion": "5.2.0.0"
          }
        }
      ]
    }
  }
}

若使用.NET Framework风格配置（如控制台项目兼容.NET Framework），修改app.config：

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="Microsoft.Data.SqlClient" publicKeyToken="23ec7fc2d6eaa4a5" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-5.2.0.0" newVersion="5.2.0.0" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

方案4：统一所有项目的依赖版本 #

检查Achieve.Common类库的依赖配置，确保其引用的Microsoft.Data.SqlClient或System.Data.SqlClient版本与AchieveResource类库一致，避免跨项目的版本冲突。

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