用C#解析STEP文件：从ISO-10303-21文本到B-Rep拓扑提取

简介：基于C#的STEP文件解析器完整源码与项目说明，属于本科毕设项目，主要面向计算机相关专业毕业生及需要工程实战的C#学习者。项目围绕STEP中性文件解析展开，实现了对文件中各组成元素的类型识别、详细信息提取，以及拓扑结构的建立与保存，并编写转换器将STEP转换为通用STL格式，最终借助Three.js在WinForm界面中加载和显示3D图形，技术栈涵盖C#、WebGL与Three.js。压缩包共19个文件，以.cs源文件为主，配合.sln/.csproj工程配置、.resx界面资源及项目说明文档，整体仅35KB，代码结构精炼，便于快速阅读与二次开发。资源包含完整的可运行工程与配套说明，既可直接用于本科毕业设计、课程设计或期末大作业，也可作为STEP解析器设计与C#图形编程的参考案例。目前已有1365人学习下载，适合需要项目实战的C#学习者借鉴。

1. STEP文件解析器在C#里的起点：把文本拆成可遍历的对象

拿到一个STEP文件，最直接的反应是用记事本打开，看到的是几千行#123=DIRECTION('',(0.,0.,1.));这样的文本。文本本身能读懂，但程序要拿它做事，绕不开一个基础步骤：把这段 ISO-10303-21 格式的文本翻译成对象模型。这就是C#开发STEP文件解析器要解决的问题。它不依赖OpenCASCADE这类重型几何内核，纯C#就能把常见的点、方向、面、壳和实体关系拆出来，输出给统计、可视化或格式转换使用。这个解析器适合毕设接手者快速理解CAD数据交换的底层机制，也适合C#上位机开发者做CAD文件预处理。

2. STEP文件格式与ISO-10303-21语法：解析器的输入边界

写解析器之前，必须先弄清输入文件的边界。STEP文件不是XML那样的结构化标记语言，它是一条一条以分号结尾的文本记录。整个文件由几个固定段组成，每条记录只占一行或跨多行。用C#做解析，第一件事就是理解这些文本片段各自代表什么。

2.1 三段式文件骨架：HEADER、DATA与解析器的读取策略

一个典型的STEP文件长下面这样：

ISO-10303-21; HEADER; FILE_DESCRIPTION((''),'2;1'); FILE_NAME('part.stp','2024-05-01T10:00:00',('user'),('company'),'','',''); FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }')); ENDSEC; DATA; #1=CARTESIAN_POINT('P0',(0.,0.,0.)); #2=DIRECTION('Z',(0.,0.,1.)); #3=AXIS2_PLACEMENT_3D('A3D',#1,#2,$); #4=VERTEX_POINT('V',#1); ENDSEC; END-ISO-10303-21;

解析器的读取策略只关注两个段：HEADER段和DATA段。HEADER段里FILE_SCHEMA指明文件遵循哪个应用协议，常见的是AUTOMOTIVE_DESIGN（AP214）和CONFIG_CONTROL_DESIGN（AP203）。解析器不需要理解协议内容，但可以在解析结果里暴露这个字段，方便上层判断坐标系单位或几何类型。

DATA段才是主体。每条实体记录以#开头，后跟数字编号，然后=连接实体类型名和括号包裹的参数列表。注意三点：记录之间用分号分隔，但分号可能出现在字符串内部；参数列表可能跨多行；$表示该参数未定义。理解了这三点，就可以确定切分策略——逐字符扫描，而不是简单Split(';')。这个结论是整个解析器的地基。

2.2 实体记录语法：类型名、参数表与必须处理的转义规则

实体记录可以拆成三部分：编号、类型和参数。编号是全局唯一的非负整数；类型名是STEP标准里定义的实体名称，C#里可以直接映射成CamelCase的类名，比如CARTESIAN_POINT对应CartesianPoint；参数列表则是括号内的逗号分隔序列。

参数有五种形态，遇到时要能准确区分：

字符串转义是新手最容易踩的坑。STEP字符串里的单引号用两个连续单引号表示，比如'O''Brien'实际内容是O'Brien。除了单引号，还有\X2\开头的Unicode转义序列，常见于非ASCII字符的文件。第一版解析器可以只处理''转义，Unicode转义留作扩展，但切分逻辑必须意识到字符串内部的分号和括号不会被当作语法符号。

