.NET 8项目单文件发布时Sap.Data.Hana.Net.v8.0驱动加载失败

问题场景 #

在.NET 8 CLI程序中使用Sap.Data.Hana.Net.v8.0.dll连接SAP HANA数据库时，开启单文件发布选项会触发以下错误：

Source : System.Private.CoreLib
Message : Value cannot be null. (Parameter 'path1')
Failed Load

不启用单文件发布时程序运行正常，但发布目录会生成大量DLL，需解决单文件发布下的兼容问题。

问题原因 #

SAP HANA的.NET驱动内部依赖读取自身DLL的物理路径，或依赖未被正确嵌入的原生组件。单文件发布模式下，所有程序集被打包到单个可执行文件中，运行时不会释放到磁盘，导致驱动无法获取有效路径，进而抛出空参数异常。

解决方案 #

1. 将SAP驱动排除在单文件嵌入之外 #

在项目文件（.csproj）中添加配置，让Sap.Data.Hana.Net.v8.0.dll保留为独立文件，不被嵌入到单文件中：

<ItemGroup>
  <PublishSingleFile Include="Sap.Data.Hana.Net.v8.0.dll" ExcludeFromSingleFile="true" />
</ItemGroup>

发布后该DLL会和单文件EXE放在同一目录，驱动可正常读取物理路径，同时其他依赖仍被嵌入，大幅减少发布文件数量。

2. 处理驱动的原生依赖 #

若驱动依赖原生库（如Windows下的adonetHDB.dll、Linux下的libadonetHDB.so），需确保这些文件被复制到发布目录，并在代码中指定路径：

// 初始化HANA连接前设置原生库路径
Environment.SetEnvironmentVariable("HDB_CLIENT_LIB_PATH", Path.Combine(AppContext.BaseDirectory, "hdb_libs"));

同时在项目文件中配置原生库的复制规则：

<ItemGroup>
  <Content Include="hdb_libs\**">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </Content>
</ItemGroup>

3. 改用SAP官方NuGet包 #

移除手动引用的Sap.Data.Hana.Net.v8.0.dll，安装SAP官方发布的.NET兼容HANA驱动NuGet包（如SAP.HANA.Client）。官方NuGet包已适配单文件发布逻辑，可自动处理依赖嵌入和路径问题。

4. 启用单文件发布的自提取模式 #

在项目文件中添加以下配置，让单文件运行时自动将必要的原生库提取到临时目录：

<PropertyGroup>
  <PublishSingleFile>true</PublishSingleFile>
  <SelfContained>true</SelfContained>
  <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
</PropertyGroup>

该模式会解决驱动的路径依赖问题，但会增加程序首次启动的耗时。

验证步骤 #

修改配置后，执行发布命令：

dotnet publish -c Release -r <目标运行时> --self-contained true

运行生成的单文件EXE，测试SAP HANA数据库连接是否正常。

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