SolidWorks二次开发模板：API对象模型、C#高频操作封装与避坑指南

简介：SolidWorks二次开发模板是一套面向机械设计工程师与C#开发者的SDK扩展入门资源，帮助读者快速掌握通过Visual Studio调用SolidWorks COM接口的方式，实现建模操作、界面定制与自动化流程。包内共99个文件，以34个dll动态库、18个cs源码文件为主，并辅以bmp图标、resx资源、xml配置及pdb调试符号等，整体压缩包约10.24MB，结构上涵盖插件工程、界面窗体与事件处理逻辑，便于对照学习。资源聚焦于C#语言与SolidWorks的交互方式，从引用类型库、获取ISldWorks实例，到实现插件接口、绑定命令事件均有示例，还涉及自定义属性页与数据交换等典型场景，很适合初次尝试SolidWorks二次开发的读者作为工程模板直接修改复用。目前已有726人学习，该模板将分散的API调用梳理为可运行的代码骨架，能显著降低入门门槛，帮助开发者快速搭建属于自己的SolidWorks扩展插件。

1. SolidWorks二次开发模板：为什么你需要的不是API手册，而是一套能跑的骨架

很多人做SolidWorks二次开发，第一件事是翻API帮助文档，然后被几千个接口吓退。我见过不少团队，花了两个月啃完ISldWorks、IModelDoc、IFeature这些接口，写出的代码还是三步一崩溃、两步一卡死。问题不是API学不会，而是没有一个能落地的模板——启动连接怎么建、文档上下文怎么拿、特征怎么遍历、属性怎么写，这些高频操作应该在一开始就封装好。

一套合格的SolidWorks二次开发模板，本质上是把「连接SolidWorks → 打开/创建文档 → 操作特征/参数/属性 → 保存输出 → 断开连接」这条主链路固化下来。它适合三类人：要给SolidWorks做参数化设计插件的机械工程师，要批量处理三维模型的研发效能工程师，以及想把设计数据和PLM/ERP打通的企业IT人员。这篇我把搭建这套模板的完整思路、代码骨架和踩过的坑一次讲清楚，新手能跟着落地，熟手可以直接拿去比对边界条件。

2. 模板的根：先搞懂SolidWorks的API对象模型与宏录制的边界

2.1 对象模型从SldWorks开始：必须记住的五个对象

SolidWorks二次开发的对象模型是一棵倒挂的树，顶层是ISldWorks，代表SolidWorks进程本身；往下依次是IModelDoc（文档基类）、IPartDoc/IAssemblyDoc/IDrawingDoc（三种具体文档）；再往下是IFeature（特征）、IDimension（尺寸）、ICustomPropertyManager（自定义属性）。这五个对象就是模板里的核心成员。

写模板的第一件事不是写功能，而是把这五个对象的获取路径固定成单例方法。我模板里的SwContext类专门干这件事：