2.3 常见实体类型与参数形态速查表

C#解析器不需要预先知道所有实体类型，因为实体解析是通用的：无论什么类型，参数列表的结构都一样。但为了提取有意义的信息，需要针对常用实体做模型映射。下面这些实体在机械零件和装配体文件里出现频率最高，API设计时可以优先覆盖。

有了这个表，第4章的B-Rep提取就顺理成章。但先别急着做模型映射，基础解析器要先解决三个问题：记录怎么切、参数怎么拆、引用怎么解。这三个问题处理干净，所有实体类型都能被通用解析，模型映射只是第二步。

3. 基于C#的STEP解析核心：记录切分、参数树与引用解析

解析器的主体是三个步骤，对应三个独立类。切分器把整个文件文本变成实体记录列表；参数解析器把每一条记录的括号内容变成参数树；引用解析器在全部实体建立索引后再把编号替换成对象引用。三步分开的好处是每一步都能单独测试，出了问题可以精确定位。

3.1 记录切分：字符串状态机切分实体记录

记录切分是解析器的第一道工序。输入是整个文件的文本，输出是List<string>，每个元素是一条完整的实体记录。不能直接用Split(';')，因为字符串内部可以合法地包含分号。正确做法是维护一个inString标志和一个括号深度计数器，逐字符扫描。

