生产环境唯一靠谱选择是 hdf.pinvoke，它直接封装 hdf5 c 库，支持多平台且兼容 .net standard 2.0+；hdf5dotnet 已多年未维护，.net core/.net 5+ 下易报 dllnotfoundexception 或绑定失败。
用 HDF5DotNet 还是 HDF.PInvoke？选错库直接卡死在第一步
别碰 HDF5DotNet —— 它已多年未维护，.NET Core/.NET 5+ 下几乎必然报 DllNotFoundException 或类型绑定失败。生产环境唯一靠谱选择是 HDF.PInvoke，它直接封装 HDF5 C 库，支持 Windows/macOS/Linux，且兼容 .NET Standard 2.0+。
安装方式很简单：dotnet add package HDF.PInvoke。注意：它不带原生 HDF5 DLL，Windows 用户需额外下载 HDF5 binaries 并把 hdf5.dll（非 hdf5dll.dll）放进输出目录，否则运行时崩在 H5F.open。
- Linux/macOS 要确保
libhdf5.so或libhdf5.dylib在LD_LIBRARY_PATH/DYLD_LIBRARY_PATH中 - Debug 和 Release 模式下，
HDF.PInvoke默认加载不同命名的 DLL（如hdf5dll.dllvshdf5.dll），建议统一用H5.OpenLibrary()手动指定路径 - 不要试图用
System.IO.Packaging或通用二进制读取器打开 HDF5 文件——它不是 ZIP，没有文件头魔数校验，强行读只会得到乱码
H5F.open 失败但没报错？检查文件权限和并发访问
HDF5 文件不是普通文本，H5F.open 返回负值却无异常，大概率是底层 C 函数静默失败。常见原因不是代码写错，而是环境问题：
- Linux/macOS 下文件被其他进程（如 Python 的
h5py、MATLAB）以写模式打开，C# 只能用H5F.ACC_RDONLY打开；若需读写，必须确保无人占用 - Windows 上 NTFS 权限不足（尤其网络共享盘），即使
File.Exists返回true，H5F.open仍会失败 - 路径含中文或 Unicode 字符？
H5F.open在旧版 HDF5（Path.GetFullPath 归一化，再转为 UTF-8 byte 数组传入
读 double[10000, 512] 数组为什么慢？绕过托管堆拷贝
直接用 H5D.read + double[] 分配，等于让 HDF5 库把数据先写进非托管内存，再由 P/Invoke 自动拷贝到托管数组——100MB 数据就是两次内存搬运，CPU 和 GC 压力都大。
正确做法是预分配非托管内存，用指针直通：
var buffer = Marshal.AllocHGlobal(10000 * 512 * sizeof(double));
H5D.read(datasetId, H5T.NATIVE_DOUBLE, H5S.ALL, H5S.ALL, H5P.DEFAULT, buffer);
// 后续用 unsafe { double* ptr = (double*)buffer; ... }
// 记得最后 Marshal.FreeHGlobal(buffer)- 若必须返回托管数组，用
Marshal.Copy(buffer, managedArray, 0, length)，比自动转换快 3–5 倍 - 小数组（10MB 时，手动管理内存延迟下降明显
-
H5D.read不支持部分读取（partial read）的托管数组重用，每次都要新分配——这点和 NumPy 的memmap完全不同
写入字符串字段总变空？HDF5 的 H5T.C_S1 不等于 C# string
HDF5 本身不存 .NET string 对象，字符串必须显式声明为固定长度 ASCII 类型（H5T.C_S1）或可变长度类型（H5T.C_S1 + H5T.set_size(H5T.VARIABLE)）。直接传 "hello" 给 H5D.write，底层会按指针解引用，结果是随机内存内容。
- 写定长字符串：先用
H5T.copy(H5T.C_S1)，再H5T.set_size(typeId, 256)，数据传Encoding.ASCII.GetBytes("hello")填满 256 字节 - 写变长字符串：必须用
H5T.C_S1+H5T.set_size(H5T.VARIABLE)，数据传new IntPtr[] { Marshal.StringToHGlobalAnsi("hello") }，写完要逐个Marshal.FreeHGlobal - 别信文档里 “HDF5 supports UTF-8”——C# 侧仍要自己做编码转换，
Encoding.UTF8.GetBytes是安全的，但读回来得用Encoding.UTF8.GetString显式解码
复杂点在于：同一个 HDF5 文件里混用定长和变长字符串类型，元数据描述完全不同，读写逻辑必须严格匹配，差一个 flag 就读出乱码或崩溃。这点很容易被忽略，尤其当文件由 Python 生成、C# 读取时。
