主要步骤使用 Visual Studio 创建 .NET Framework 4.7.2 的类库项目 项目中添加对 ProjectPenguin.dll 以及 NSGeo3dm.dll 的引用 创建自定义类，并声明继承自 ProcessorCardBase，然后实现相关的抽象函数，以及一个 无参数构造函数 复制编译结果至Y-GAMA的 自定义卡片文件夹 内
步骤详解接下来的内容是对上述四个步骤的详解，并且标明了一些需要特别注意的细节。 【1 - 使用 Visual Studio 创建 .NET Framework 4.7.2 的类库项目】首先需要在安装Visual Studio时，需要选择 .NET 桌面开发 (.NET desktop development)。并注意在右侧需要有 .NETFramework4.7.2targeting pack： 
若右侧没有 .NETFramework4.7.2targeting pack 选项出现，则需要选择上方的 “单个组件”标签页，勾选它： 
若您已经安装过 Visual Studio，则可以通过启动 Visual Studio Installer （一般可以从开始菜单内搜索找到）来启动上述所示的画面，并确认上述组件是否有安装： 
在确认Visual Studio环境确认完毕之后，就可以开始建立项目了。打开Visual Studio之后，选择新建项目。 
选择 类库 (.NET Framework)，不要选择仅有“类库”二字的选项。 
点击下一步后，在随后的选项中可以任意输入自己喜欢的名字、项目存放的磁盘位置。然后在框架中需要选择的是 .NETFramework4.7.2 或更低的版本。 
您当前的Visual Studio版本可能与这里展示的版本选项略有出入，这是正常的，也不会影响到后续的正常卡片构建，只需要确保目标库的版本是 .NETFramework4.7.2 或更低的版本即可。 此时，我们的第一步就完成了。 最后，重新列出在该步骤中需要特别注意的点： 特别注意：
【2 - 添加对 ProjectPenguin.dll 以及 NSGeo3dm.dll 的引用】项目建立完毕之后，我们就可以开始着手准备为 Y-GAMA 编写代码了。但是，在编写代码之前，我们需要添加对 Y-GAMA 的运行必要的 DLL类库 添加引用，这样，我们编写、编译出来的类库文件才可以被 Y-GAMA 识别并加载运行。 我们需要引用的 DLL类库 一般来说有2个： 下面我们就来为我们刚刚建立的项目添加这两个 DLL类库 的引用。 首先在Visual Studio的 “解决方案资源管理器” 中找到引用，并在上面单击鼠标右键，选择“添加引用…”： 
此时，在弹出的窗口中，选择“浏览”，并在Y-GAMA的安装目录下找到对应的 ProjectPenguin.dll 以及 NSGeo3dm.dll 文件，依次添加。 
确认添加之后，我们就可以在 “解决方案资源管理器” 的 “引用” 下面看到我们刚刚添加的两个 DLL类库 的引用了。 
此时，我们还需要一步操作，那就是对它们的属性进行设置：在 “解决方案资源管理器” 中，同时选择刚刚添加的 ProjectPenguin.dll 以及 NSGeo3dm.dll 引用之后，在其中任意一个引用上点击右键，选择属性。
此时在“属性”页面中，将“复制本地”（Copy Local）选项设置为 “否”（false）。
做完上述步骤后，就可以开始代码逻辑的编写了。 特别注意：
【3 - 创建第一个自定义卡片类】所有在 Y-GAMA 绘图区域所看到的内容都是 卡片，而大部分我们在创建参数化工作流时用到的卡片都是继承自 ProcessorCardBase 的一类 “数据处理卡片”。我们在这里就以制作一个输出“Hello, World”的卡片为例，学习如何制作自己的 数据处理卡片 。 我们在该步骤的目标是：编写一个继承自 ProcessorCardBase的类。在Visual Studio为我们创建项目时，其实就已经准备好了一个类的模板，以及其对应的文件。为了方便起见，我们就不再向该项目中添加其他的文件了，直接在默认的这个类中进行操作。 我们需要声明该类继承自 ProcessorCardBase （using ProjectPenguin.Cards）： using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using ProjectPenguin.Cards;
namespace ClassLibrary1
{
public class Class1 : ProcessorCardBase
{
}
} 此时， Class1名字下应该会出现红色波浪线，我们如果把鼠标悬停在波浪线处，则会弹出提示信息。提示信息为未实现抽象方法xxx。 我们找到提示框最下方处的“显示可能的修补程序”，鼠标左键单击它，选择“实现抽象类”
选择完成后，Visual Studio就会为我们生成许多代码了，但每个函数中都是一句 thrownewNotImplementedException(); 这些内容都是我们接下来要进行替换的。
自定义卡片类的无参数构造函数声明 在我们替换它们之前，让我们先来为我们的数据处理卡片起个名字。卡片命名是通过 无参数构造函数 来实现的。在此处，我们的类名字叫做 Class1，因此我们的 无参数构造函数 写为： public Class1() : base('基本名称', '缩写', '描述信息', '大类', '子类')
{
}
自定义卡片类的抽象函数实现接下来，我们需要将四个 thrownewNotImplementedException();进行替换，来真正地实现自定义卡片的运行。这四个抽象函数分别对应的作用是： CardGuid: 一个全局唯一的标识号，用来唯一地确定“卡片类别”，可以认为是“身份证”一样的存在。【切勿手工编造输入，后文会介绍生成方法】 Build: 卡片运行的主逻辑 AddInputSideDataCards: 卡片的输入端口声明（卡片左端接口声明） AddOutputSideDataCards: 卡片的输出端口声明（卡片右端接口声明）
实现 CardGuid 属性的 get方法：我们需要使用 Visual Studio 自带的 Guid生成器 来获得一个全新的随机的 Guid。在菜单栏的“工具”菜单下，点击“创建GUID”。
然后在弹出来的创建GUID小工具中，选择“注册表格式”，并点击“复制”。此时，生成的Guid文本就已经被复制到您的剪切板上了。
随后，我们将 CardGuid=>thrownewNotImplementedException()替换为 Guid.Parse方法（下面所示的代码仅为示例，您所生成的Guid将会有所不同，这是正常的现象；请确保每次新建类的时候，都有不一样的Guid，以保证 Y-GAMA 能够为每个不同的卡片来分配唯一标识）： public override Guid CardGuid => Guid.Parse('{95FAD3CB-B4DC-4E3A-9D94-F7266F2CA0DB}'); 实现 AddInputSideDataCards 以及 AddOutputSideDataCards正如其函数名称所代表的， AddInputSideDataCards 里的代码是用来实现添加卡片的入口端，而 AddOutputSideDataCards 里的代码是用来实现添加卡片的出口端。 我们目前只想要实现输出一个 “Hello, world” 字符串，所以我们无需对 AddInputSideDataCards 里填写任何代码，仅需对 AddOutputSideDataCards 中添加一个 字符串 类型的出口即可： protected override void AddInputSideDataCards(IDataCardEmbedmentHelper helper)
{
}
protected override void AddOutputSideDataCards(IDataCardEmbedmentHelper helper)
{
helper.AddWellKnownTypeOfDataCard(
typeof(string), // 出口的数据类型
'卡片出口', // 出口全名，将会在鼠标悬停时显示
'出口', // 出口简称，将会直接显示在卡片上
'卡片出口的描述性文字…', // 出口描述信息，将会在鼠标悬停时候显示
ProjectPenguin.Cards.Enums.DataProcessingMode.OneByOne); // 出口的数据处理模式
} 实现 Build 方法Build方法是 数据处理卡片 的核心，它会负责从卡片入口中收集数据、处理数据、以及将处理完成的数据设置到卡片出口中。在我们的这个简单案例中，仅需要对出口的数据设置为'Hello, world'这个字符串即可：
public override void Build(IDataDelivery idd)
{
idd.SetDataItem(
0, // 出口的编号，从0开始。我们仅有一个出口，因此为0
// 若有多个出口则按照添加顺序依次排列
'Hello, world!' // 需要输出的数据结果
);
} 到此为止，我们的代码部分就已经完成了，完成后的我们Visual Studio大致应该是这样的： 特别注意：
【4 - 复制编译结果至Y-GAMA的“自定义卡片文件夹”之中】上面内容完整做完之后，我们就可以开始编写结果后处理事件，让Visual Studio每次都自动复制编译好的类库文件至 Y-GAMA 的自定义卡片文件夹了。 Y-GAMA 的自定义卡片文件夹可以直接在下列目录找到： C:\Users\<<您的电脑登录用户名称>>\AppData\Roaming\yjkSoft\Penguin\Cards
也可以通过在 Y-GAMA 中点击“文件”菜单，选择“打开自定义卡片文件夹”。
特别提醒：自定义卡片文件夹内的卡片将会在下一次 Y-GAMA 启动的时候读取，若您在复制自定义卡片类库时， Y-GAMA 仍处在运行状态，则需要将 Y-GAMA 以及 盈建科计算软件 在内的软件整体关闭，再次打开，才能加载新的自定义卡片。
找到自定义卡片文件夹路径后，则可以回到 Visual Studio 中，在“解决方案资源管理器”中找到我们的类库项目 “ClassLibrary1”，在上面点击右键，选择“属性”：
在左侧选择“生成事件”标签，在“生成后事件命令行”中依据您的自定义卡片文件夹来填入下面的内容：
Copy '$(TargetPath)' 'C:\Users\<<您的电脑登录用户名称>>\AppData\Roaming\yjkSoft\Penguin\Cards\$(TargetName).crd'
特别提醒：
设置生成后事件命令行之后，就可以启动编译了。
如果一切都没问题，编译成功之后，我们就可以在我们的自定义卡片文件夹里找到刚刚编译成功的卡片类库了：
此时启动 Y-GAMA （如果您之前有正在运行的 Y-GAMA，请将 Y-GAMA 及其关联的 盈建科结构设计软件 一起关闭之后，再次启动）
Hello, world! 总结本文简单地介绍了一下如何基于 Y-GAMA 当前版本 （v0.6.11）来制作自定义卡片。 自定义卡片其实是一个 .NETFramework的类库，在 Y-GAMA 启动时将会被加载，并且读取其中的自定义卡片类，并在使用时将其实例化。自定义卡片的名字及其所属分类由卡片类的 无参数构造函数 确定，自定义卡片的出入口由其实现的抽象函数 AddInputSideDataCards 以及 AddOutputSideDataCards 来确定，自定义卡片的主要工作逻辑由其实现的抽象函数 Build 来确定。 编译完成的类库文件复制到自定义卡片文件夹、并将后缀名改为“.crd”后即可被 Y-GAMA 识别并加载。该复制操作可以通过 Visual Studio 的编译后处理事件命令行来自动完成。
加入QQ群，我们一起来探索YJK-GAMA的 无限可能！ 接下来我们还会给您带来更多的惊喜，关注我们公众号吧！ 非解构数字科技 新科技 新设计 新建造 2篇原创内容 公众号 非解构 建筑与结构语汇的非常解释 358篇原创内容 公众号 有任何问题，您也可以直接联系我们“大菲儿”。
|
