Bentley二次开发教程03-第一个插件HelloWorld

最新推荐文章于 2024-05-22 19:21:18 发布

不见不散com

最新推荐文章于 2024-05-22 19:21:18 发布

阅读量1k

点赞数 29

文章标签： c# 学习开发语言制造

本文链接：https://blog.csdn.net/weixin_43602823/article/details/137817511

版权

4 Addins 程序编写

要使一个.NET 程序集能够作为 Addins 在 MicroStation 下加载运行，需要首先建立
Addins 框架，在框架下结合功能需求建立目标程序，关于建立框架的细节本章将介绍两

种方法。第一种创建方式为一步一步建立 Addins 框架，在此过程中将一步一步建立起
Addins 的整个框架；第二种方法介绍了如何通过 SDK 中的案例快速转换成可使用的
Addins 程序框架。另外，我还为您提供了一套 Addins 程序框架模板，您可以学习一下如何使用该模板快速创建 Addins 程序，它最大的优势为跳过 Addins 程序框架的建立，方便您直接编写业务功能。最后，若想进一步学习二次开发的相关知识，您可以使用 SDK 进
行学习和实践，这里我也会对如何使用帮助文档、案例及调试进行介绍。

4.1 一步一步建立 Addins 框架

4.1.1 创建工程

在这里插入图片描述

图 29 点击新建工程
选择类库（Class Library），若需要修改工程建立位置则点击浏览，最后确定.NET
Framework 的版本为 4.6.2，确认无误后点击确定生成解决方案。需要注意的是，目前
MicroStationU16 版本基于.NET 4.6.2，后续随着版本迭代可能会升级到更高版本，而
U16.1 版本推荐您使用 VisualStudio2019 进行插件的开发。启动 VisualStudio 请注意使用
管理员权限打开。

在这里插入图片描述

图 30 创建工程菜单
在这里插入图片描述

图 31 程序编写界面
点击确认按钮后会出现所下图所示界面，左侧为自动生成的 C#代码，右侧为解决方案
浏览器窗体，我们在菜单键上右键工程，打开项目属性窗体。

4.1.2 修改输出路径

在这里插入图片描述

图 32 工程菜单
打开工程属性窗体后点击生成选项卡，在输出界面点击浏览，选择路径为 MicroStation
安装路径下的 mdlapps 文件夹。
在这里插入图片描述

图 33 工程属性界面

例如，我的 MicroStation 安装在 C:\Program Files\Bentley\MicroStation CONNECT
Edition\MicroStation\Mdlapps，在下方菜单栏需定位至 Mdlapps 文件夹内。
在这里插入图片描述

图 34 输出路径选择界面

4.1.3 添加引用

为了使用 Bentley Addins 框架，我们在使用方法前需要引用包含该方法的库文件，这
里需要右键引用，选择添加引用。
在这里插入图片描述

图 35 引用菜单界面

在本案例中，我们需要调用系统的对话框，因此我们需要首先引用程序集中名为
System.Windows.Forms 的系统内置库文件，若需精准搜索，可直接在右上角输入关键
字，即可快速筛选出含有关键字的库文件，如下图所示。
在这里插入图片描述

图 36 引用筛选界面
为了建立 Addins 框架，我们需要引用 Bentley 软件中的库文件 ustation.dll，这里我们点击浏览，在 MicroStation 安装文件夹下找到名为 ustation 的库文件，选取该项。注意，
在文件夹中您可以按住 Ctrl 多选库文件，借以提高效率。选择完毕后点击确定。

在这里插入图片描述

图 37 选择引用界面
常用动态库及功能说明如下图所示，关于更多的库文件使用说明您可以参照 SDK 中的
帮助文档或中国优先社区相关资料做进一步的了解。
在这里插入图片描述

图 38 常用库文件及功能简述

4.1.4 类名修改

为了更好的管理文件，我们需要对类文件名进行修改，这里我们右键 Class1，点击重命
名，命名为 MyAddin，说明该文件的目标——建立 Addins 框架。
在这里插入图片描述

图 39 类文件属性界面

4.1.5 建立 Addins 框架

