第一期视频回放

点击查看【bilibili】

相关资料

MicroStation安装包
下载地址：
https://connect.bentley.com/
MicroStation SDK安装包
下载地址：
https://connect.bentley.com/
Visual Studio安装包
下载地址：
https://visualstudio.microsoft.com/
模板及本期文字版下载地址：
链接：https://pan.baidu.com/s/1j4EpN0pJ6bwKql3RXogHHg
提取码：3rxh

第一期文字版

1 Bentley平台介绍

image.png
图1 Bentley平台介绍
Bentley软件大致可分为四大平台，分别为用于设计的Microstation平台，用于协同的ProjectWise平台，用于对资产进行全生命周期管理的AssetWise平台和数据互联互通的数字孪生平台iTwin。

1.1 MicroStation

MicroStation，即Bentley的基础图形平台软件。它基于三维设计，支持实体建模、B样条曲面建模和网格建模三大三维图形内核，可兼容其他各种图形平台导入的数据格式。同时，MicroStation还是一个囊括二维绘图、三维建模、图形渲染，动画制作的全方位多功能图形平台。基于强大的MicroStation平台，根据各个专业的不同需求，Bentley开发出面向不同专业的Open系列设计软件，生成模型可利用Bentley开发的计算软件进行结果分析。

1.2 ProjectWise

为满足企业跨时间，跨空间协作的需求，ProjectWise平台提供了一个集成的协同环境，可以精确有效地管理各个专业的文件内容，并通过良好的安全访问机制，供项目各个参与方在一个统一的平台上协同工作。

1.3 AssetWise

AssetWise平台主要用于对资产在全生命周期中的管理，它是一系列软件的统称，其中核心软件叫做eB。eB软件提供有从项目前期的合同管理到设计阶段的管理到项目移交、运营直至某个管件的作废的 “全生命周期”管理过程。

1.4 iTwin

在整个建设周期中，传统迭代过程中获得到的信息被不断积累——抛弃，而在数据孪生中，数据被不断的被积累、迭代、优化，周而复始，从而提升整个流程的决策，降低风险，提高生产力和应变能力。iTwin平台可兼容各种类型的数据格式，并保证信息无损，通过信息整合统筹管理，优化物理资产。

2 Bentley平台插件开发介绍

2.1 Bentley产品SDK间关系介绍

image.png
图2 Bentley产品SDK关系
虽然Bentley拥有几乎涵盖了各个专业的设计软件，但在实际应用中，可能会出现在特定场景下无法适配的情况，此时就需要通过二次开发的方式实现既定的功能需求，这也就是Bentley软件提供软件开发包的初衷与意义。您可以通过使用软件开发包开发出符合您自身业务需求的工具甚至软件，借此提高生产力。我们可以看到上图列有MicroStation SDK和ORD SDK，ORD（OpenRoadsDesigner）是Bentley公司面向道路专业设计的一款专业软件，它们是两个独立的软件安装包。如果您只基于MicroStation中的对象进行开发，在安装MicroStation的基础上安装MicroStation SDK即可。若要基于ORD做开发，则需安装ORD SDK。在ORD二次开发程序中您既可以通过ORD SDK去访问DGN文件中的ORD专用对象（比如边坡，廊道等），还可以通过MicroStation SDK去访问DGN文件中的通用对象（比如文字、标注、普通的几何体等）。若您对特定专业的二次开发感兴趣也欢迎您登陆中国优先社区或Bentley-learn网站了解更多信息。

2.2 Bentley软件开发语言介绍

image.png
图3 Bentley软件支持的开发语言表
Bentley设计软件支持三种开发语言：VBA、C#和C++。VBA语言仅需安装MicroStation，简单易学，但存在API接口不全，在开发大型程序时较为困难；C#语言需安装MicroStation与VisualStudio，相对于C++来说，上手难度较低，可使用Winform，WPF定制界面灵活性较大，可以满足开发大型程序的需要。C++语言需安装MicroStation，VisualStudio与对应的SDK，具有功能最全，性能最佳的优势，但也存在学习成本较大，界面不易制作的问题。
目前关于C#语言的SDK封装已经日趋完整，因为其语言自身无需关心内存的开辟与回收的特点，可以让您更加专注于业务功能的实现，因此若您的编程技术较弱，或需要快速编写业务功能，推荐您使用C#语言进行Bentley软件的二次开发。

