快速上手

第二章：快速上手——五分钟跑通 Hello World

2.1 创建项目

1. 打开 VS 2022，新建项目 → 选择 Windows 窗体应用 (.NET Framework) → 目标框架选 .NET Framework 4.8
2. 项目名称填入 YourId_BeamDemo（将 YourId 替换为你的公司简称或个人 ID），如 Acme_BeamDemo
3. 创建后打开项目属性 → 应用程序 → 输出类型 改为 类库
4. VS 已自动创建 Form1.cs，在解决方案资源管理器中将其重命名为 YourId_BeamForm.cs（将 YourId 替换为你的标识）。这就是组件的参数设置窗口。

   为避免组件冲突，命名空间和窗体名称应包含开发者唯一标识（公司简称、组织名称或个人ID）及组件功能描述，不得使用通用名称（如 Form1、MainForm、Connection 等）

2.2 添加 SDK 引用

在解决方案资源管理器中右键"引用"→"添加引用"→"浏览"，导航到 LoongCAD 安装目录（如 C:\Program Files\loongstc_community\），添加以下文件：

• LoongSDKCore.dll
• LoongCAD.STC.Friendly.dll
• LoongCAD.STC.Friendly.DataType.dll

最终的 .csproj 中引用部分长这样：

<Reference Include="LoongCAD.STC.Friendly">
  <HintPath>C:\Program Files\loongstc_community\LoongCAD.STC.Friendly.dll</HintPath>
</Reference>
<Reference Include="LoongCAD.STC.Friendly.DataType">
  <HintPath>C:\Program Files\loongstc_community\LoongCAD.STC.Friendly.DataType.dll</HintPath>
</Reference>
<Reference Include="LoongSDKCore">
  <HintPath>C:\Program Files\loongstc_community\LoongSDKCore.dll</HintPath>
</Reference>
<Reference Include="System.Windows.Forms" />
<Reference Include="System.Drawing" />

2.3 创建参数设置窗体

在写组件主逻辑之前，先把参数窗口搭好。

第一步：将 LoongCAD 控件导入 VS 工具箱

1. 打开 工具箱（视图 → 工具箱）
2. 在工具箱空白处 右键 → 选择项…
3. 点击 浏览，导航到 LoongCAD 安装目录，选择 LoongCAD.STC.Friendly.dll
4. 确定后，所有 LoongCAD 控件会出现在工具箱中（可右键新建一个选项卡分类存放）

第二步：搭建页面骨架

一个最基础的组件窗体至少需要以下控件：

控件	作用	工具箱中的名称
SaveLoad	保存 / 加载参数配置	SaveLoad
OkApplyModifyGetOnOffCancel	确定 / 应用 / 修改 / 取消 按钮栏	OkApplyModifyGetOnOffCancel
TabControl	标签页容器，分类放置参数	.NET 自带 TabControl

操作步骤：

1. 从工具箱拖一个 SaveLoad 到窗体顶部
2. 从工具箱拖一个 OkApplyModifyGetOnOffCancel 到窗体底部
3. 从工具箱拖一个 .NET 自带 TabControl 到窗体中间（填满剩余空间）
4. 在 TabControl 中添加若干 TabPage（如"螺栓"、"板件"、"焊缝"），之后将属性面板拖入对应标签页

2.4 写一个最简单的自定义组件

我们的目标：用户在场景中点两个位置，生成一根 H 型钢梁。

Step 1：创建参数数据类

新建 BeamData.cs，定义梁的截面和材质：

using LoongCAD.STC.Friendly.Plugins;

namespace Acme_BeamDemo
{
    [AttributeFields]
    public class BeamData
    {
        public string profile  = "HN400*200";  // 截面
        public string material = "Q355B";       // 材质

        public BeamData() { }
    }
}

Step 2：创建组件主类

将 Class1.cs 重命名为 MyFirstBeam.cs：

using LoongCAD.Geometry.Friendly;
using LoongCAD.STC.Friendly.Plugins;
using LoongCAD.STC.Friendly.Scene;
using LoongCAD.STC.Friendly.Scene.UI;
using System.Collections.Generic;

namespace Acme_BeamDemo
{
    [Plugin("Acme_BeamDemo")]
    [PluginUserInterface("Acme_BeamForm")]   // 关联窗体
    [PluginNumber(90001)]
    public class MyFirstBeam : CustomPlugin
    {
        public BeamData data;
        Component comp;
        List<Point> inputPoints;

        public MyFirstBeam(BeamData data) { this.data = data; }

        // 采集用户输入：让用户点两个点
        public override List<InputDefinition> DefineInput()
        {
            try
            {
                var picker = new Picker();
                var pts = picker.PickPoints(
                    Picker.PickPointEnum.PICK_TWO_POINTS, "选择梁的起点和终点");
                if (pts == null || pts.Count < 2)
                    return new List<InputDefinition>();

                var input = new List<InputDefinition>();
                input.Add(new InputDefinition(pts));
                return input;
            }
            catch (UserInterruptException)
            {
                return null;  // 用户按 ESC 取消
            }
        }