我们将 MyAddins 中的代码修改为下图所示，注意：要是一个.NET 程序集能够作为
Addins 在 MicroStation 中运行，需要满足以下三个条件：
1.包含一个派生于 Bentley.MstnPlatformNET.Addin 的类；
2.该派生类必须提供一个单参数， (即指针类型的 MDL 描述符)的构造函数，且该构造函
数需要链接到基类构造函数上；
3.该派生类必须覆盖 Addin 基类中的虚方法 Run()， Run 函数是构造函数执行完以后第一个被执行的函数，有点类似与传统编程中的 Main 函数。接下来我们在 Run 函数中输入
MessageBox.Show(“Hello World!”)。
在这里插入图片描述

图 40 Addins 框架

4.1.6 生成解决方案

我们右键工程，点击生成，或点击菜单栏上的生成——生成解决方案，需要注意的
是，若您只想编译指定的某个工程，则只能选择第一种方法，第二种方法会将该解决方案
中的所有工程都进行编译。

在这里插入图片描述

图 41 工程菜单栏
在下方输出界面我们可以看到在我们选择的输出文件夹：C:\Program
Files\Bentley\MicroStation CONNECT Edition\MicroStation\Mdlapps 生成了一个名为
csAddin 的库文件。
在这里插入图片描述

图 42 工程输出结果

4.1.7 验证结果

我们打开 MicroStation，打开键入命令界面，输入 mdl load csAddin，回车后出现一个
写着“Hello World!”的对话框。
在这里插入图片描述

图 43 键入命令界面
在这里插入图片描述

图 44 键入结果

4.2 具有命令指向的 Addins 框架

当我们需要实现多个功能时，如果开发一个功能就创建一个工程，那么反复创建框架不仅会极大影响编码的速度，同时无论是工程还是生成的库文件都存在管理困难的问题，具有命令指向的 Addins 框架可以实现在一个工程中写入多个命令执行不同功能，方便对代
码和功能的统一管理。

4.2.1 修改 XML 文件

我们首先在 SDK 文件中的 Example 文件夹下，找到 Elements 文件下的
ManagedFenceExample，找到其中的 Command.xml 文件后复制到本工程的文件夹下。
在这里插入图片描述

图 45 ManagedFenceExample 文件夹

在这里插入图片描述

图 46 工程文件夹
我们打开本工程文件，点击显示所有文件后找到我们从案例文件中复制过来的
command.xml 文件，右键点击该文件，选择包括在项目中。
在这里插入图片描述

图 46 解决方案管理器
可被 Bentley Addins 识别为命令的 xml 文件中有且仅有一个 KeyinTree 节点，其下由
三部分组成，分别为： RootKeyinTable、SubKeyinTables 和 KeyinHandlers。他们分别表

示命令的根键入表，子键入表和命令键入对应的处理函数名称。值得一提的是，
keyinhandler 中的 keyin 需要与上面 RootKeyinTable、SubKeyinTables 中的文字匹配起来，而 keyinhandlers 中的 function 为处理该命令对应的函数名称，换句话说，当用户在
MicroStation 中输入 keyin 指定字符串时，就会调用到 function 函数中对应的函数。
在这里插入图片描述

图 47 xml 文件
接下来，我们试着将原来的 command 命令改造成与我们工程的匹配的形式。同时，点
击 xml 文件查看属性，确认在生成操作一栏为嵌入的资源。
xml 文件的文件格式
初次接触 xml 文件时，肯定会有种雾里看花的感觉，其实， xml 文件的结构非常简单，您可以简单的将 xml 文件想象为一个树状图，即一个节点可以有多个分支，而每个分支也可以有多个分支，而他们之间使用了“<…>… </…>”或“<…/>”来进行组织。在撰写 xml 文件内容时需要注意符号匹配，简单来说，“<>”有点像括号的“{”，而 “ < …/>”像是“}”，即在
其中包含不限个数分支的信息，而“<…/>”有点像“(…)”，其中包含一个分支的信息。

在这里插入图片描述

图 48 xml 属性界面

4.2.2 修改配置文件