public static List<string> SplitRecords(string content) { var records = new List<string>(); var sb = new StringBuilder(); bool inString = false; int parenDepth = 0; for (int i = 0; i < content.Length; i++) { char c = content[i]; // 字符串状态内，只处理单引号转义，其余字符原样保留 if (inString) { if (c == '\'' && i + 1 < content.Length && content[i + 1] == '\'') { sb.Append("''"); i++; // 跳过第二个单引号 } else if (c == '\'') { inString = false; sb.Append(c); } else { sb.Append(c); } continue; } switch (c) { case '\'': inString = true; sb.Append(c); break; case '(': parenDepth++; sb.Append(c); break; case ')': parenDepth--; sb.Append(c); break; case ';' when parenDepth == 0: records.Add(sb.ToString().Trim()); sb.Clear(); break; default: sb.Append(c); break; } } return records; }

inString和parenDepth必须同时跟踪，缺一不可。举个例子，字符串'IT''S OK'内部没有括号，但如果没有inString状态，切分器会把字符串里的分号误认为记录分隔符；反过来，一条B_SPLINE_SURFACE_WITH_KNOTS记录可能跨越十行，括号深度在参数列表内始终大于0，分号只有出现在最深层的列表项里，但记录结束符一定在深度为0的位置。

这段切分逻辑是O(n)扫描，对大文件友好。需要注意的是，STEP标准里存在/* */块注释和--行注释，但几乎所有实际生成的STEP文件都不带注释。为了兼容罕见情况，可以在循环外先做一次注释剥离，用正则把注释替换成空格，再交给切分器。

3.2 参数树解析：递归处理括号与逗号

拿到一条记录，先拆出编号、类型和参数文本。参数文本是第一个=之后、最后一个)之前的全部内容。类型名和参数文本的分离很简单，难点在把参数文本解析成树形结构，因为参数可以是嵌套列表，比如CARTESIAN_POINT('P',(0.,0.,0.))里的坐标就是一个子列表。

public static List<StepParameter> ParseParameters(string text) { var result = new List<StepParameter>(); int i = 0; while (i < text.Length) { if (text[i] == ',') { i++; continue; } var param = ParseOneParameter(text, ref i); result.Add(param); } return result; } private static StepParameter ParseOneParameter(string text, ref int i) { char c = text[i]; if (c == '\'') // 字符串 { int start = i; i++; while (text[i] != '\'' || (text[i] == '\'' && i + 1 < text.Length && text[i + 1] == '\'')) { if (text[i] == '\'' && text[i + 1] == '\'') i += 2; else i++; } i++; return new StepParameter(StepParameterType.String, text.Substring(start, i - start)); } if (c == '(') // 嵌套列表，递归解析 { int depth = 0; int start = i; do { if (text[i] == '(') depth++; if (text[i] == ')') depth--; i++; } while (depth > 0); // 去掉首尾括号后再递归 var inner = text.Substring(start + 1, i - start - 2); return new StepParameter(StepParameterType.List, inner); } // 其余情况：读到逗号或右括号结束 int end = i; while (end < text.Length && text[end] != ',' && text[end] != ')') end++; string token = text.Substring(i, end - i).Trim(); i = end; return ClassifyToken(token); }

递归的终止条件在遇到字符串或普通token时自然发生。嵌套列表的递归不需要额外记录深度以外的信息，因为内层括号的结束位置就是外层列表的子串边界。这里StepParameter是一个统一的参数包装类，内部维护类型和原始文本，值在后续阶段再按需转换。

ClassifyToken 函数处理非字符串、非列表的单值token：以#开头的是引用，以.开头和结尾的是枚举，$是未定义，含.或E的是实数，否则是整数。分类后存原始文本，等引用解析阶段再填充真正对象，避免在参数解析阶段去查实体索引。

3.3 延迟引用解析：实体索引的两遍扫描

STEP实体之间通过编号互相引用，但引用次序没有保证。常见的情况是#10记录引用#200，而#200在后面才出现。因此必须分两遍处理：第一遍切分并建立Dictionary<long, StepEntity>，第二遍再把参数树里的StepParameterType.Reference替换成具体实体引用。

public void ResolveReferences() { foreach (var entity in _entities.Values) { ResolveParameter(entity.Parameters); } } private void ResolveParameter(List<StepParameter> parameters) { foreach (var p in parameters) { if (p.Type == StepParameterType.Reference) { long targetId = long.Parse(p.Token.Substring(1)); if (_entities.TryGetValue(targetId, out var target)) p.Reference = target; else _warnings.Add($"实体 #{p.Id} 引用了不存在的 #{targetId}"); } else if (p.Type == StepParameterType.List) { ResolveParameter(p.Items); // 递归进入嵌套列表 } } }

延迟解析带来的额外好处是可以在解析阶段同时做引用完整性检查。真实世界中，很多STEP文件由不同CAD软件导出，偶尔会出现悬空引用。把这种异常收集成warning列表而不是直接抛异常，能让解析器继续输出部分结果，这对上层应用很友好。

3.4 C#对象模型：从通用字典到具体实体类

通用解析结果是一棵参数树加一个实体字典，足够回答「文件里有哪些实体」这类问题。但要提取面数、边数、实体体积等业务信息，还要做一步映射：把通用的StepEntity转换成具体实体类。常见做法是定义一个抽象基类，然后为高频实体建子类。

public abstract class StepEntityBase { public long Id { get; set; } public string TypeName { get; set; } public List<StepParameter> Parameters { get; set; } } public class CartesianPoint : StepEntityBase { public double X { get; set; } public double Y { get; set; } public double Z { get; set; } } public class AdvancedFace : StepEntityBase { public StepEntityBase Geometry { get; set; } public List<StepEntityBase> Bounds { get; set; } = new(); }

映射逻辑放在工厂方法里，根据TypeName分发到不同转换器。参数位置和含义在不同应用协议下可能略有差异，所以我一般会在转换器里做防御性检查：参数个数不足时不抛异常，而是把对应属性留空并记录warning。这一步的容错能力，直接决定了解析器能否处理那批「CAD导出的、格式不太严格的」STEP文件。

4. 从几何实体到B-Rep拓扑：提取与导出形状数据

解析器最常用的业务场景不是输出实体列表，而是提取B-Rep（边界表示）信息。B-Rep用面、边、点的拓扑关系描述实体形状，一个机械零件在STEP文件里的结构是固定的层级链。顺着这条链提取数据，就能回答「这个零件有多少个面」这类问题。

4.1 B-Rep实体链路：MANIFOLD_SOLID_BREP到ADVANCED_FACE

B-Rep的顶层入口是MANIFOLD_SOLID_BREP，它只引用一个CLOSED_SHELL；CLOSED_SHELL引用一组ADVANCED_FACE；每个ADVANCED_FACE包含一个曲面几何引用和若干边界环。链路如下：

MANIFOLD_SOLID_BREP └─ CLOSED_SHELL └─ ADVANCED_FACE ├─ 曲面几何（平面、圆柱面、B样条面等） └─ FACE_OUTER_BOUND / FACE_BOUND └─ EDGE_LOOP └─ ORIENTED_EDGE └─ EDGE_CURVE └─ VERTEX_POINT

拿到这个链路以后，提取逻辑就变成简单的递归遍历。值得注意的是，ADVANCED_FACE的参数顺序在不同AP协议里一致，但个别文件会出现B_SPLINE_SURFACE_WITH_KNOTS这种参数极长的曲面实体，控制点列表可能是多层嵌套。遍历时只要按List类型递归展开即可，不需要关心具体几何含义。

4.2 提取面、边、点：一个可扩展的BRepExtractor

提取器按类型名过滤实体，再顺着引用链计数。以下代码统计实体和面数，并输出所有顶点坐标：

public class BRepExtractor { private readonly Dictionary<long, StepEntityBase> _entities; public BRepExtractor(Dictionary<long, StepEntityBase> entities) { _entities = entities; } public BRepSummary ExtractAll() { var summary = new BRepSummary(); foreach (var e in _entities.Values) { switch (e.TypeName) { case "MANIFOLD_SOLID_BREP": summary.SolidCount++; TraverseShell(e); break; case "VERTEX_POINT": summary.VertexCount++; break; } } return summary; } private void TraverseShell(StepEntityBase entity) { // 参数[1] 是外壳引用，参数列表从0开始，实体名是参数[0] var shellRef = entity.Parameters[1]; if (shellRef.Reference?.TypeName == "CLOSED_SHELL") { foreach (var faceRef in shellRef.Reference.Parameters[1].Items) { if (faceRef.Reference?.TypeName == "ADVANCED_FACE") _summary.FaceCount++; } } } }

参数下标是提取器最容易出错的地方。ADVANCED_FACE的四个参数分别是名称、边界列表、曲面几何引用、方向标志，但有些文件会省略方向标志。更稳妥的做法是先按参数个数做分支，再按参数类型匹配目标实体；只靠固定下标处理「标准文件」没问题，但面对真实文件时会频繁踩坑。

4.3 序列化导出：JSON输出与格式转换的前置准备

提取出的B-Rep数据最终要交给别的模块使用。JSON是最稳妥的中转格式，C#用System.Text.Json即可。序列化之前，把实体引用收拢成普通数据结构，避免对象图循环引用导致序列化失败。

public class FaceDto { public long Id { get; set; } public string SurfaceType { get; set; } public List<long> BoundLoopIds { get; set; } } var json = JsonSerializer.Serialize(new { solids, faces, vertices }, new JsonSerializerOptions { WriteIndented = true });

行业里常见的「STEP转CATIA」「GLB转STEP」本质上都是先把源格式解析成中性结构，再映射到目标格式的输出器。解析器做到JSON这一步，就已经为这类转换准备好了中间层。后续要做OBJ、STL或DXF导出，只需要新写一个遍历List<FaceDto>的写入器。

5. 大文件与坏文件的处理：健壮性设计和性能取舍

STEP文件的体积跨度极大。教学用例几KB，真实机械装配体动辄几十MB到几百MB。C#解析器在处理大文件和损坏文件时的表现，往往比功能完整性更能影响使用者评价。

5.1 读取策略：ReadAllText与StreamReader的选择

最省事的做法是File.ReadAllText一次性读入内存，然后交给切分器。代价是内存占用量大约为文件体积的2倍，因为string在.NET里以UTF-16存储。50MB以内的文件，这个开销在桌面应用上完全可接受；超过100MB的装配体，一次性读入就可能触发大对象堆频繁回收，出现明显卡顿。

分块读取的写法不算复杂：用StreamReader读行，累积到一个StringBuilder，每遇到一个在字符串外的分号就把累计内容交给切分器。但注意，分块读取必须自己维护inString状态，因为字符串转义可以跨行。第一版实现我建议直接ReadAllText，把分块留到有真实性能需求时再优化。

5.2 容错策略：宁可保留警告也不中断解析

真实世界的STEP文件远没有标准范文干净。我们处理过损坏文件，包括缺分号、括号不配对、字符串引号未闭合等情况。容错设计的原则是：出现局部错误时，跳过坏记录，保留其余数据，并把错误信息记录在ParseWarning列表里。下表是常见异常和对应处理策略：

坏文件解析的目标不是「完全正确」，而是「尽量多地把有用信息捞出来」。文件里10000条记录坏了3条，如果整体返回失败，上层应用什么都做不了；返回997条有效记录加3条warning，上层至少能进行格式预览或数据统计。

5.3 错误定位：从记录序号反查文件行号

warning信息如果只记录「第834条记录有问题」，对使用者的帮助有限。最好能把记录序号换算成文件行号，方便用编辑器直接定位。做法是提前记录每一行的起始偏移，再在报告时二分查找。

private int GetLineNumber(int charOffset, List<int> lineStarts) { int lo = 0, hi = lineStarts.Count - 1; while (lo < hi) { int mid = (lo + hi + 1) / 2; if (lineStarts[mid] <= charOffset) lo = mid; else hi = mid - 1; } return lo + 1; }

切分器在扫描文本时同步记录每个记录起始字符的偏移量，再把偏移量喂给GetLineNumber，就能报告「第N行附近」。这一步对毕设答辩和后续维护都很有价值，省去了一行一行数记录位置的痛苦。

6. 验证解析器的三个实用技巧：最小样例、断言清单与可视化调试

解析器这类代码的验证难点在于输入种类繁多。我惯用的验证路径是三步走：先用最小人工样例验证主流程，再用真实文件做引用完整性检查，最后用一个简单的可视化手段确认结果没有系统性偏差。

6.1 构造最小STEP样例并断言实体关系

手工构造一个只包含一个三角形面片实体的STEP文件，足以覆盖大部分核心路径。

ISO-10303-21; HEADER; FILE_NAME('test.stp','',(''),(''),'','',''); FILE_SCHEMA(('CONFIG_CONTROL_DESIGN')); ENDSEC; DATA; #1=CARTESIAN_POINT('P0',(0.,0.,0.)); #2=CARTESIAN_POINT('P1',(1.,0.,0.)); #3=CARTESIAN_POINT('P2',(0.,1.,0.)); #4=VERTEX_POINT('V0',#1); #5=VERTEX_POINT('V1',#2); #6=VERTEX_POINT('V2',#3); #7=EDGE_CURVE('E0',#4,#5,$); #8=EDGE_CURVE('E1',#5,#6,$); #9=EDGE_CURVE('E2',#6,#4,$); #10=EDGE_LOOP('L',(#7,#8,#9)); #11=FACE_OUTER_BOUND('B',#10,.T.); #12=ADVANCED_FACE('F',(#11),#1,.T.); #13=CLOSED_SHELL('S',(#12)); #14=MANIFOLD_SOLID_BREP('Tri',#13); ENDSEC; END-ISO-10303-21;

验证断言应该覆盖：实体总数等于14；MANIFOLD_SOLID_BREP的壳引用指向#13；EDGE_LOOP的边引用列表有3项；字符串'Tri'被正确解析。运行解析器后，逐个检查这些断言。

6.2 引用完整性检查清单

对真实文件，建议关注以下指标而不是逐条断言：

这些指标可以帮助判断解析器对某个具体文件的「信任程度」。未知实体类型占比超过10%时，输出结果通常不可信，需要扩展实体映射或降级使用通用实体。

6.3 可视化调试与后续扩展方向

调试解析结果最直观的办法是把提取出的面用WPF的StreamGeometry画出来。做法是：解析所有EDGE_LOOP，取每条边的起点和终点坐标，连线显示。如果解析正确，屏幕上会出现一个完整网格；如果链路提取有误，会看到断裂的线或乱序的环。

后续扩展方向取决于目标用途。要给上位机做预览，按OBJ格式导出是成本最低的方案；要做文件统计，在BRepExtractor里增加曲面类型分布即可；要做STEP转CATIA这类格式转换，在当前解析结果之上再写一个目标格式的写入器就行。解析器本身不需要再做大改动，因为STEP文本的复杂性已经在这一层被隔离了。

本文还有配套的精品资源，点击获取