2.3 MicroStation托管应用开发架构

image.png
图4 Bentley软件开发架构
MicroStation托管应用开发架构（即使用C#语言对Bentley基础平台进行二次开发）主要分为以下六大块：
几何库：主要负责几何层面的变换与修改；
属性表达库：主要负责工程属性的添加与修改；
DGN平台库：主要负责读写dgn文件的操作；
DGN文件显示库：主要负责dgn文件的内容显示或交互式工具；
MicroStation应用库：主要对管理器，会话等应用继续管理；
Addins工具：可调用上述所有库。
在开发过程中，主要调用的API主要有：
几何API
image.png
图5 常用几何API
主要面向应用程序提供几何运算方面的支持，他提供了通用的几何图元，包含几何对象的创建，编辑，定位等操作。
元素API
image.png
图6 常用元素API
主要用于对元素的控制。元素为MicroStation中构件的基本单位，MicroStation有很多种类型的元素，我们可以将其分成图形元素和控制元素。
模型API
image.png
图7 常用模型API
主要用于对数据，例如存储构件的容器及模型层面的环境配置等进行操作，或对于视图，比如说对元素显示，视图布局等进行控制。
文件API
image.png
图8 常用文件API
主要用于修改模型的容器及环境配置，比如说图层，样式，字体，EC属性等。
事件API
image.png
图9因指定事件出现触发API
image.png
图10 常用事件API表
主要用于监控用户特定操作事件，在用户做出指定操作后触发。
管理器API
image.png
图11 常用管理器API

通过这些接口我们可以直接调用到MicroStation中的一些功能。例如通过ACSManager我们可以对坐标系进行变换，通过SelectionSetManager这个类完成对选择集的操作。
约束及参数化API
image.png
图12 约束及参数化API
在创建参数化模型时，通常需要先规划一下参数化模型需要哪些参数去控制。若前期规划得当，后期可以省去很多修改模型带来的麻烦。SDK中提供了参数化建模的编程接口。
DgnTool命令工作集
image.png
图13 人机交互界面
image.png
图14 常用事件虚函数功能对照表
MicroStation中超过一半的功能都是以交互式工具的形式而存在的，我们可以通过重写该工具集中的虚函数来实现所需功能。通过上述API协调配合，实现既定的功能。

3 开发环境搭建

3.1 MicroStation安装流程介绍

image.png
图15 双击运行安装包
image.png
图16 勾选“我接受最终用户许可协议”
image.png
图17 若需修改安装路径则点击该项
image.png
图18 等待程序自动下载安装即可
image.png
图19 程序安装完成

3.2 MicroStation SDK安装流程介绍

image.png
图20 双击运行安装包
image.png
图21 勾选“我接受最终用户许可协议”
image.png
图22 若需修改安装路径则点击该项
image.png
图23 程序安装完成

3.3 Visual Studio安装流程介绍

image.png
图24 双击运行安装包
对于Bentley平台的开发来说，若使用C#语言进行开发，需勾选.NET桌面开发，若使用C++语言进行开发，则需勾选使用C++的桌面开发。您可根据您的实际情况按需安装，同时后续也可在Visual Studio中继续添加模块。
image.png
图25 Visual Studio模块安装界面
因为Bentley二次开发基于.NET Framework4.6.2，因此，若您安装的Visual Studio版本为2017，请注意勾选.NET Framework 4.6.2开发工具。image.png
图26 模块安装界面
image.png
图27 若需修改安装路径则点击该项
image.png
图28 等待程序自动下载安装即可

4 Addins程序编写

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

4.1 一步一步建立Addins框架

4.1.1 创建工程

