使用 SOLIDWORKS PDM Professional API 创建 Add-in Hook（C#）

在工程设计和产品数据管理（PDM）中，自动化和定制化功能能够显著提升工作效率。SOLIDWORKS PDM Professional 提供了强大的 API，使开发者能够根据具体需求创建自定义的 Add-in。本篇博客将详细介绍如何使用 C# 编写一个 Add-in，通过注册 Hook 实现对文件添加、签出和签入事件的监听与处理。

前言
SOLIDWORKS PDM Professional 是一款功能强大的产品数据管理工具，广泛应用于工程设计领域。通过其 API，开发者可以扩展其功能，实现自动化操作、定制化工作流程等。本篇博客将指导您如何创建一个 Add-in，当文件被添加、签出或签入到仓库时，SOLIDWORKS PDM Professional 将通知您的 Add-in。

注意：由于 SOLIDWORKS PDM Professional 无法强制重新加载基于 .NET 的 Add-in，因此所有客户端机器在更新 Add-in 后必须重新启动，以确保使用的是最新版本的 Add-in。

创建基础 Add-in
在开始之前，建议您参考创建菜单命令（C#）以创建一个基本的 Add-in。这将为后续的 Hook 注册打下基础。

实现 GetAddInInfo 方法
IEdmAddIn5::GetAddInInfo 方法用于提供 Add-in 的基本信息，并注册需要监听的事件。在此方法中，我们将调用 IEdmCmdMgr5::AddHook 方法，为每个需要监听的事件注册 Hook。

代码示例

public void GetAddInInfo(ref EdmAddInInfo poInfo, IEdmVault5 poVault, IEdmCmdMgr5 poCmdMgr)
{
    // 在 Add-in 的属性对话框中显示的信息
    poInfo.mbsAddInName = "My first add-in";
    poInfo.mbsCompany = "The name of my company";
    poInfo.mbsDescription = "This is a very nice add-in.";
    poInfo.mlAddInVersion = 1;

    // 指定 SOLIDWORKS PDM Professional 的最低版本要求
    poInfo.mlRequiredVersionMajor = 5;
    poInfo.mlRequiredVersionMinor = 2;

    // 注册 Hook

    // 当文件被添加时通知 Add-in
    poCmdMgr.AddHook(EdmCmdType.EdmCmd_PostAdd);

    // 当文件被签出时通知 Add-in
    poCmdMgr.AddHook(EdmCmdType.EdmCmd_PostLock);

    // 当文件即将被签入时通知 Add-in
    poCmdMgr.AddHook(EdmCmdType.EdmCmd_PreUnlock);

    // 当文件被签入时通知 Add-in
    poCmdMgr.AddHook(EdmCmdType.EdmCmd_PostUnlock);
}

说明
AddHook 方法：用于注册特定的事件类型。上述代码中，我们注册了四种事件类型：文件添加（EdmCmd_PostAdd）、文件签出（EdmCmd_PostLock）、文件即将签入（EdmCmd_PreUnlock）和文件签入（EdmCmd_PostUnlock）。
Add-in 信息：通过 poInfo 对象，您可以设置 Add-in 的名称、公司、描述及版本信息。
实现 OnCmd 方法
IEdmAddIn5::OnCmd 方法在注册的事件触发时被调用。在此方法中，您可以根据不同的事件类型执行相应的操作。

代码示例

public void OnCmd(ref EdmCmd poCmd, ref Array ppoData)
{
    // 处理 Hook
    string name = null;
    switch (poCmd.meCmdType)
    {
        case EdmCmdType.EdmCmd_PostAdd:
            name = "PostAdd";
            break;
        case EdmCmdType.EdmCmd_PostLock:
            name = "PostLock";
            break;
        case EdmCmdType.EdmCmd_PreUnlock:
            name = "PreUnlock";
            break;
        case EdmCmdType.EdmCmd_PostUnlock:
            name = "PostUnlock";
            break;
        default:
            name = "?";
            break;
    }

    // 检查数组的上下界
    string message = "";
    int index = Information.LBound(ppoData);
    int last = Information.UBound(ppoData);

    // 将所有受影响文件的路径添加到消息字符串中
    while (index <= last)
    {
        message += ((EdmCmdData)(ppoData.GetValue(index))).mbsStrData1 + Constants.vbLf;
        index += 1;
    }

    // 向用户显示消息
    message = "The following files were affected by a " + name + " hook:" + Constants.vbLf + message;

    EdmVault5 vault = default(EdmVault5);
    vault = (EdmVault5)poCmd.mpoVault;
    vault.MsgBox(poCmd.mlParentWnd, message);
}

说明
事件类型判断：通过 poCmd.meCmdType 判断触发的事件类型，并相应设置 name 变量。
处理受影响的文件：ppoData 数组包含了受事件影响的文件信息。通过遍历该数组，将所有文件路径拼接到 message 字符串中。
消息显示：使用 vault.MsgBox 方法向用户显示受影响的文件列表及触发的事件类型。
构建和安装 Add-in
完成代码编写后，按照以下步骤构建和安装 Add-in：

构建 Add-in
在 Visual Studio 中，点击 Build > Build Solution 来构建 Add-in。
安装 Add-in
打开 SOLIDWORKS PDM Professional 管理工具。
展开要安装 Add-in 的仓库，并以管理员身份登录。
右键点击“Add-ins”，选择 New Add-in。
浏览至项目的构建输出目录（例如 project_path\project_name\project_name\bin\Debug），选择 project_name.dll 和 Interop.EdmLib.dll，然后点击 Open。
点击 OK 以完成安装。
测试 Add-in
在仓库中添加、签出或签入一个或多个文件。
应会弹出消息框，显示被添加、签出或签入的文件列表。
注意：如果文件未被修改，签入操作不会触发 OnCmd 方法，因为 SOLIDWORKS PDM Professional 会触发“撤销签出”事件。在这种情况下，您需要在 GetAddInInfo 方法中注册 EdmCmd_PreUndoLock 和 EdmCmd_PostUndoLock Hook，以处理“撤销签出”事件。

注意事项
Add-in 版本更新：由于 SOLIDWORKS PDM Professional 无法强制重新加载基于 .NET 的 Add-in，当您更新 Add-in 后，必须重新启动所有客户端机器，以确保使用的是最新版本的 Add-in。
事件处理：确保在 OnCmd 方法中处理所有注册的事件类型，以避免遗漏重要的文件操作事件。
错误处理：在实际开发中，建议在 OnCmd 方法中添加错误处理机制，以应对可能的异常情况。
结语
通过本文的指导，您已经了解了如何使用 SOLIDWORKS PDM Professional 的 API 创建一个 Add-in，并通过注册 Hook 监听文件的添加、签出和签入事件。这为进一步的自动化和定制化功能开发奠定了基础。根据具体需求，您可以在此基础上扩展更多功能，提升工作流程的效率和智能化水平。

如果您在开发过程中遇到任何问题，建议参考 SOLIDWORKS PDM Professional API 文档 或加入相关开发者社区，寻求更多帮助和支持。