using SolidWorks.Interop.sldworks; using SolidWorks.Interop.swconst; public class SwContext { private static ISldWorks _app = null; public static ISldWorks GetApp(bool connectExisting = true) { if (_app != null) return _app; try { // 优先连接已运行的SolidWorks进程 _app = (ISldWorks)Marshal.GetActiveObject("SldWorks.Application"); } catch { // 没有运行中的实例，就创建新的 _app = new SldWorks(); } if (connectExisting) { _app.Visible = true; _app.UserControl = true; // 让用户接管进程控制 } return _app; } public static IModelDoc2 GetActiveDoc() { return (IModelDoc2)_app?.ActiveDoc; } }

逻辑说明：Marshal.GetActiveObject是连接已运行SolidWorks实例的经典做法，新版本也常用Activator.CreateInstance(Type.GetTypeFromProgID("SldWorks.Application"))来创建新实例。UserControl属性要特别注意——设为true表示把进程控制权还给用户，否则插件退出时SolidWorks会被一起关掉，那你就会收获一个对着电脑骂街的同事。

参数说明：connectExisting这个开关是我后期加的。调试时设true可以反复连同一个SolidWorks窗口；部署给最终用户时反而建议设false，让插件自己拉起进程，避免用户在SolidWorks里手动操作时被后台进程干扰。

2.2 宏录制是起点，但绝不能当终点

网上大量教程告诉你用宏录制器，录一段操作再改成VBA，然后翻译成C#。这个路子作为学习API很有效，能快速看到某个操作背后调了哪个方法。比如录制「新建一个零件」，你会看到：

Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Set swApp = Application.SldWorks Set swModel = swApp.NewDocument("C:\ProgramData\SolidWorks\SOLIDWORKS 2022\templates\Part.prtdot", 0, 0#, 0#)

这行代码连模板路径都写死了，这就是宏录制的第一个边界：不同机器SolidWorks安装路径不同，模板路径不同，录出来的代码基本不可移植。第二个边界是宏录制拿不到Selection和Feature的深层对象——你手动在界面上选了面、拉了凸台，录制器只能记下「选中了某个东西」和「执行了FeatureManager.BossExtrude」，至于选中的是哪个几何实体、参数怎么关联，宏里完全不体现。

所以我的态度是：宏录制只用来查API方法名，模板的主链路全部手写。具体做法是——先在SolidWorks里手动执行一遍操作，录制宏看方法名，然后查API帮助里这个方法的参数结构，最后在模板里按自己的封装方式重新实现。这一步慢，但值得。

2.3 模板的分层结构：把API调用与业务逻辑分开

我维护的模板分四层，这个结构经历了两个项目验证，稳定：

核心原则只有一个：业务层不允许出现ISldWorks的直接调用，必须通过上下文层转发。这样做的好处是换SolidWorks主版本时只改上下文层的兼容代码，业务层一行不用动。后面的所有代码，都基于这个分层结构展开。

3. 用C#搭建模板骨架：从空白项目到在SolidWorks里挂上菜单

3.1 环境准备：版本配对是第一步

C#做SolidWorks二次开发不像普通桌面程序，版本兼容是第一道坎。我的经验是SolidWorks 2018及以上版本配合Visual Studio 2019/2022，项目框架选.NET Framework 4.6.1或4.8，不要选.NET Core——官方互操作库对.NET Core的支持不完整，跑起来各种诡异问题。这个配对表直接存到模板仓库的README里：

安装完SolidWorks之后，在Visual Studio里添加项目引用，选择C:\Program Files\SolidWorks Corp\SolidWorks\SolidWorks.Interop.sldworks.dll和SolidWorks.Interop.swconst.dll这两个主要互操作程序集。注意别选成SolidWorks.Interop.swpublished.dll，那是给AddIn插件注册用的，做独立EXE工具的话用不到。

环境配好后先别急着写代码，在Visual Studio里建一个控制台项目，把Platform Target设为x64，然后编译一次。编译通过说明互操作库引用没问题，编译报错大多是Framework版本不对或者两个Interop DLL版本不一致。

3.2 从空白控制台项目到能弹出SolidWorks窗口

第一步先不急着做AddIn，做一个独立的工具型EXE，跑通「启动/连接→操作→退出」这条最简链路。把Program.cs替换成：

private static void Main(string[] args) { ISldWorks app = null; try { app = SwContext.GetApp(connectExisting: true); app.Visible = true; // 打开一个现有的零件测试连接是否正常 int errs = 0, warns = 0; ModelDoc2 doc = app.OpenDoc6(@"D:\temp\demo.SLDPRT", (int)swDocumentTypes_e.swDocPART, (int)swOpenDocOptions_e.swOpenDocOptions_Silent, "", ref errs, ref warns); if (doc == null) { Console.WriteLine($"打开失败，错误码: {errs}"); } else { Console.WriteLine($"成功打开: {doc.GetTitle()}"); } } catch (COMException ex) { Console.WriteLine($"COM异常: {ex.Message}"); } finally { // 注意不能在这里强制释放COM对象 // SolidWorks进程由用户接管，释放app会造成句柄失效 } }

逻辑说明：OpenDoc6是打开文档的主力API，第五个参数errs是输出参数，打开失败时会收到swDocumentError_e枚举对应的错误码。Silent模式打开文档不会弹出SolidWorks的打开对话框，适合批量处理静默操作。GetTitle()拿到的是文档名不含扩展名。

参数说明：openDocOptions有三个常用选项——Silent（静默打开）、ReadOnly（只读）、SaveAsCopy（另存副本）。批量导出场景我用swOpenDocOptions_Silent | swOpenDocOptions_ReadOnly，避免程序跑着的时候用户手滑改坏图纸，也避免SolidWorks弹窗阻塞主流程。

3.3 注册AddIn：让插件出现在SolidWorks工具栏

控制台工具跑通后，第二步就是把模板改造成AddIn插件——它能在SolidWorks启动时自动加载，在工具栏或CommandManager里挂出你自己的按钮组。AddIn的核心是一个继承ISwAddin的类，加上COM注册特性：

using SolidWorks.Interop.swpublished; [ComVisible(true)] [Guid("9C1A5A11-7B4E-4E6F-9A5E-3F2D0B6E1C42")] [ProgId("MyToolkit.AddIn")] public class SwAddIn : ISwAddin { private ISldWorks _app; private int _addinId; private ICommandManager _cmdMgr; public bool ConnectToSW(object ThisSW, int Cookie) { _app = (ISldWorks)ThisSW; _addinId = Cookie; // 注册菜单命令 _cmdMgr = _app.CommandManager; CommandGroup group = _cmdMgr.CreateCommandGroup2( "MyToolkitMenu", "我的工具箱", "我的工具箱", -1, true, "MyToolkit"); group.AddCommandItem("参数化建模", "启动参数化建模面板", -1, "打开参数化面板", "打开参数化面板", "MyToolkit.ParamForm", 0); group.Activate(); return true; } public bool DisconnectFromSW() { Marshal.ReleaseComObject(_cmdMgr); Marshal.ReleaseComObject(_app); return true; } }

逻辑说明：ConnectToSW里最重要的不是画界面，而是拿到Cookie——这个值是SolidWorks给你这个插件实例的唯一ID，注册菜单、处理事件回调时都用它做身份识别。CreateCommandGroup2创建时如果tooltip参数传空，按钮悬停提示就是空的，用户根本不知道这个按钮干嘛的。

参数说明：CreateCommandGroup2第三个参数是菜单在工具菜单里显示的名字，如果写空字符串，菜单不会出现在「工具」下拉里，只能在右键菜单里找。我固定用"主菜单名、子菜单名、工具提示"三段式命名，这样后期按名字查按钮功能时不迷茫。

此时注册表内需要写入COM类信息。Visual Studio里勾选「注册COM互操作」会在编译时自动注册。手动注册用：

"C:\Windows\Microsoft.NET\Framework64\v4.0.30319\regasm.exe" MyToolkit.dll /codebase /tlb:MyToolkit.tlb

逻辑说明：regasm的/codebase参数告诉.NET从程序集所在目录加载，适合开发阶段频繁更新程序集。正式分发时可以做成安装包，把DLL放到固定目录再注册，同时把x86和x64两个注册表路径都覆盖到——很多插件加载失败就是只注册了32位，而SolidWorks主程序是64位。

4. 模板里的高频操作封装：参数化建模与自定义属性的读写

模板骨架搭起来之后，真正让业务跑起来的是两类高频操作——参数化建模（改尺寸、驱动特征）和属性写入（写零件号、材料、供应商）。这两个操作我在模板里各用一个封装类对应。

4.1 参数化建模的核心：通过Feature找到Dimension

SolidWorks里的每个拉伸、切除、圆角都是一个Feature，每个Feature下有尺寸对象IDimension。最稳定的参数化路径是「FeatureManager → 特征树 → 特征下的参数集合 → 按名称定位尺寸」：

public class FeatureParam { private IModelDoc2 _doc; public FeatureParam(IModelDoc2 doc) => _doc = doc; /// <summary> /// 按特征名找特征，对应设计树里的名字 /// </summary> public Feature GetFeatureByName(string featName) { FeatureManager featMgr = _doc.FeatureManager; return (Feature)featMgr.GetFeatureByName(featName); } /// <summary> /// 修改指定特征下的某个尺寸 /// </summary> public bool SetDimension(Feature feat, string dimName, double newValue) { if (feat == null) return false; // 遍历特征下的所有尺寸参数 int paramCount = feat.GetParameterCount(); for (int i = 0; i < paramCount; i++) { Parameter param = feat.GetParameter(i); if (param != null && param.Name == dimName) { // 注意：SolidWorks内部单位是米，这里要换算成毫米 param.SetSystemValue3(newValue / 1000.0, (int)swSetValueInConfiguration_e.swSetValueIn_ThisConfiguration); _doc.EditRebuild3(); return true; } } return false; } }

逻辑说明：GetParameterCount和GetParameter(i)遍历特征参数，param.Name就是你在SolidWorks界面尺寸框里看到的名字，比如"D1@草图1"。SetSystemValue3是带配置选项的设值方法，第三个参数指定写入哪个配置——只改当前配置用ThisConfiguration，要改所有配置用AllConfigurations。

参数说明：单位换算在这里是血泪经验。SolidWorks API内部数字一律用米、弧度，但SolidWorks界面默认显示毫米、度。直接在界面上写100、代码里传100，结果就是模型膨胀1000倍。我模板的UnitHelper类里放了一个MmToM扩展方法，所有尺寸写入都经过这里。

EditRebuild3()是重建模型的方法，有的教程写成EditRebuild，老版本API能用，但新版本已弃用。改完尺寸必须重建，否则几何体不更新，后续的干涉检查、出工程图全用旧数据，导出STEP给供应商更是灾难。

4.2 属性写入：CustomPropertyManager的两种模式

自定义属性是SolidWorks和PLM/ERP打交道的桥梁。一个零件没写属性，下游系统根本认不出来。模板里封装了属性读写，分「指定配置」和「所有配置」两种模式：

public class PropWriter { private IModelDoc2 _doc; public PropWriter(IModelDoc2 doc) => _doc = doc; public void SetProperty(string propName, string propValue, bool allConfigs = false) { CustomPropertyManager propMgr = _doc.Extension.get_CustomPropertyManager( allConfigs ? "" : _doc.GetActiveConfigurationName()); // 先判断属性是否存在 bool found = false; string value = ""; string resolved = ""; propMgr.Get(propName, out found, out value, out resolved); if (found) { int ret = propMgr.Set(propName, propValue); // ret == 1 表示写入成功 } else { int ret = propMgr.Add(propName, propValue); } } }

逻辑说明：get_CustomPropertyManager传入空字符串代表操作整个文档的自定义属性，传配置名则操作指定配置下的属性集。Get方法返回四个值，其中found标志变量告诉你属性是否已存在，决定用Add创建还是用Set覆盖。

参数说明：Get输出参数里那个resolved是最容易踩坑的——如果你写入的属性值是公式表达式（比如="SW-材料"），resolved返回计算后的实际值，而value返回公式本身。批量导出BOM时一定要读resolved，否则下游拿到的全是等号开头的公式，Excel里直接报引用错误。

4.3 批量操作模板化：遍历文件夹处理所有零件

参数化建模和属性写入都不是一次性的。模板里最常见的批量场景是：选中一批零件，统一改材料属性、统一重新生成、统一导出。我保留了一个BatchProcessor骨架：

public class BatchProcessor { public void ProcessFolder(string folder, Action<ModelDoc2> processAction) { string[] files = Directory.GetFiles(folder, "*.SLDPRT"); ISldWorks app = SwContext.GetApp(); foreach (string file in files) { int errs = 0, warns = 0; ModelDoc2 doc = app.OpenDoc6(file, (int)swDocumentTypes_e.swDocPART, (int)swOpenDocOptions_e.swOpenDocOptions_Silent, "", ref errs, ref warns); if (doc == null) { Log.Write("Batch", $"打开失败: {file}, err={errs}"); continue; } try { processAction(doc); doc.Save3((int)swSaveAsOptions_e.swSaveAsOptions_Silent, ref errs, ref warns); } catch (Exception ex) { Log.Write("Batch", $"处理异常: {file}, msg={ex.Message}"); } finally { app.CloseDoc(doc.GetTitle()); Marshal.ReleaseComObject(doc); } } } }

逻辑说明：ProcessFolder是一个高阶函数，接收Action<ModelDoc2>委托，这样业务逻辑（加属性、改尺寸、导STP）通过lambda传进来，批量框架代码不用动。OpenDoc6用的是Silent模式，即使SolidWorks的弹窗状态开着也不会打扰用户。

参数说明：Save3的第一个参数用swSaveAsOptions_Silent表示静默保存，不弹「是否覆盖」对话框。批处理结束必须CloseDoc，否则SolidWorks内存会涨到可怕的程度——我见过一次跑两千个零件不关文档，SolidWorks直接卡死的现象。Marshal.ReleaseComObject在finally里调用，确保COM引用计数归零。这个释放动作不是玄学，是COM资源的硬约束。

5. 模板避坑：版本错误、COM释放与属性层次的五个实战记录

5.1 现象：SolidWorks启动报CEF组件错误，软件直接崩溃

现象：SolidWorks启动时弹英文错误提示，说旧版CEF组件无法用于当前版本的SolidWorks（类似error 1714或error 1772），随后软件界面空白或直接崩溃。

原因：SolidWorks从2019版开始内置CEF（Chromium Embedded Framework）组件用于界面渲染，旧版安装残留的CEF与新版冲突。多发生在「旧版本没卸干净就装了新版」或「同一台机器装了多个SolidWorks版本」。

解决：去控制面板卸载所有带「CEF」字样的组件（如CEF for SolidWorks Applications），然后用Registry Finder这类工具搜索并删除残留的SolidWorks注册表项，再重新安装对应版本的CEF组件。操作前先备份注册表，别删错其他软件的条目。

5.2 现象：AddIn在SolidWorks里加载失败，无任何错误提示

现象：插件在「工具→插件」里能看到，勾选后弹出加载失败，SolidWorks事件查看器里的错误是.NET运行时异常，但抓不到堆栈。

原因：最常见是regasm注册的COM类和你实际输出的DLL架构不匹配。比如SolidWorks是64位，你的项目Platform Target设成了x86，COM类注册到WOW64目录，SolidWorks在正常目录找不到类。

解决：把项目平台目标改成x64，重新编译并注销旧的COM类。我模板里已经把平台目标固定在x64，并在生成事件里自动执行regasm注册，杜绝人工操作带来的路径错位。

5.3 现象：程序运行一段时间后SolidWorks假死，所有API调用挂起

现象：插件跑批量操作，刚开始几小时正常，突然所有操作无响应，任务管理器里SolidWorks的CPU占用为0，但进程不退出。

原因：基本可以断定是COM对象泄漏。SolidWorks的API是COM对象，每次GetFeatureByName、GetParameter返回的对象都要显式释放。只跑几十次不释放没问题，跑几千次之后COM引用计数耗尽或句柄耗尽，服务进程就不响应了。

解决：模板里统一用SafeRelease扩展方法包装，在finally块里释放所有临时对象。另外，把UserControl设回true能让SolidWorks从「被外部控制」状态恢复，但根治还是靠释放对象。这个就是典型的「黑匣子」问题，不看到对象释放代码根本猜不到原因。

5.4 现象：修改尺寸后模型不变，导出结果还是旧尺寸

现象：参数化修改后立即导出STP，导出的模型没有体现新尺寸，重新打开模型却是对的。

原因：修改尺寸后没有触发重建。SetSystemValue3只是写入了参数值，必须调用EditRebuild3或ForceRebuild3让SolidWorks重新计算几何体。而且重建必须在保存和导出之前同步完成，否则导出用的是缓存里的旧几何。

解决：模板在SetDimension方法内部统一在设值后调用_doc.EditRebuild3()，并在BatchProcessor的processAction完成后强制调用一次app.ActiveDoc.ForceRebuild3()做双保险。这样即使业务层忘记重建，批量链路也能兜底。

5.5 现象：写入的属性在模型属性对话框里看不到

现象：用CustomPropertyManager写入属性后，打开「文件→属性」对话框，自定义属性选项卡里没有看到刚写入的属性，但用API读取却能读到。

原因：SolidWorks的自定义属性分「指定配置」和「整个文档」两个层级。如果get_CustomPropertyManager传入的是配置名，写入的是配置特定属性，而UI的默认标签页显示的是文档属性。两边独立存储，经常被误以为写入失败。

解决：模板里默认写配置属性，同时暴露allConfigs=true开关让调用方决定是否同时写文档属性和配置属性。批量申报BOM时两个都写，避免下游系统读取不一致。这里没有「后悔药」，写错了层级只能再读出来重写，所以封装层最好一次把层级问题解决掉。

6. 把模板做成团队基建：版本管理、自动化验证和统一日志

模板不是写完就固定的，它是团队的公共代码，后续所有插件项目都基于它生长。这一章讲三件我反复在新人培训里强调的事。

6.1 版本管理：跟SolidWorks主版本绑定，不跟功能走

我习惯用Git的分支策略管理模板：主分支对应最低支持版本，每个大版本建独立分支切走。模板项目里建一个Compatibility.cs文件，集中声明当前分支支持的SolidWorks版本范围和互操作库版本：

public static class Compatibility { // 当前分支支持的最低/最高版本（RevisionNumber格式） public const string SwMinVersion = "24.0.0.0"; // SolidWorks 2018 public const string SwMaxVersion = "31.0.0.0"; // SolidWorks 2023 public static void CheckVersion(ISldWorks app) { string rev = app.RevisionNumber(); // 如 "30.3.0.0" Version v = new Version(rev); Version min = new Version(SwMinVersion); Version max = new Version(SwMaxVersion); if (v < min || v > max) { throw new NotSupportedException($"当前SolidWorks版本 {rev} 不在模板支持范围内"); } } }

逻辑说明：RevisionNumber()返回的是类似"30.3.0.0"的主版本字符串，SolidWorks 2022对应30、2023对应31，2018对应24。在ConnectToSW开头调用这个检查，能提前拦住用户用一个不在测试范围内的SolidWorks版本跑插件，省得后面出现莫名奇妙的API行为差异。

6.2 自动化验证：用测试零件集跑通冒烟链路

模板每改一次，就要验证「连接→打开→改尺寸→写属性→保存→关闭」整条链路没被改坏。我维护了一个Validate控制台项目，里面放6个测试零件，覆盖三种典型情况：纯拉伸简单件、含配置的钣金件、带设计表的装配体零件。

# 一键冒烟测试 MyToolkit.Validate.exe --folder D:\testparts --reps 100 --checkRebuild true

参数说明：--reps 100是循环次数，用来暴露COM泄漏；--checkRebuild true会在每次改尺寸后读取特征体积，和预期值比对，偏差超过0.1%就判失败。这个冒烟测试在CI的每日定时任务里跑，凌晨3点跑完发邮件报告，早上到公司看到绿色邮件才安心动代码库。别小看这个动作，模板类代码改坏的几率比功能代码高十倍。

6.3 统一日志：所有API调用留痕，出错不用猜

模板内置一个轻量日志类，不接第三方日志框架，就用静态文件写追加：

public static class Log { private static readonly string LogPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "log", "swaddin.log"); public static void Write(string category, string message) { string line = $"{DateTime.Now:yyyy-MM-dd HH:mm:ss.fff} [{category}] {message}"; File.AppendAllText(LogPath, line + Environment.NewLine); } }

异常捕获在SwContext的入口统一做，写日志时带上方法名、文档名、异常类型三层信息。后来排查线上问题，九成靠这个日志就够了，不用让用户装调试环境去复现。我见过太多次「用户说不行，但你这边怎么试都正常」的翻车现场，加日志后才发现是用户机器上的SolidWorks是旧版本，路径体系都不同。日志写清楚版本号和操作步骤，能省掉一整天的扯皮。

这个模板我已经维护了四年，期间换过三家公司的环境，至今每次新项目启动还是从这套骨架开始。最大的教训是：SolidWorks二次开发的核心不是API调用本身，而是把「连接+清理+重建+释放」这条底层链路的稳定性做到位——功能可以越加越多，但骨架不能松。早期我疯狂堆功能，结果每次升级SolidWorks主版本都要重写一半代码；后来老老实实按分层结构重做了一遍，再升级只改上下文层。参数化建模、属性写入、批量处理这些高频动作，谁先用模板固化好，谁后面就少加三个月班。希望帮到你。

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