image.png
图29 点击新建工程
选择类库（Class Library），若需要修改工程建立位置则点击浏览，最后确定.NET Framework的版本为4.6.2，确认无误后点击确定生成解决方案。需要注意的是，目前MicroStationU16版本基于.NET 4.6.2，后续随着版本迭代可能会升级到更高版本，而U16.1版本推荐您使用VisualStudio2019进行插件的开发。启动VisualStudio请注意使用管理员权限打开。
image.png
图30 创建工程菜单
image.png
图31 程序编写界面
点击确认按钮后会出现所下图所示界面，左侧为自动生成的C#代码，右侧为解决方案浏览器窗体，我们在菜单键上右键工程，打开项目属性窗体。

4.1.2 修改输出路径

image.png
图32 工程菜单
打开工程属性窗体后点击生成选项卡，在输出界面点击浏览，选择路径为MicroStation安装路径下的mdlapps文件夹。
image.png
图33 工程属性界面
例如，我的MicroStation安装在C:\Program Files\Bentley\MicroStation CONNECT Edition\MicroStation\Mdlapps，在下方菜单栏需定位至Mdlapps文件夹内。
image.png
图34 输出路径选择界面

4.1.3 添加引用

为了使用Bentley Addins框架，我们在使用方法前需要引用包含该方法的库文件，这里需要右键引用，选择添加引用。
image.png
图35 引用菜单界面
在本案例中，我们需要调用系统的对话框，因此我们需要首先引用程序集中名为System.Windows.Forms的系统内置库文件，若需精准搜索，可直接在右上角输入关键字，即可快速筛选出含有关键字的库文件，如下图所示。
image.png
图36 引用筛选界面
为了建立Addins框架，我们需要引用Bentley软件中的库文件ustation.dll，这里我们点击浏览，在MicroStation安装文件夹下找到名为ustation的库文件，选取该项。注意，在文件夹中您可以按住Ctrl多选库文件，借以提高效率。选择完毕后点击确定。
image.png
图37 选择引用界面
常用动态库及功能说明如下图所示，关于更多的库文件使用说明您可以参照SDK中的帮助文档或中国优先社区相关资料做进一步的了解。
image.png
图38 常用库文件及功能简述

4.1.4 类名修改

为了更好的管理文件，我们需要对类文件名进行修改，这里我们右键Class1，点击重命名，命名为MyAddin，说明该文件的目标——建立Addins框架。
image.png
图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!”)。
image.png
图40 Addins框架

4.1.6 生成解决方案

我们右键工程，点击生成，或点击菜单栏上的生成——生成解决方案，需要注意的是，若您只想编译指定的某个工程，则只能选择第一种方法，第二种方法会将该解决方案中的所有工程都进行编译。
image.png
图41 工程菜单栏
在下方输出界面我们可以看到在我们选择的输出文件夹：C:\Program Files\Bentley\MicroStation CONNECT Edition\MicroStation\Mdlapps生成了一个名为csAddin的库文件。
image.png
图42 工程输出结果

4.1.7 验证结果

我们打开MicroStation，打开键入命令界面，输入mdl load csAddin，回车后出现一个写着“Hello World!”的对话框。
image.png
图43 键入命令界面
image.png
图44 键入结果

4.2具有命令指向的Addins框架

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

4.2.1 修改XML文件

我们首先在SDK文件中的Example文件夹下，找到Elements文件下的ManagedFenceExample，找到其中的Command.xml文件后复制到本工程的文件夹下。
image.png
图45 ManagedFenceExample文件夹
image.png
图46 工程文件夹
我们打开本工程文件，点击显示所有文件后找到我们从案例文件中复制过来的command.xml文件，右键点击该文件，选择包括在项目中。
image.png
图46 解决方案管理器
可被Bentley Addins识别为命令的xml文件中有且仅有一个KeyinTree节点，其下由三部分组成，分别为：RootKeyinTable、SubKeyinTables和KeyinHandlers。他们分别表示命令的根键入表，子键入表和命令键入对应的处理函数名称。值得一提的是，keyinhandler中的keyin需要与上面RootKeyinTable、SubKeyinTables中的文字匹配起来，而keyinhandlers中的function为处理该命令对应的函数名称，换句话说，当用户在MicroStation中输入keyin指定字符串时，就会调用到function函数中对应的函数。
image.png
图47 xml文件
接下来，我们试着将原来的command命令改造成与我们工程的匹配的形式。同时，点击xml文件查看属性，确认在生成操作一栏为嵌入的资源。
xml文件的文件格式
初次接触xml文件时，肯定会有种雾里看花的感觉，其实，xml文件的结构非常简单，您可以简单的将xml文件想象为一个树状图，即一个节点可以有多个分支，而每个分支也可以有多个分支，而他们之间使用了“<…>…</…>”或“<…/>”来进行组织。在撰写xml文件内容时需要注意符号匹配，简单来说，“<>”有点像括号的“{”，而 “<…/>”像是“}”，即在其中包含不限个数分支的信息，而“<…/>”有点像“(…)”，其中包含一个分支的信息。
image.png
图48 xml属性界面