修改完成后保存，打开在文件夹内打开该工程的资源文件。
注意：
1.在修改配置文件后需要重新加载工程，若此前在 Visual Studio 中未对工程进行保存，则
会造成数据丢失。
2.打开配置文件(*.csproj)不可双击，否则则会直接启动 Visual Studio 打开该工程，无法对
配置文件进行编辑。您可以下载 VSCode，或使用记事本打开该文件来进行修改。

在这里插入图片描述

图 49 修改前的配置文件
为了让 commands.xml 命令顺利被 Addins 框架识别，我们将这一行改写为如下格式：
在这里插入图片描述

图 50 修改后的配置文件

4.2.3 添加属性定义

接下来，我们将 Run 函数中的语句删除，并添加属性定义，关于属性定义我们可以打开 MicroStation 软件，打开 key-in，输入 mdl load ，若插件已被加载，在下图位置即可
看到 MdlTaskID 中定义的文字，双击文字后即可看到在 xml 文件中定义的命令。
在这里插入图片描述

图 51 添加属性定义
在这里插入图片描述

图 52 应用定义名称

4.2.4 补充业务功能

我们再将命令键入对应的处理函数 Function 所需要执行的功能函数补充完整，即当 MicroStation 中输入了指定 key-in，程序会根据 key-in 执行对应 Function 指向的方法，
下图即为修改后的结果。
在这里插入图片描述

图 53 Function 函数指向的业务方法

4.2.5 生成解决方案并验证

接下来我们生成解决方案并打开 MicroStation 进行验证，打开主程序后点击 key-in，
输入 mdl load csAddin 加载插件，然后输入 output words success，点击回车后即弹出一
个写着 Success 的对话框。此时您已经实现一个具有命令指向的 Addins 插件。

在这里插入图片描述

图 54 插件执行效果

4.3 快速配置 Addins 程序框架

因为框架本身仅是功能实现的载体，若您的编程经验尚浅或需要快速编写程序，该部分
很有必要了解一下。

4.3.1 拷贝 SDK 文件

首先在 SDK 中找到 Example-DgnEC-ItemType，复制 ManagedExample 到自定义位
置，接下来删除 mke 文件与 readme 文件，删除后结果如下图：
在这里插入图片描述

图 55 删除文件后结果

4.3.2 修改配置文件

右键用文本方式打开该工程的配置文件，在 Property Group 下添加MicroStation 安装地址和 $(MS) < / R e f ere n ce P a t h > ，因为下方可以看到在引用参照时， M i cro St a t i o n 的安装路径都使用$ (MS)进行替代，但是若直接启动工程时，因
$(MS)指代不明，因此会造成找不到引用的情况，此时就需要给出一个定义，让程序知道
$(MS)所代表的意义。
在这里插入图片描述

图 56 工程配置文件

4.3.3 修改命令并添加业务方法

接下来创建业务函数，并将命令修改为业务功能需要的形式。

在这里插入图片描述

图 57 修改后的命令
在这里插入图片描述

图 58 业务方法

4.3.4 生成解决方案与验证

在生成解决方案后打开 MicroStation 验证结果，加载插件后可以发现 key-in 与命令文件中定义的一一对应。回车即得到一个写着“Hello World“的对话框。相较于一步一步搭建
框架，该方法可极大程序的节约时间。

在这里插入图片描述

图 59 结果验证

4.4 使用模板快速创建 Addins 程序框架

您也可以使用本次课程附带的模板压缩包，用以快速建立起 Addins 程序框架，使用该
模板您可以直接跳过框架的建立，转而专注于业务功能的编写。

4.4.1 放置模板

我们将模板文件放在 Visual Studio 的文档路径下的模板文件夹内，默认路径如图中所
示：

在这里插入图片描述

图 60 默认模板放置路径

4.4.2 使用模板

放置完成后打开 Visual Studio，点击创建工程，这时可以发现在 Visual C#下有一个名为 csAddin 的模板，选择该模板，确认工程名称与存储路径后点击确定，此时 Addins 框
架以自动搭建完成。
在这里插入图片描述

