做设计自动化和参数化建模这一块，SolidWorks 的 API 二次开发迟早会绕不开。你可能会遇到这样的场景：产品系列几百个型号，总不能一个个手动装配；BOM 要按规则自动生成，装配关系每次手工调整，稍微复杂一点就出错；或者要做概念阶段的快速布局，零件还没定型，但结构验证已经等不起了。这些需求堆在一起，最终都会指向同一个方向：用代码直接驱动 SolidWorks，在程序里构建装配体、生成虚拟零件、添加配合关系。这篇内容就是围绕这个目标，把从零搭建 C# .NET API 开发环境、理解 SolidWorks 装配体对象模型、写出第一个能够自动构建装配体和虚拟零件的实用程序的全过程，拆开揉碎了讲清楚。适合刚接触 SolidWorks 二次开发的机械工程师，也适合需要给企业搭设计自动化工具的软件工程师参考，里面涉及到的东西都是实际项目里真正用得到的。
1. 项目背景与整体设计思路
1.1 为什么选择 SolidWorks API 做装配体自动化
在制造业数字化转型的语境下，CAD 二次开发的价值不在于"炫技"，而在于解决重复劳动。以我接触过的几个项目为例，最常见的痛点是标准化产品变型设计：比如一台设备的框架由型材、钣金件、标准件组成，用户只改几个主参数，整套装配结构、每个零件的尺寸、各零部件之间的配合关系都要同步变化。如果全手工操作，一个型号至少耗掉半天时间，而且改错一个尺寸可能导致连锁报错。
SolidWorks API 正好能在这个环节发力。它允许开发者从外部程序创建装配体文档、插入零件、添加配合、驱动尺寸、导出工程图或中立格式，把"建模过程"变成"参数输入 + 程序执行"的模式。尤其对于装配体这一层，API 的覆盖非常完整：从 AssemblyDoc 到 Component2，从 Mate 到配合组，几乎所有你在界面里能做的操作，都有对应的接口可以调用。
选择 C# 和 .NET 作为开发语言，主要考虑三点：一是 C# 对 COM 互操作的支持非常成熟，SolidWorks 的 API 本质是 COM 组件，C# 里加引用后基本上就是强类型调用，编译期就能发现很多参数错误；二是 C# 的语法和工程化生态更适合做完整工具，日志、配置、界面、数据库访问这些周边能力都很顺手；三是团队协作时，C# 代码的可维护性远比 VBA 宏好得多，结构清晰，版本管理也能做起来。对于有一定 .NET 基础的工程师来说，这套组合的学习曲线其实是最平滑的。
1.2 整体架构设计：Add-in 还是独立 EXE 程序
拿到需求后第一个要做的决定是：用 SolidWorks 插件（Add-in）还是独立的 EXE 程序。这个选择直接影响后面的实现方式和工作量。
| 对比项 | Add-in 插件 | 独立 EXE 程序 |
|---|---|---|
| 启动方式 | SolidWorks 启动时加载，随 SolidWorks 生命周期运行 | 单独启动，按需连接 SolidWorks |
| 调试体验 | 需要附加到 SolidWorks 进程，调试过程偶尔会假死 | 可直接运行调试，连接逻辑简单 |
| 界面集成 | 可以挂菜单、任务窗格，深度集成到 SolidWorks 环境 | 通常用 WinForms/WPF 做独立界面 |
| 部署复杂度 | 需要生成注册表、tlb 文件，签名和杀毒软件拦截问题多 | 只需要安装 .NET 运行时和 SolidWorks 环境 |
| 适用场景 | 给设计师日常使用的工具，要求交互体验流畅 | 批处理、参数化生成、数据转换、无人值守任务 |
我的经验是，如果是做车间或设计部门内部使用的参数化建模工具，Add-in 体验更好；但如果是搭建批量生成、数据转换、自动出图这类流程性程序，独立 EXE 更稳。原因很简单：独立程序的运行环境更干净，没有 SolidWorks 界面状态影响，出问题时能快速重启进程。这篇内容分享的核心示例采用独立 EXE 方案，方便初学者测试和理解，你真正做产品时可以把里面的逻辑原封不动搬进 Add-in。
1.3 核心技术点拆解
SolidWorks API 的对象层级是理解整个开发过程的基础。我习惯把它想成"俄罗斯套娃"：最外层是 SldWorks 对象（代表 SolidWorks 应用程序本身），往下一层是 ModelDoc2（代表当前打开的文档，可能是零件、装配体或工程图），再往下是 AssemblyDoc（装配体文档专用接口）、FeatureManager（特征管理器）、SketchManager（草图管理器）等。
构建装配体主要涉及这样几个核心对象：
- SldWorks：连接 SolidWorks、创建文档、读取全局设置。
- ModelDoc2 / ModelDocExtension：通用文档操作，比如保存、重建、选择对象。
- AssemblyDoc：装配体特有的操作，插入组件、添加配合、爆炸视图等。
- Component2：装配体里的一个具体组件，可以是外部零件、子装配体或虚拟零件。
- Mate2：配合对象，定义组件之间的几何约束。
- FeatureManager：创建和管理特征。
- SketchManager：创建和编辑草图。
理解这套对象模型后，整个开发思路就清晰了：连接 SldWorks 应用，创建装配体文档，用 AssemblyDoc 插入或创建组件，用 FeatureManager 和 SketchManager 给虚拟零件添加实体特征，最后用 Mate2 和配合组来约束组件位置。下面每一节都会围绕这条主线展开。
2. 开发环境搭建与"Hello Assembly"
2.1 开发环境准备
开发 SolidWorks 二次开发前，先把环境配齐。我的建议配置如下：
- Windows 10/11 64 位系统。
- SolidWorks 2020 或更新版本（以下代码基于 2022 编写，版本差异我会在问题排查部分说明）。
- Visual Studio 2022 或 2019，安装时勾选".NET 桌面开发"工作负载。
- .NET Framework 4.7.2 或更高版本（SolidWorks 的 PIA 是基于 .NET Framework 的，不要用 .NET Core/.NET 5+ 创建此类项目，否则 COM 互操作会出现很多奇怪问题）。
- SolidWorks API SDK，一般随 SolidWorks 安装包一起安装，确认安装目录下有 api 文件夹和 SolidWorks Interop 库。
检查 SDK 是否完整的简单方法：在本机搜索一下有没有C:\Program Files\Common Files\SolidWorks Shared\目录下的sldworks.dll和swconst.dll。这两个 DLL 就是后续要引用的主互操作程序集，几乎所有的二次开发都离不开它们。
2.2 创建项目并添加 SolidWorks 引用
打开 Visual Studio，新建一个 Windows 窗体应用（.NET Framework）项目，名称可以叫 SolidWorksAssemblyBuilder。项目创建完成后，在解决方案资源管理器里右键"引用"，选择"添加引用"，切到"浏览"选项卡，找到刚才提到的两个 DLL 并添加：
C:\Program Files\Common Files\SolidWorks Shared\sldworks.dll C:\Program Files\Common Files\SolidWorks Shared\swconst.dll添加引用后，在代码文件顶部加上 using 指令：
using SolidWorks.Interop.sldworks; using SolidWorks.Interop.swconst; using System.Runtime.InteropServices;这里解释一下为什么需要这两个引用：sldworks.dll是 SolidWorks API 的主体，包含 SldWorks、ModelDoc2、AssemblyDoc、Component2 等类型定义；swconst.dll是常量库，定义了所有枚举和开关选项，比如文档类型常量、配合类型常量等。少了一个都会导致编译失败。
还有一点需要注意：这两个 DLL 的版本必须和运行的 SolidWorks 版本对应。如果你本机 SolidWorks 是 2022，就引用 2022 的 DLL。引用错误版本的 DLL 在调用某些接口时会遇到"找不到方法"或方法签名不匹配的问题。同一台机器装多个 SolidWorks 版本时，务必确认 Visual Studio 里引用的路径正确。
2.3 连接 SolidWorks COM 会话
写第一行业务代码之前，先解决"程序怎么找到 SolidWorks 并跟它对话"的问题。最常用的方式是通过 COM 的 ProgID：程序先尝试获取正在运行的 SolidWorks 实例，如果获取不到就启动一个新的 SolidWorks 进程。
static SldWorks ConnectToSolidWorks() { SldWorks swApp = null; // 第一步：尝试获取已经打开的 SolidWorks 实例 try { swApp = Marshal.GetActiveObject("SldWorks.Application") as SldWorks; } catch (COMException) { // 没有运行中的实例，进入启动流程 } // 第二步：启动新的 SolidWorks 实例 if (swApp == null) { Type swType = Type.GetTypeFromProgID("SldWorks.Application"); if (swType == null) { throw new Exception("未检测到 SolidWorks 的注册信息，请确认已正确安装 SolidWorks。"); } swApp = (SldWorks)Activator.CreateInstance(swType); swApp.Visible = true; // 显示 SolidWorks 窗口 } if (swApp == null) { throw new Exception("连接 SolidWorks 失败。"); } return swApp; }这段代码背后的原理是：Marshal.GetActiveObject是 COM 标准方法，用于从 ROT（Running Object Table）中检索已经注册为正在运行的 COM 对象。SolidWorks 启动时会把它的 Application 对象注册到 ROT 中，所以外部程序可以找到它。Activator.CreateInstance则相当于在系统里执行了new SldWorks.Application，触发 SolidWorks 的 COM 服务器注册逻辑，从而启动新进程。
调用这个函数后，可以顺手打印一下版本信息，验证连接是否成功：
SldWorks swApp = ConnectToSolidWorks(); string version = swApp.RevisionNumber(); Console.WriteLine($"SolidWorks 已连接，版本: {version}");我第一次跑这段代码时就踩过坑：程序启动后一直报"未将对象引用设置到对象的实例"，后来发现是 Visual Studio 没有用管理员权限运行，导致 COM 激活失败。如果你的程序需要真正操作 SolidWorks 并保存文件，建议开发期间就直接以管理员身份运行 Visual Studio。
3. 核心细节解析：装配体与虚拟零件的实现原理
3.1 SolidWorks 装配体模型的数据结构
在写创建装配体的代码之前，先把 SolidWorks 内存中的数据结构搞清楚，否则后面调用 API 很容易一头雾水。
装配体文档在 SolidWorks 内部是一个树形结构，根节点是装配体文档自身（AssemblyDoc），下一层是各个组件（Component2）。组件可以是外部零件引用，也可以是子装配体，还可以是本节重点说的虚拟零件。每个组件都包含位置信息（变换矩阵）、名称、所属配置、特征列表等数据。组件下面还有面（Face2）、边（Edge）、顶点（Vertex）、特征（Feature）、草图（Sketch）等几何和拓扑信息。
这个树形结构反映到 API 上，就是很典型的"从根往下找"的访问模式。你拿到一个装配体文档后，遍历第一个层级的组件：
object[] components = (object[])((AssemblyDoc)swDoc).GetComponents(false); foreach (object compObj in components) { Component2 comp = (Component2)compObj; string name = comp.Name2; string path = comp.GetPathName(); Console.WriteLine($"组件名称: {name}, 路径: {path}"); }理解这个结构的意义在于：程序化创建装配体时，你要时刻清楚当前操作的对象处于树的哪一层，以及这个对象是否已经被 SolidWorks 加载到内存中。比如一个外部零件的组件如果处于"轻化"状态，某些 API 调用可能返回空引用，这时需要先调用comp.Unload或修改配置选项把组件设为"还原"状态。
3.2 虚拟零件是什么，为什么有用
虚拟零件是 SolidWorks 2015 以后重点强化的一个功能。简单说，它是"存在装配体内部"的零件：没有独立的 .sldprt 文件路径，零件数据以轻量方式存储在装配体文档内部。从用户界面看，它的图标带一个特殊的叠加标记，命名通常是"零件名^装配体名"。
为什么要用虚拟零件？三个原因非常实际：
- 概念设计阶段需要快速搭建方案，零件尺寸还没定、系列化不确定，如果每建一个零件都生成独立文件，目录里很快就是一堆垃圾文件。虚拟零件可以避免这种文件污染。
- 虚拟零件的性能开销更小，特别适合大批量标准件、辅助结构件的临时建模。
- 在装配体环境下直接建模时，虚拟零件可以让"自顶向下"设计变得顺畅：先在装配体里画一个粗结构，边验证边细化，最后再决定哪些零件要保存成独立文件。
当然，虚拟零件也有坑。最大的风险是保存管理：如果在保存装配体时不特意处理虚拟零件，它可能不会被正确保存为外部文件，换台电脑打开装配体就发现零件丢了。所以在程序化创建虚拟零件时，我会非常强调后面第 4.4 节的"保存时机"。
3.3 配合关系的程序化构建原理
装配体自动化的另外一个核心问题是"如何把组件放到正确的位置"。在 SolidWorks 界面里我们通过添加配合来约束组件，比如两个面重合、两个轴同轴、边和面平行等。程序里的做法也是调用配合接口，但需要对配合类型、对齐方向、配合对象有一个清晰理解。
配合（Mate）的本质是一个几何约束关系。API 里通过AssemblyDoc.AddMate5方法创建配合，核心参数包括：配合类型（重合、平行、垂直、同轴、距离等）、对齐方向（同向/反向）、距离或角度值（距离配合和角度配合需要）、以及需要约束的两个几何实体（面、轴、边等）。
在程序里选择几何实体时，我强烈建议不要依赖界面选择，而是用代码精确获取。SolidWorks API 提供了两种方式：一种是通过名称选择，比如SelectByID2("面名", "FACE", ...)，缺点是面名称在不同语言环境下可能不同；另一种是直接遍历组件的GetBodies、GetFaces，按几何特征判断目标面，这种方式更可靠。比如你要让虚拟零件的顶面与装配体前视基准面重合，可以先拿到虚拟零件的 body 和 face，再拿装配体的基准面，然后调用 AddMate5。
4. 实操过程：从零构建装配体与虚拟零件
4.1 创建装配体文档
连接 SolidWorks、设计好思路之后，开始真正的构建流程。第一步先创建装配体文档。SolidWorks 创建新文档依赖模板文件（.asmdot），通常安装时会在 SolidWorks 安装目录下生成默认模板。稳妥的做法是从 SolidWorks 的首选项里读取默认模板路径，而不是硬编码路径。
// 获取默认装配体模板 string assemblyTemplate = swApp.GetUserPreferenceStringValue( (int)swUserPreferenceStringValue_e.swDefaultTemplateAssembly); if (string.IsNullOrEmpty(assemblyTemplate)) { // 手动指定常见路径，注意版本目录 assemblyTemplate = @"C:\ProgramData\SolidWorks\SOLIDWORKS 2022\templates\Assembly.asmdot"; } if (!File.Exists(assemblyTemplate)) { throw new Exception($"装配体模板不存在: {assemblyTemplate}"); }拿到模板路径后，创建装配体文档：
int errorCode = 0; ModelDoc2 swDoc = (ModelDoc2)swApp.NewDocument(assemblyTemplate, 0, 0, 0); if (swDoc == null) { throw new Exception("创建装配体文档失败，错误码: " + errorCode); } AssemblyDoc swAsm = (AssemblyDoc)swDoc; swDoc.SetTitle2("DemoAssembly");这里有个细节：NewDocument的后三个参数在早期版本里表示纸张大小和宽高，在创建装配体时通常传 0 即可。但不同的 SolidWorks 版本对这个方法的签名处理略有差异，如果遇到重载冲突，可以先看下智能提示里的方法定义。
创建文档后建议立即设置一个自定义标题，方便后续识别。也可以顺手关掉装配体的自动重建提示，避免批量操作时性能受影响。
4.2 创建并插入虚拟零件
装配体文档创建完成后，就可以往里面插入虚拟零件了。这里用InsertNewVirtualPart方法：它会在当前装配体内部创建一个新的零件文档，并作为组件插入。调用时传入虚拟零件的初始名称。
string virtualPartName = "MotorMount_01"; Component2 swComp = null; try { swComp = (Component2)swAsm.InsertNewVirtualPart(virtualPartName); } catch (Exception ex) { Console.WriteLine("创建虚拟零件失败: " + ex.Message); return; } if (swComp == null) { throw new Exception("InsertNewVirtualPart 返回空组件，请确认当前文档是装配体且版本支持虚拟零件。"); } // 获取虚拟零件对应的零件文档 ModelDoc2 vPartDoc = (ModelDoc2)swComp.GetModelDoc2();执行完这段代码后，SolidWorks 界面左侧的 FeatureManager 树里就能看到装配体下面出现了一个零件节点，命名类似MotorMount_01^DemoAssembly。这个组件在磁盘上没有独立的 .sldprt 文件，它的几何数据全部存放在装配体文档内部。
这里必须提醒一个很常见的坑：InsertNewVirtualPart只有在当前文档类型是装配体时才有效，如果当前文档是零件或工程图，这个方法会直接返回 null 或抛出异常。所以代码里一定要先判断文档类型。判断方式在后面的问题排查部分会给出。
创建完虚拟零件后，紧接着的一个操作是"进入该零件的编辑状态"。在 SolidWorks 界面里，编辑虚拟零件相当于双击零件节点；在 API 里，需要激活该组件对应的文档视图。最简单的方式是通过swComp.GetModelDoc2()拿到零件文档后，再调用swDoc.ShowNamedView2("*Front", 6)或是直接对文档实例做特征操作。SolidWorks 的文档对象模型允许直接操作未激活的文档，但有些特征命令必须在激活状态下才能正常工作。我通常在创建完虚拟零件后调用一次((ModelDoc2)swApp.ActiveDoc)?.ForceRebuild3(...)这样的重建逻辑，确保状态一致。
4.3 在虚拟零件内部添加实体特征
虚拟零件只是一个空的零件文档，没有几何实体。要让装配体里有实际的零件形状，需要在虚拟零件内部创建草图并拉伸。这也是整个流程中最繁琐、最容易出错的部分。
我以最常见的"拉伸一个长方体底座"为例，展示完整的 API 调用链。首先要确保当前焦点在虚拟零件文档上，然后通过 FeatureManager 和 SketchManager 创建矩形草图并拉伸。
FeatureManager featMgr = vPartDoc.FeatureManager; SketchManager skMgr = vPartDoc.SketchManager; // 在前视基准面上新建草图 bool sketchEdit = skMgr.InsertSketch(true); if (!sketchEdit) { throw new Exception("进入草图编辑失败。"); } // 绘制一个中心在原点、宽100mm、高60mm的矩形 // SolidWorks 默认单位是米，所以这里传入 0.05 表示 50mm bool rectCreated = skMgr.CreateCornerRectangle(-0.05, 0.03, 0, 0.05, -0.03, 0); if (!rectCreated) { throw new Exception("创建矩形草图失败。"); } // 退出草图 skMgr.InsertSketch(true);草图完成后，调用拉伸特征。FeatureExtrusion3 是创建拉伸凸台的常用接口，参数非常多，我这里列出实际常用的几个：
Feature feat = featMgr.FeatureExtrusion3( true, // 单向拉伸 false, // 是否双向拉伸 false, // 是否对称拉伸 0, // 双向拉伸时的距离2 0, // 拔模角度 0.02, // 拉伸深度，单位米，即20mm 0, // 薄壁特征的厚度 false, // 是否薄壁特征 false, // 是否加厚 false, // 是否生成曲面 false, // 是否从草图偏移 false, // 是否反转方向 0, // 偏移距离 0, // 拔模起始点 false, // 是否在终点拔模 false, // 是否在起点拔模 false, // 是否创建圆角 true, // 是否合并结果 true, // 是否使用默认草图 true, // 是否自动选择轮廓 0, // 轮廓选择选项 0, // 特征范围选项 false // 是否生成切除 ); if (feat == null) { throw new Exception("拉伸特征创建失败。"); } // 强制重建零件 vPartDoc.EditRebuild3(out int rebuildErr, out int rebuildWarn); Console.WriteLine("虚拟零件生成完成，重建结果: 错误码 " + rebuildErr + "，警告码 " + rebuildWarn);这段代码里最值得解释的是单位问题。SolidWorks API 里的长度单位默认是米，但很多中国设计师习惯用毫米。如果你的项目想统一用毫米，建议在程序启动时设置单位偏好：
swApp.SetUserPreferenceToggle((int)swUserPreferenceToggle_e.swInputDimValOnCreate, false); swApp.SetUserPreferenceDoubleValue((int)swUserPreferenceDoubleValue_e.swUnitLinear, 0); // 0表示米，2表示毫米不过坦白讲，我在实际项目中很少改全局单位，而是在代码里做一个"毫米转米"的辅助函数，所有传入 API 的数据都经过这个函数转换，这样代码语义更清楚：
static double MM(double mm) => mm / 1000.0; static double ToMM(double meters) => meters * 1000.0;4.4 添加配合关系与约束
虚拟零件创建完、几何特征也有了，接下来要把零件和装配体或其外部参考关联起来。最典型的场景是：让虚拟零件的一个面和装配体的前视基准面重合，或者让虚拟零件的一条边与某个外部零件的轴同轴。
这里我演示一个"面重合"配合：目标是把虚拟零件的顶面与前视基准面约束为重合。
bool sel1 = false; bool sel2 = false; // 选择虚拟零件的顶面：遍历组件实体，找到法向为Z轴正方向的那个面 Body2 vBody = (Body2)swComp.GetBody(); object[] faces = (object[])vBody.GetFaces(); Face2 targetFace = null; foreach (object fObj in faces) { Face2 face = (Face2)fObj; double[] normal = new double[3]; face.GetNormal(out double x, out double y, out double z); // 实际接口为 GetNormal(out double, out double, out double) // 判断是否为顶面：法向接近Y轴正方向（具体坐标系根据实际方位调整） if (z > 0.9) { targetFace = face; break; } } if (targetFace != null) { sel1 = targetFace.Select4(false, null, false, 0); } // 选择装配体的前视基准面 sel2 = swDoc.Extension.SelectByID2("Front Plane", "PLANE", 0, 0, 0, false, 0, null, 0); if (sel1 && sel2) { // 添加重合配合 bool mateOk = swAsm.AddMate5( (int)swMateType_e.swMateCOINCIDENT, (int)swMateAlign_e.swAlignPOSITIVE, false, // flip 0.0, // 距离/角度值 0.0, // 角度 0.0, // 齿轮比 false, // 锁定旋转 null, // 配合参考1，已通过选择指定 null, // 配合参考2 false); // 是否生成配合文件夹外 if (mateOk) { Console.WriteLine("配合添加成功。"); } else { Console.WriteLine("配合添加失败。"); } }实际开发中，识别"哪个面是顶面"远比这个示例复杂，因为面的位置和方向会随着零件的姿态变化。更通用的做法是用面的重心坐标加法向量综合判断，或者根据零件上已有的参考几何（比如基准面、草图点）来定位。这里的重点是理解Select4和AddMate5的关系：SolidWorks API 的很多配合方法不是直接把两个面对象传进去，而是要求先把它们选中，再基于当前选择集创建配合。这是 COM 接口时代的设计惯性，新手很容易在这里绕晕。
4.5 重建、保存与导出
装配体构建完毕后，进入收尾阶段：重建模型、保存虚拟零件、另存为中立格式（如 STEP、STL）。
重建的代码很简单：
bool rebuildResult = swDoc.ForceRebuild3(out int rebuildErr, out int rebuildWarn); Console.WriteLine($"重建状态: {rebuildResult}，错误码: {rebuildErr}，警告码: {rebuildWarn}");重建是必须的。如果不重建，SolidWorks 内部的特征数据可能是"脏"的，后续导出的模型可能缺少最新的几何体。我在实际项目中甚至见过不重建直接导出导致零件变空白的案例。
虚拟零件的保存是很多人忽略的点。前面提到虚拟零件默认只存在于装配体内部，如果你希望它以后能被其他装配体复用，就应该把它另存为外部零件文件。SldWorks 提供了一个保存虚拟零件的方法：
bool saveOk = swAsm.SaveVirtualComponents( true, // 已更改的虚拟零件 true, // 未更改的虚拟零件 true, // 是否应用到子装配体 out object errObject);调用这个方法后，SolidWorks 会弹出保存对话框（如果swAsm有对应的交互设置）。如果想完全静默处理，可以设置 SolidWorks 的提示模式为不弹框，但这种做法有风险：一旦路径设置错误，虚拟零件可能直接被保存到意想不到的位置。更稳妥的做法是先把虚拟零件另存为明确的路径：
string externalPartPath = @"D:\Project\Parts\MotorMount_01.sldprt"; bool extOk = swComp.SaveAsComponent(externalPartPath, 0, 0); // 参数为路径、保留参考、内部错误码不过SaveAsComponent在不同版本的 API 里行为有差异，有些版本只支持通过 SaveAs 对话框交互。所以我的建议是：在开发阶段先弹一次对话框，确认路径正确后再改成静默模式。
最后，如果需要导出 STEP、STL 等交换格式，使用 ModelDoc2 的SaveAs方法：
string stepPath = @"D:\Project\Output\DemoAssembly.step"; int error = 0; int warning = 0; bool exportOk = swDoc.SaveAs(stepPath, 0, 0, null, ref error, ref warning);注意 STEP 导出需要 SolidWorks 安装对应的 translators 组件，某些精简安装版本没有这些组件，导出时会报错。
5. 常见问题与排查技巧实录
5.1 COM 连接失败：明明装了 SolidWorks 却找不到实例
这个现象在刚入门时很常见：程序抛出COMException，或者Marshal.GetActiveObject一直返回 null。通常有三个原因。
- 权限问题：SolidWorks 以管理员身份运行，而开发程序以普通用户运行，COM 激活会失败。反过来也一样。建议开发期间两边都以管理员身份运行。
- 进程被杀：SolidWorks 进程崩溃后，ROT 中的对象可能残留，但已经无法访问。重启 SolidWorks 就好。
- 引用版本不匹配：如果代码里引用了 2022 的 sldworks.dll，但本机运行的是 2020，COM 激活时方法签名对不上，表现为某些方法抛
MissingMethodException或返回 null。
排查的时候，建议在ConnectToSolidWorks函数里加入详细的日志输出，记录异常类型和消息，方便定位。
5.2 NewDocument 返回 null 或模板报错
创建装配体文档失败，90% 的原因是模板路径不对。很多机器上 SolidWorks 的默认模板路径是没有写入注册表的，GetUserPreferenceStringValue返回空字符串。建议做成三级回退：
- 读取用户的默认模板设置。
- 读取 SolidWorks 安装目录下的模板路径（用
swApp.GetExecutablePath()拼接）。 - 手动指定一个绝对路径，并在代码启动时验证
File.Exists。
另外注意，.asmdot 是装配体模板，.prtdot 是零件模板，不要混用。
5.3 InsertNewVirtualPart 返回空组件
InsertNewVirtualPart返回空组件最常见的原因有四个：
- 当前文档不是装配体。可以先判断文档类型：
int docType = swDoc.GetType(); // 2 表示装配体，1 表示零件，3 表示工程图 if (docType != (int)swDocumentTypes_e.swDocASSEMBLY) { throw new Exception("当前文档不是装配体，无法创建虚拟零件。"); }- 装配体处于"已保存并关闭"的只读状态，无法编辑。
- SolidWorks 版本太低，不支持虚拟零件。虚拟零件功能从 2015 版本开始完整支持，低于这个版本请考虑用空零件文件代替。
- 当前正在草图编辑状态或配合编辑状态，SolidWorks 不允许同时插入组件。先退出所有编辑状态再调用。
5.4 拉伸特征失败：FeatureExtrusion3 返回 null
FeatureExtrusion3是参数最多的 API 之一，也是新手最容易踩坑的地方。我的经验是：先跑通最简单的拉伸，再逐步增加复杂参数。如果返回 null，优先检查三件事：
- 当前是否在零件文档环境中。虚拟零件的文档类型是零件，不是装配体。如果还在装配体文档上调用
FeatureExtrusion3，结果是不可预料的。 - 当前是否有可用的草图。拉伸必须基于一个已经存在的草图，并且草图必须处于"未编辑"状态。
- 是否在草图中选择了轮廓。代码里我传了
true给"自动选择轮廓"，但如果草图里有多个闭环，SolidWorks 可能无法判断拉伸哪个轮廓。这时需要明确指定轮廓，或者改为更小的草图区域。
5.5 保存后虚拟零件不翼而飞
这个问题几乎每个用过虚拟零件的人都会遇到。原因是虚拟零件的数据默认只存在于装配体内部，如果你只保存了装配体文件而没有执行"保存虚拟零件"，那么关闭 SolidWorks 后虚拟零件的几何数据可能丢失。SolidWorks 界面在关闭装配体时会弹窗提醒"是否保存虚拟零件"，但程序化操作时很容易忽略这一步。
解决方法是形成固定的保存流程：在程序结束前，先保存所有虚拟零件到指定目录，再保存装配体本身。代码顺序不能反，因为装配体保存时会记录外部虚拟零件的路径引用。
5.6 尺寸单位混乱：看起来是 1mm，实际却是 1m
SolidWorks API 的单位默认是米，但很多模具、非标设备工程师的习惯是毫米。我发现一个比较稳妥的做法是：程序开头做一个单位检查，并定义一个全局单位转换器，保证所有进出 API 的数据都经过转换。
class LengthConverter { private double _factor = 1.0; public LengthConverter(bool useMillimeter) { if (useMillimeter) _factor = 1000.0; } public double ToMeters(double value) => value / 1000.0; public double FromMeters(double value) => value * 1000.0; }在代码里凡是写入 API 的尺寸统一走ToMeters，读出来的数据统一走FromMeters。不要在图省事的地方偷懒，混用单位导致的模型尺寸错误，往往要花几小时才能发现。
5.7 性能优化：大批量装配时的卡顿问题
如果你需要在一个装配体里插入几十甚至上百个虚拟零件，逐个调用InsertNewVirtualPart和FeatureExtrusion3会非常卡，因为每个特征默认都会触发界面刷新和重建。我实际测过，插入 50 个零件、每个零件 2 到 3 个特征，默认配置下可能要跑十几分钟。
性能优化有几个关键开关：
- 关闭屏幕刷新：
swApp.GetUserPreferenceToggle设置刷新模式，或者在文档级别调用swDoc.SetAddToDB(true)让特征加入数据库时不立刻重建。 - 抑制草图自动标注：
swApp.SetUserPreferenceToggle((int)swUserPreferenceToggle_e.swInputDimValOnCreate, false)，避免每次画完草图都弹出尺寸输入框。 - 最后统一重建：所有特征创建完以后再调用一次
ForceRebuild3，而不是每加一个特征就重建一次。
还有一个不那么明显但很实用的技巧：尽量使用FeatureManager.SetAddToDB(true)配合SetAddToDB2等方法，让特征只进入模型数据库而不立即执行几何计算。大批量建模时，这个开关能把耗时从分钟级降到秒级。
6. 从代码到工程化：一些想特别强调的事
如果你只是自己研究着玩，看到上一节就可以动手了。但如果是给公司搭工具，我建议再往下看两点经验。
第一，日志怎么做。SolidWorks 二次开发的调试体验非常差，很多 API 调用不抛异常，只是返回 null 或者 false。你在代码里必须做详细的日志记录：进入哪个方法、传入了什么参数、返回值是什么、模型当前处于什么状态。日志既能帮你排查问题，也能在使用者报告"程序跑失败了但不知为啥"的时候快速定位。我通常用一个简单的LogHelper类，把日志同时输出到控制台和文件，文件命名带上时间戳。
第二，如何设计参数化入口。程序化创建装配体这个能力本身只是基础，真正的价值在于把它封装成"输入参数、输出模型"的工具。比如把装配体的长度、宽度、高度、孔位、零件数量做成一个 XML 或 JSON 配置，程序读取配置后自动生成装配体。这样即使不写代码的工程师也能通过改配置文件来驱动建模，整个工具的使用面就宽了。
我在实际项目中经常遇到一个现象：明明 API 调用都成功了，但生成的模型在 SolidWorks 里打开时，某些配合状态显示为"过定义"或"错误"。这通常是配合添加顺序或参考对象选择不当导致的。建议在程序里每添加一个配合就检查一下配合的状态，如果有错误立刻停止并输出这条配合的名称和参考对象，不要等所有配合加完了再回头找问题。通过遍历FeatureManager.GetFeatures找到类型为配合的特征，检查其GetErrorCode2方法，可以在早期发现配合冲突。
最后再分享一个我个人的习惯：无论在哪个项目里，我都保留一个"手工基准案例"。也就是说，先用鼠标在 SolidWorks 界面里把整个装配体流程从头到尾操作一遍，记录每一步涉及到的操作菜单和选项值，然后才去写代码。这个习惯帮我绕开了大量 API 文档描述不清晰的坑，因为 SolidWorks 的界面选项往往比 API 枚举值更直观，对照着写代码，出错的概率会小很多。
虚拟零件和装配体自动化这一块功能，玩熟了以后可以扩展的方向非常多：批量出 BOM、自动装配标准件、参数化生成整机模型、对接 PLM 系统等等。核心还是先把"程序化构建装配体 + 虚拟零件"这条链路跑通，后面的路就容易走了。
