C# 中解析 BAM/SAM 文件应使用 Htslib.Net 而非自行封装或调用外部命令；它封装了 BGZF 解压、header 解析与 record 迭代，需确保匹配架构的 native 库可用，并配合 region 查询、CigarElement 解析及单线程 reader 实例使用。
用 SamTools 还是 HTSlib 的 C# 绑定？别自己封装
直接上结论：C# 生态里没有成熟、维护活跃的原生 BAM/SAM 解析库，强行用 System.IO.BinaryReader 手撕格式会掉进字节序、块压缩、索引偏移、CIGAR 解析等深坑。目前唯一靠谱路径是调用 htslib（C 实现）的跨平台绑定——推荐使用 htsjdk 的 .NET 移植版 Htslib.Net，它封装了 bgzf 解压、BAM header 解析、record 迭代等关键逻辑。
常见错误现象：InvalidDataException 或读出乱码 CIGAR，基本是因为跳过了 BGZF 块头校验，或误把未解压的 block 当作原始字节处理。
-
Htslib.Net依赖本地libhts.so（Linux）/hts.dll（Windows），必须确保运行时能找到对应架构的动态库（x64/x86 匹配） - 不要用
Process.Start("samtools")调外部命令——启动开销大、无法流式读取、错误码难捕获 - 如果项目不能引入 native 依赖，只能退到预处理：用
samtools view -b把 SAM 转成 BAM 后再交给 C# 处理，否则纯托管解析性能极差
SamReader 流式读取时内存暴增？必须设 bufferSize 和 region
默认构造 SamReader.Open() 会加载整个 BAM 文件头 + 索引（.bai），但真正危险的是不加约束地遍历 record——尤其全基因组 WGS 数据，单个 chromosome 就可能含数千万条 alignment，全 load 到内存就崩。
使用场景：只分析 chr17 上 BRCA1 区域（17:41196312-41277500）的比对质量
- 务必用
SamReader.Open(path, new SamReaderOptions { BufferSize = 64 * 1024 })控制内部 BGZF 缓冲区大小，避免默认 1MB 导致 GC 压力 - 用
reader.Query("17", 41196312, 41277500)替代reader.GetEnumerator()，它走的是 BAI 索引二分查找，不是全文扫描 - 注意：region 查询要求 BAM 已用
samtools index生成 .bai 文件，否则降级为全文件扫描，速度慢十倍以上
Cigar 字符串解析别用 string.Split，用 CigarElement 类型
看到 "10M2D5M" 就想 .Split('M','D')？这会漏掉数字和操作符的绑定关系，且无法处理 S（soft clip）、N（intron）、H（hard clip）等语义差异。CIGAR 是位置敏感的序列操作指令，错一位就导致坐标映射全错。
性能影响：手动解析字符串比调用 cigar.GetCigarElements() 慢 3–5 倍，且易出边界错误
-
CigarElement对象带Length和Operation属性，比如new CigarElement(10, CigarOperation.M) - 特别注意
Operation.N表示参考序列上的 gap（如剪接位点），此时 query 序列不推进，但 ref 坐标要跳过对应长度 - 如果需要反向计算 query → ref 坐标，必须遍历全部
CigarElement累加，不能只看开头 M/N
多线程并发读同一个 SamReader 实例？会崩溃
SamReader 不是线程安全的——它的内部 bgzf_stream 句柄、缓冲区指针、当前 block 偏移都是共享状态。多个线程同时调 Query() 或 GetEnumerator().MoveNext()，大概率触发 AccessViolationException 或返回错乱 record。
容易踩的坑：写了个 Parallel.ForEach 想加速 region 查询，结果跑两轮就 core dump
- 每个线程必须持有一个独立
SamReader实例（即每次SamReader.Open()） - 但不要在循环内反复 Open/Close——BAM 索引加载开销大，建议按 chromosome 预先打开多个 reader，复用它们
- 如果真要共享底层文件句柄，得自己加
lock，但性能还不如单线程流式读；不如用PLINQ处理 record 解析后的业务逻辑（比如质量过滤、UMI 统计）
最麻烦的其实是索引一致性：.bai 文件更新滞后于 BAM 时，Query 会返回空结果，但不报错——得养成每次处理前校验 File.GetLastWriteTime(bamPath) > File.GetLastWriteTime(baiPath) 的习惯。
