基于SuperMap iDesktop 从零开始创建 C# 类库进行插件开发

作者：巡巡

前言：有些客户不满足于iDesktop的现有功能，想要自行对iDesktop做插件开发，但对于插件开发又没有什么思路，一头雾水，帮助文档上的说明也过于老旧。小编最近编写了一个简单的基于SuperMap iDesktop插件，现整理了一下插件从开发到打包安装的步骤，针对小白插件开发者来说十分友好，希望能对各位程序员们有帮助，本篇文档的插件链接如下： https://download.csdn.net/download/supermapsupport/87354853 如有需求可自行下载查看。

一、准备工作和环境配置

关于前期准备和环境配置部分，大家可以该篇参考博客中关于准备工作和环境配置部分，链接如下: https://blog.csdn.net/supermapsupport/article/details/127007251，对此我就不再做过多的介绍。针对于引用的文件，用户可以根据自己的需求进行引用。

注意：使用窗体程序还需引入DevExpress.Utils.v17.1.dll文件。

二、插件开发

用户可以参考原有的示例代码运行查看，SuperMap iDesktop 10i / 11i 安装目录下的 SampleCode 目录有一些关于 iDesktop插件开发示例代码，用户可直接修改已有的示例代码，实现 SuperMap iDesktop 10i / 11i 自定义插件开发。如没有，可以在离线帮助文档中下载，如下图：

用户也可以参考该篇文档从零创建C#库类进行插件开发。

2.1、配置文件

用户可以轻易的通过插件配置文件 （*.config） 进行自定义扩展插件在 SuperMap iDesktop 桌面端上布局、状态等调整。用户每开发一个插件，都要为该插件配以一个相应的配置文件，插件配置文件包括的内容主要有插件配置、界面元素配置及帮助系统的配置等。SuperMap iDesktop 配置文件都是以 *.config 为扩展名，以标准的 XML 格式编写和存储，同时，插件必须要有命名空间，值为 http://www.supermap.com/desktop。

2.1.1、新建应用程序配置文件
如下图所示：

由于上述步骤已经配置了项目的生成后事件命令用于拷贝新建的 应用程序配置文件 ，所以不需要再将配置文件在编译时输出。

2.1.2、编写配置文件

可配置文件菜单，配置快捷按钮栏，配置状态栏，配置右键菜单，配置功能区等。
关于配置文件的编写，大家可以详细参考帮助文档中的【扩展开发指南】->【编写应用程序的配置文件】部分，在此文档中只讲解几个重要的参数。
在本示例中的配置文件编写如下，大家可在以下基础上修改，供大家参考：

<?xml version="1.0" encoding="utf-8"?>
<plugin xmlns="http://www.supermap.com.cn/desktop" name="test" author="test" url="www.supermap.com.cn"
 description="DesktopPlugin1 Plugin" helpLocalRoot="" helpOnlineRoot="">
	<runtime assemblyName="./Plugins/test/SuperMap.Desktop.Ext.test.dll" className="SuperMap.Desktop.Ext.DesktopPlugin" loadOrder="2000" enabled="True" />
	<!--Ribbon上自定义各种控件-->
	<toolbox>
		<ribbon>
			<tabs>
				<tab index="3" id="DataProcess" label="数据" formClass="" visible="true">
					<group index="3" id="DataProcess" label="数据处理" image="" visible="true">
						<gallery index="10" id="DataProcess" visible="" style=""  >
							<galleryItems index="1" id="Vector" visible="" label="">
								<buttonGallery index="30" label="查询重叠点线面" visible="" checkState="" assemblyName="./Plugins/test/SuperMap.Desktop.Ext.test.dll"
								  onAction="SuperMap.Desktop.Ext.myCtrlAction" image="./Plugins/test/img/重复.png"
								  style="" screenTip="打开对话框，进行重叠的点或线或面重叠的查询。" screenTipImage=""
								  helpURL="WebHelp\UseExplanation\Ribbon\tabs\datasource\groups\newcreatedataset\CreateDatasetPoint.html" />
							</galleryItems>
						</gallery>
					</group>
				</tab>
			</tabs>
		</ribbon>
	</toolbox>
</plugin>

讲解几个较为重要的参数配置：

1. runtime：标签用于提供插件运行库的信息。
   • assemblyName： 程序集文件名称，可以是相对于可执行程序的相对路径，也可以是绝对路径，该属性的值必须正确设置。