图 61 工程创建界面

在这里插入图片描述

图 62 由模板创建的工程

4.5 SDK 使用说明

在安装 SDK 成功后，安装路径下可以看到工具文件夹（bin）、头文件（include）、库
文件（library）、开发示例（examples）、帮助文档（Documentation）等文件或文件
夹，在桌面上会出现 MicroStation Connect Edition SDK 的快捷方式。这里主要介绍一下
帮助文档，开发示例及黑窗口的使用方法。

4.5.1 帮助文档使用说明

打开帮助文档文件夹后可以发现，其中包含面向不同程序集的说明文档，其中带有 NET 关键字的是包含使用 C#语言编写的方法，例如我们如果经常使用的 DgnPlatformNet。接
下来我将以此帮助文档为例，介绍一下帮助文档的使用方法。

在这里插入图片描述

图 63 帮助文档文件夹
打开帮助文档后，左边有三个选项卡， Contents—— 目录， Index——索引与 Search—
—搜索。
目录显示了该帮助文档中方法的组织关系：

在这里插入图片描述

图 64 帮助文档目录选项卡
使用索引选项卡在文字输入栏中输入需要找到的类或方法的关键字后，可快速显示关于该类的相关信息，是使用频率最高的功能，当我们不清楚某个方法如何使用时，我们可以
通过该模块快速找到对应信息，根据功能描述与入参，输出参数说明快速上手。

在这里插入图片描述

图 64 帮助文档索引选项卡
使用搜索选项卡在文字输入栏中输入关键字后，他会将所有含有关键字的页面都列在结
果框中。
在这里插入图片描述

图 65 帮助文档搜索选项卡
帮助文档右侧为方法说明，右上角的 Code 按钮，点击之后我们可以根据我们编程使用
的语言，过滤掉我们不关心语言对应方法的内容。下方即为该方法的命名空间与引用说

明，构造形式，并附有参数的类型与说明，若您对该方法的参数有疑问，您也可以通过点
选参数链接的方式转到对应的参数说明介绍页面上了解相关信息。
在这里插入图片描述

图 66 帮助文档

4.5.2 案例文件使用说明

在 Example 文件夹中包含有许多基于 MicroStation SDK 开发的案例，您可以根据自己
的需要参考对应的案例，比如说，若您需要对模型进行操作，您可以点击 Model 文件
夹，查看是否有您可以参考的例子。值得一提的是，SDK 中的例子分为使用 C++语言编写的和使用 C#语言编写两种方式，若您基于 C#语言 Addins 开发时，您可参考前缀为
Managed 打头的案例。
在这里插入图片描述

图 67 案例文件夹

若需要运行或在线调试案例，则需首先打开桌面上的 MicroStation CONNECT Edition SDK 快捷方式，找到需要运行的案例文件地址，复制后待黑窗口加载完毕后，输入 cd 空
格加案例的文件夹地址回车，转至案例的文件夹下，输入带有.sln 后缀的工程（例如：
ManagedFenceExample.sln）或批处理文件 openSln.bat 点击回车，此时 Visual Studio
程序自动启动并加载该工程。
在这里插入图片描述

图 68 工程加载界面
若需要查看案例效果，您可以打开单个案例后使用 Visual Studio 生成库文件，也可以使用黑窗体，输入 buildallexamples ，此时 SDK 中的所有案例都会编译成库文件。生成后通
过 MicroStation 中的 key-in，输入 mdl load 空格加库文件的名称加载查看运行结果。
在这里插入图片描述

图 69 编译全部案例后的结果

不见不散com

关注

29
点赞
踩
30

收藏

觉得还不错? 一键收藏
0
评论
Bentley二次开发教程03-第一个插件HelloWorld

接下来，我们将 Run 函数中的语句删除，并添加属性定义，关于属性定义我们可以打开 MicroStation 软件，打开 key-in，输入 mdl load ，若插件已被加载，在下图位置即可看到 MdlTaskID 中定义的文字，双击文字后即可看到在 xml 文件中定义的命令。图 51 添加属性定义图 52 应用定义名称。
复制链接

扫一扫