        // 主逻辑：创建梁
        public override bool Run(Component componentObject,
            List<InputDefinition> input)
        {
            comp = componentObject;
            if (input == null || input.Count == 0) return false;
            inputPoints = input[0].GetInput() as List<Point>;
            if (inputPoints == null || inputPoints.Count < 2) return false;

            // 直接在世界坐标系下创建梁（无需自定义工作平面）
            Beam beam = new Beam();
            beam.StartPoint = inputPoints[0];
            beam.EndPoint   = inputPoints[1];
            beam.Profile.ProfileString   = data.profile;
            beam.Material.MaterialString = data.material;
            beam.Position.Depth    = Position.DepthEnum.MIDDLE;
            beam.Position.Rotation = Position.RotationEnum.TOP;
            beam.Name = "测试梁";
            beam.PartNumber.Prefix = "GL";
            beam.Label = "MainBeam";        // 对象标签，同一组件内唯一
            beam.Insert();

            return true;
        }
    }
}

💡 这个示例中我们直接在世界坐标系创建梁，因为用户点选的点本身就是世界坐标。更复杂的组件才需要建立参考坐标系激活工作平面。

⚠️ Label 属性： 所有 ModelObject 子类（Beam、ContourPlate、BoltArray、Weld 等）都有一个 Label 属性。每个通过 new 创建的对象都应赋予唯一 Label（如 "MainBeam"、"GussetPlate"），同一组件内不可重复。

Step 3：关联窗体与组件

在 2.1 节创建的 Acme_BeamForm 窗体上，不需要拖任何属性面板——因为 BeamData 里只有两个简单字段（profile 和 material），LoongCAD 会自动生成文本框。

打开 Acme_BeamForm.cs 的代码，确保构造函数的 InitializeComponent() 之后，将 BeamData 传给组件：

public partial class Acme_BeamForm : Form
{
    BeamData data;

    public Acme_BeamForm()
    {
        InitializeComponent();
        data = new BeamData();
        // LoongCAD 框架会自动将 data.public 字段绑定到 UI
    }
}

SaveLoad 和 OkApplyModifyGetOnOffCancel 这两个控件由 LoongCAD 框架自动接管，无需手写事件代码。

2.5 配置调试环境

第一步：设置启动参数

项目属性 → 调试：

设置项	值
启动操作	启动外部程序
外部程序路径	C:\Program Files\loongstc_community\LoongSTC.exe
工作目录	C:\Program Files\loongstc_community\

第二步：创建组件部署目录

LoongCAD 是从模型目录加载组件 DLL 的，不是你项目的 bin\Debug\。

1. 启动 LoongCAD，新建一个空项目（如命名为 MyProject）。LoongCAD 会在 Documents\LoongSTC\Models\MyProject\ 下创建项目目录结构
2. 在资源管理器中进入该目录，在 config\comps\ 下手动新建一个文件夹，命名为你的组件名（如 Acme_BeamDemo）。最终路径为：

C:\Users\<用户名>\Documents\LoongSTC\Models\MyProject\config\comps\Acme_BeamDemo\
                                                    ↑ 项目名        ↑ 你建的文件夹名 (= Plugin 名称)
    └── plugin.dll              ← 编译产出的 DLL（必须叫这个名字）

💡 config\comps\ 下的文件夹名就是组件名，一个文件夹放一个组件 DLL，且 DLL 必须命名为 plugin.dll。配置 .inp 文件放在同级目录。

第三步：配置生成后事件，自动复制 DLL

在 VS 项目属性的 生成事件 中添加"生成后事件命令行"，把上面路径中的 MyProject 和 Acme_BeamDemo 填入：

copy /Y "$(TargetPath)" "%USERPROFILE%\Documents\LoongSTC\Models\MyProject\config\comps\Acme_BeamDemo\plugin.dll"

⚠️ DLL 必须命名为 plugin.dll，LoongCAD 只加载这个名字的文件。

之后每次编译，DLL 都会自动复制到组件目录。

2.6 第一次调试

1. 按 Ctrl+Shift+B 编译，检查 VS 输出窗口确认 DLL 已复制到 config\comps\Acme_BeamDemo\
2. 按 F5 启动调试，VS 自动启动 LoongCAD
3. 打开之前创建的 MyProject 模型
4. 双击运行 → 弹出参数窗口（显示截面 HN400*200、材质 Q355B）
5. 点击 确定，在场景中依次点两个位置
6. 一根 H 型钢梁出现在两个点之间！

🎉 恭喜！你已经跑通了第一个 LoongCAD 组件——而且它能真正在场景中创建构件。