• className：实现插件的类名称，该类必须从 Plugin 类继承。这里给定的实现插件的类名称必须是全名，即需要指定其命名空间。该属性的值必须正确设置。
• loadOrder：插件的加载顺序，使用整数来标识插件的加载顺序，该值越小，插件越先加载，该属性的值必须正确设置。注意：当用户新建的插件依赖于系统提供的插件时，必须保证先启动系统提供的插件。
• enabled：用于控制是否加载该插件。true 表示加载，可以使用该插件；false 表示不加载，禁用该插件。

2. buttonGallery 按钮

• index：用于排序功能区上的选项卡（tab 页），即当功能区存在多个选项卡时，每个选项卡将通过该项的值来确定其在功能区的排列次序。
• id：选项卡支持多个不同配置文件里的项进行合并显示，合并的依据就是通过 id 来实现的，也就是说我们可以在 A 插件的配置文件中配置一个选项卡，指定一个 id，同时在 B 插件里面也配置一个选项卡，指定相同的 id，在系统显示时，这两个选项卡中的项将会合并到一起，放到一个选项卡上显示。
• assemblyName： 同上。
• onAction：通过该属性可以指定用于响应 buttonGallery 按钮的点击事件所执行的内容，该属性可以指定为一个继承 CtrlAction 类或者实现了 ICtrlAction 接口的类，并且要指定该类的全名，即需指出该类的命名空间。例如，在本例中，onAction绑定的文件名为myCtrlAction.cs的库类（在本文后面会讲解到该类），该类的工作空间是SuperMap.Desktop.Ext，所以该处的写法是 SuperMap.Desktop.Ext.myCtrlAction。

注意：关于index和id这两个参数的设置，大家可以在【视图】->【环境设计】进行查看。

2.2、构建plugin类

该类用来设置插件定义类。每一个插件都必须存在于一个类中，该类由plugin类派生，主要用来负责插件的初始化和退出等相关工作

2.2.1新建plugin类
新建一个类，如下图所示：

2.2.2代码编写：
创建完成后，需要设置引用using SuperMap.Desktop;
并且该类需要继承自Plugin。代码如下：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SuperMap.Desktop;

namespace SuperMap.Desktop.Ext
{
    
    
    internal class DesktopPlugin:Plugin
    {
    
    
        public DesktopPlugin(PluginInfo pluginInfo)
    : base(pluginInfo)
        {
    
    
        }
        public override Boolean Initialize()
        {
    
    
            return true;
        }

        public override Boolean ExitInstance()
        {
    
    
            return true;
        }

    }
}

到此，你通过运行程序已经能够正常运行程序，并且在对应的位置能够看到标签按钮了。如下图所示：

接下来就是设置插件程序启动后的入口程序了，通过新建CtrlAction完成。

2.3、实现Run函数

Run函数是插件程序启动后的入口程序，即程序的入口点。简单的说，就是在iDesktop中点击插件运行的事件。

2.3.1、新建类myCtrlAction
如下图所示：

2.3.2代码编写
该类继承自CtrlAction ，在该类中重载public override void Run()方法，即当控件事件被触发时，将调用对象的Run() 方法，添加代码如下：（该代码示范了点击桌面的按钮时，弹出Form1窗体）

namespace SuperMap.Desktop.Ext
{
    
    
    class myCtrlAction:CtrlAction
    {
    
    
        public myCtrlAction(IBaseItem caller)
    : base(caller)
        {
    
    
        }
        public override void Run()
        {
    
    
            Form1 form = new Form1();
            form.ShowDialog();
        }
    }
}

2.4、窗体设计

2.4.1、新建用户控件（Windows 窗体）
如下图：

2.4.2、配置窗体环境
窗体创建成功以后，在新建的窗体中右键查看代码，进行编辑。
1）、拓展开发的插件都有一个统一的基础接口IForm，因此修改窗体继承的父类：Form1 -> UIForm
2）、至少引入 4 个命名空间：using SuperMap.Desktop.UI、using SuperMap.Data、using DevExpress.Utils