4.2.2 修改配置文件

修改完成后保存，打开在文件夹内打开该工程的资源文件。
注意：
1.在修改配置文件后需要重新加载工程，若此前在Visual Studio中未对工程进行保存， 则会造成数据丢失。
2.打开配置文件(.csproj)不可双击，否则则会直接启动Visual Studio打开该工程，无法对配置文件进行编辑。您可以下载VSCode，或使用记事本打开该文件来进行修改。
image.png
图49 修改前的配置文件
为了让commands.xml命令顺利被Addins框架识别，我们将这一行改写为如下格式：
image.png
*图50 修改后的配置文件

  1. <EmbeddedResource Include="Commands.xml">
  2.           <SubType>Designer</SubType>
  3.           <LogicalName>CommandTable.xml</LogicalName>
  4. </EmbeddedResource>

4.2.3 添加属性定义

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

4.2.4补充业务功能

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

4.2.5 生成解决方案并验证

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

4.3 快速配置Addins程序框架

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

4.3.1 拷贝SDK文件

首先在SDK中找到Example-DgnEC-ItemType，复制ManagedExample到自定义位置，接下来删除mke文件与readme文件，删除后结果如下图：
image.png
图55 删除文件后结果

4.3.2 修改配置文件

右键用文本方式打开该工程的配置文件，在Property Group下添加MicroStation安装地址和$(MS)，因为下方可以看到在引用参照时，MicroStation的安装路径都使用$(MS)进行替代，但是若直接启动工程时，因$(MS)指代不明，因此会造成找不到引用的情况，此时就需要给出一个定义，让程序知道$(MS)所代表的意义。

  1. <MS>C:\Program Files\Bentley\MicroStation CONNECT Edition\MicroStation\</MS>
  2. <ReferencePath>$(MS)</ReferencePath>

image.png
图56 工程配置文件

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

接下来创建业务函数，并将命令修改为业务功能需要的形式。
image.png
图57 修改后的命令
image.png
图58 业务方法

4.3.4 生成解决方案与验证

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

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

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

4.4.1 放置模板

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

4.4.2 使用模板

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

4.5 SDK使用说明

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

4.5.1 帮助文档使用说明

打开帮助文档文件夹后可以发现，其中包含面向不同程序集的说明文档，其中带有NET关键字的是包含使用C#语言编写的方法，例如我们如果经常使用的DgnPlatformNet。接下来我将以此帮助文档为例，介绍一下帮助文档的使用方法。
image.png
图63 帮助文档文件夹
打开帮助文档后，左边有三个选项卡，Contents——目录，Index——索引与Search——搜索。
目录显示了该帮助文档中方法的组织关系：
image.png
图64 帮助文档目录选项卡
使用索引选项卡在文字输入栏中输入需要找到的类或方法的关键字后，可快速显示关于该类的相关信息，是使用频率最高的功能，当我们不清楚某个方法如何使用时，我们可以通过该模块快速找到对应信息，根据功能描述与入参，输出参数说明快速上手。
image.png
图65 帮助文档索引选项卡
使用搜索选项卡在文字输入栏中输入关键字后，他会将所有含有关键字的页面都列在结果框中。
image.png
图66 帮助文档搜索选项卡
帮助文档右侧为方法说明，右上角的Code按钮，点击之后我们可以根据我们编程使用的语言，过滤掉我们不关心语言对应方法的内容。下方即为该方法的命名空间与引用说明，构造形式，并附有参数的类型与说明，若您对该方法的参数有疑问，您也可以通过点选参数链接的方式转到对应的参数说明介绍页面上了解相关信息。
image.png
图67 帮助文档