2.4.3、界面设计
可以有两种方法：
1）、用户可以通过vs2022来进行窗体的设计，vs2022支持64位的控件拖拽
2）、通过代码进行窗体设计
如果想要设计风格和桌面一致的控件，需要在设计时使用SuperMap.Desktop.UI.。例如：SuperMap.Desktop.UI.UIButton()，SuperMap.Desktop.UI.UIGroupBox()等。
很明显就能看到风格与iDesktop保持一致啦，界面设计如下图所示：

到此为止，我们可以运行程序看一下，通过此刻我们已经能看到，通过点击按钮，能够正常弹出窗体了，如下图所示，接下来就是功能代码的编写了。

2.5、程序功能编写

首先操作的前提是我们要获取workspace工作空间，那在子窗体中如何获得当前程序的工作空间呢？
这就要使用到我们的Application 类。

Application 类：应用程序类，实现启动主窗口、插件管理和代码段编译执行等功能。对于 SuperMap iDesktop 桌面产品来说，一个主窗口及相关资源对应一个 Application 类（应用程序类）。实例对象管理的内容包括：工作空间（Workspace），用于管理应用程序内的插件的插件管理器（PluginManager），代码段编译执行器（IScript），应用程序的主窗口（IFormMain），应用程序的启动界面（ISplashForm）以及应用程序的输出信息方面的管理。

插件开发中最普遍常用的功能就是获取当前的工作空间，以及输出窗口信息。
获取当前的程序的工作空间： SuperMap.Desktop.Application.ActiveApplication.Workspace
既然已经获取到workspace工作空间了，那其余代码就和iObjects.net的编写区别不大。大家根据自行的需求进行编写即可。
信息输出和日志记录：SuperMap.Desktop.Application.ActiveApplication.Output，示例代码如下：

 // 信息一：单参数输出方法，会自动当做 InfoType.Information 类型输出信息。
    SuperMap.Desktop.Application.ActiveApplication.Output.Output("单参数输出方法，会自动当做 InfoType.Information 类型输出信息。");

    // 信息二：信息（InfoType.Information）类型的输出信息。
    SuperMap.Desktop.Application.ActiveApplication.Output.Output("信息（InfoType.Information）类型的输出信息。", InfoType.Information);

    // 信息三：异常（InfoType.Exception）类型的输出信息。
    SuperMap.Desktop.Application.ActiveApplication.Output.Output("异常（InfoType.Exception）类型的输出信息。", InfoType.Exception);

    // 结果：
    // 当桌面全局选项设置仅输出“信息”的时候，会在输出窗口中看到信息一和信息二；
    // 当桌面全局选项设置仅输出“异常”的时候，会在输出窗口中看到信息三；
    // 当桌面全局选项设置输出“异常和信息”的时候，会在输出窗口看到所有三条信息

三、打包

项目生成过程中会根据上述步骤配置的 生成后事件命令 将配置文件拷贝到 SuperMap iDesktop 安装目录\WorkEnvironment\Default 目录下，如下图所示：

项目构建成功后，会根据上述步骤配置的 输出路径 将插件包输出到 SuperMap iDesktop 安装目录\Bin\Plugins\test目录下，如下图所示：

程序编写完以后，确认程序代码无误以后，最后一步就是进行打包。
找到程序输出路径，在\Bin\Plugins\下找到对应的文件夹，例如本例中的：.\supermap-idesktop-11.1.0-1019-43617-97920-win64-bin-zip-chs\Bin\Plugins\RepetitiveRegion。
注意：检查该文件夹下的.config文件，确保是自己项目中新建的.config文件，如有其他配置文件，请删除，只保留一个配置文件，否则会插件导入会解析失败。
将该文件夹压缩成zip包以后就完成打包啦。

四、插件拷贝安装

此时的zip包可以作为插件导入到其余版本或其余电脑的iDesktop中啦，在【视图】-【插件管理】即可进行导入

直接导入下载的.zip压缩包，成功导入后会显示成功安装界面。

五、插件卸载

如果用户想从 SuperMap iDesktop 中移除该插件功能，只需将"安装目录\WorkEnvironment\Default"目录下的 SuperMap.Desktop.Samples. test.config 文件和“安装目录\Bin\Plugins\ test”文件夹删除即可；如果用户想再次使用该插件功能，则需重新安装。

好啦，一个简单的插件开发就讲到这里啦，希望能对各位程序员有所帮助。当然每一个项目的实现需求不一致的，不同需求还需要去寻求不同的解决方案。
如有错误，希望大家也能在评论区批评指正！