4.5.2 案例文件使用说明

在Example文件夹中包含有许多基于MicroStation SDK开发的案例，您可以根据自己的需要参考对应的案例，比如说，若您需要对模型进行操作，您可以点击Model文件夹，查看是否有您可以参考的例子。值得一提的是，SDK中的例子分为使用C++语言编写的和使用C#语言编写两种方式，若您基于C#语言Addins开发时，您可参考前缀为Managed打头的案例。
image.png
图68 案例文件夹
若需要运行或在线调试案例，则需首先打开桌面上的MicroStation CONNECT Edition SDK快捷方式，找到需要运行的案例文件地址，复制后待黑窗口加载完毕后，输入cd空格加案例的文件夹地址回车，转至案例的文件夹下，输入带有.sln后缀的工程（例如：ManagedFenceExample.sln）或批处理文件openSln.bat点击回车，此时Visual Studio程序自动启动并加载该工程。
image.png
图69 工程加载界面
若需要查看案例效果，您可以打开单个案例后使用Visual Studio生成库文件，也可以使用黑窗体，输入buildallexamples，此时SDK中的所有案例都会编译成库文件。生成后通过MicroStation中的key-in，输入mdl load空格加库文件的名称加载查看运行结果。
image.png
图70 编译全部案例后的结果

5 开发资源与帮助

5.1 中国优先社区

image.png
图71 中国优先社区
中国优先社区（https://www.bentley.com/chinafirst）是Bentley为中国用户打造的产品、技术信息发布门户与用户沟通枢纽。目前中国优先社区主要提供以下三个板块，分别为技术资料库，问答与博客。其中，技术资料库主要提供了Bentley软件的安装，使用与功能说明，帮助您快速上手产品，同时还会有一些高级使用技巧与您分享。若您对Bentley产品和技术有任何问题，欢迎您在问答板块提出您的疑惑，有相关技术人员会第一时间为您提供解答。博客板块中则汇聚最新产品的发布与更新信息，同时也会分享合作伙伴的技术及产品信息。

5.2 中国BDN社区

image.png
图71 中国BDN社区
中国BDN社区（https://communities.bentley.com/communities/other_communities/bdn_other_communities）是面向Bentley软件二次开发用户打造的技术信息发布门户与技术交流平台。目前中国BDN社区主要提供以下三个板块，分别为技术资料库，博客与需求征集。其中，技术资料库中提供针对Bentley不同专业软件二次开发的需求，由专业技术人员编制的开发教程，帮助您全面掌握Bentley软件的开发技巧；博客中有资深专业技术人员分享最新的技术细节或开发技巧，助您在编程进阶之路上如虎添翼；需求征集板块则由用户提出亟待解决的需求，我们会根据您提出的需求在适当的时间提供解决办法。

5.3 Bentley软件官方教学

image.png图72 Bentley软件官方教学
Bentley软件官方教学——Bentley Learn。Bentley Learn（https://bentley-learn.com/index）主要面向需要学习Bentley软件的用户，视频由Bentley工程师筹划录制，全中文讲解。目前教学视频数已超过一千，并且在不断更新。

5.4 Bentley软件知识库

image.png
图73 Bentley软件知识库
Bentley软件知识库（https://www.yuque.com/bentleysystems），主要面向二次开发用户的资料库，提供包括编程教程，MicroStation软件，OpenRoadsDesigner软件及iTwin技术的开发及应用指导。

5.5 Bentley产品研发生态群

在该群中我们会不定期发布一些学习资料，开发技巧及插件，您也可以在该群中提出您在学习二次开发中遇到的问题，我们会有相关技术人员为您提供解答。
image.png
图74 Bentley产品研发生态群