ArcGIS Pro Add-In插件开发[ArcGIS Pro SDK for .NET]

本文基于 Windows7 + VS2019 + .NET Framework 4.8 + ArcGIS Pro 2.5.22081 开发和撰写。

开发环境配置

获取ArcGIS Pro

ArcGIS Pro可在Esri官网申请21天试用。

安装VS2019

VS2019的安装十分简单，在微软官网下载VS2019社区版安装程序，双击安装即可，具体可参考该博客

安装ArcGIS Pro SDK

关闭VS拓展自动更新

首先打开安装好的VS2019，点击“菜单栏-工具-选项”，在选项中找到“环境-拓展”，关闭拓展自动更新，如下图所示。关闭拓展自动更新可以防止拓展自动更新后与当前环境不匹配，如我的环境为ArcGIS Pro2.5，如果不关闭自动更新，则下次打开VS时ArcGIS Pro SDK插件将自动更新为2.6版本，与Pro版本不匹配，无法使用。

正式安装插件

接下来开始安装ArcGIS Pro SDK for .NET，需要点击“菜单栏-拓展-管理拓展”，在弹出的窗口中切换至联机，搜索“ArcGIS Pro”，找到“ArcGIS Pro SDK for .NET”和“ArcGIS Pro SDK for .NET(Utilities)”两个插件，安装并禁用自动更新。点击安装后，重启VS插件即安装完毕，至此，开发环境配置完成。

创建第一个Pro Add-in

使用模板创建Pro Add-in项目

打开VS2019，选择“创建新项目”，将“项目类型筛选”设置为“ArcGIS Pro SDK”，找到“ArcGIS Pro 模块加载项”创建项目即可，注意选择语言为C#而非VB。

添加一个button

Pro的插件及配置使用DAML文件，即项目下的“config.daml”进行声明。

手动添加button

添加button至显示

首先，我们来尝试手动添加一个button。打开“config.daml”文件，在controls标签下添加一个button标签。

    
        Add one button
    
 

添加完button标签后，该控件并不会显示，只有当控件被某个group引用时，才会显示在菜单中，应用方式如下，其中refID为创建button标签时的id。

至此，当Pro加载时即会在“菜单栏-加载项-Group”中显示该控件。修改完成后的“config.daml”文件和Pro中显示效果如下图所示。

为button添加逻辑代码

修改daml后，仅实现了在Pro中显示button，下面来为button添加逻辑代码。

在项目中新建一个类，类名为刚才daml文件中对应button的className属性，并使其继承自Pro SDK中的Button类。然后重写Button的相关方法，如点击时触发的OnClick方法，在其中实现逻辑代码即可，如下图。

自动添加button

在我们熟悉了daml文件之后，日常开发即可直接使用VS提供的快捷添加控件的方式。

在项目上“右击-添加-新建项”，在弹出的窗口左侧选择“ArcGIS Pro Add-ins”中进行筛选后，选择“ArcGIS Pro 按钮”，点击添加，VS即会自动添加一个button类至项目中，在daml文件的controls中添加button定义，并在默认group中引用该button。

生成Addin文件

插件配置完成后，在解决方案上“右键-重新生成解决方案”，待解决方案生成完毕后，在解决方案文件夹\bin\Debug目录下找到*.esriAddinX文件，该文件即为插件安装文件，双击即可为Pro安装该插件。

调试插件

如果不希望直接为Pro安装插件，而是在开发过程中需要测试插件效果，直接按快捷键F5或点击运行，VS将启动Pro，并在Pro中加载修改后的插件，可以在其中对插件进行测试。

开发小tip

1. 当项目是从其他电脑拷贝而来时，引用地址可能不正确，此时，可以在解决方案上右击，找到“修复 Pro 引用”选项，点击后，插件会自动更新引用。若要手动更新引用，dll文件通常存放在Pro安装路径\bin和Pro安装路径\bin\Extensions目录下。
2. 提示"未能解析主引用***，因为它是针对“.NETFramework,Version=v4.8”框架生成的。该框架版本高于当前目标框架"错误信息，则说明生成使用的Framework版本与当前项目应该使用的Framework版本不匹配，在项目上“右击-属性-生成程序”，将“目标框架”切换为当前项目版本即可。
   

DAML配置

DAML是Desktop Application Markup Language的缩写。是ESRI基于XML标准自定义的UI配置文件。插件和配置的声明性部分是在DAML文件中定义的，其中包含了框架元素（主要是插件）的集合，还包括声明性部分(框架所需的信息，以便在适当的时候激活或创建相关的对象）。通过这种方式实现界面和功能的分离。

DAML介绍

具体的DAML介绍请查看DAML ID reference。以下仅介绍常用节点。

根节点

即ArcGIS标签下的节点，大多数情况下无需修改，使用默认即可，常用的有：

1. defaultAssembly：该配置代表的插件所在的程序集名称。
2. defaultNamespace：该配置代表的插件所在的命名空间名称。
   

AddInInfo节点

AddInInfo节点用于声明插件的相关信息，如名称、描述、图标等

modules节点

modules节点是最长访问的节点，插件元素的添加、描述等均在该节点下。modules节点可以包括的元素包括ribbon按钮、工具、画廊、组合框、编辑框、调色板和其他控件，以及应用程序窗格和对接窗格。

Pro 控件级别

Pro的控件级别从上到下分为Module-Tab-Group-Menu-Control，相互关系如下图所示。

1. Tab
2. Group
3. Menu
4. Control

一个原始的DAML文件如下图所示，开发时，先在controls标签下创建所有要使用的控件及其描述，然后在需要显示控件的group标签中引用对应的control即可。

将control在新tab中显示

默认情况下，control将添加至“菜单栏-加载项”中，如果需要在单独的Tab中显示，则需要在daml文件tabs标签下新建tab标签，并在其中添加对需要显示的group的引用，如下图。

常用DAML元素

下面只介绍常用的元素及其属性、方法等，各元素具体使用情景、属性、方法等请参见官方API文档。DAML中通常可以包括controls、categories、dockpanes、groups、menus、minitoolbars、panes、toolbars等等各种元素，具体元素可参见官方DAML ID Reference

控件control

控件常用属性

控件常用方法

控件常见方法有：

1. OnClick()：单击控件时触发

使用时，在控件类中重写对应的方法即可，如：

internal class AddOneButton : ArcGIS.Desktop.Framework.Contracts.Button
{
    protected override void OnClick()
        {
            MessageBox.Show("Hello World");
        }
}

常用控件

1. button
2. comboBox
3. checkBox
4. labelControl
5. tool

停靠窗dockpane

dockpane类为停靠窗口类，其UI由对应的.xaml文件确定，逻辑代码由对应的.cs类文件实现。

双击xaml文件即可进入设计窗口，可以通过拖拽的方式将各种控件添加至dockpane界面中，可以通过可视化或代码方式设置控件和dockpane的各种属性。

功能实现

在Addin中直接打开自建的工具箱

若想要实现，点击插件上的按钮，自动打开对应的自建工具箱或系统工具箱，需要重写按钮的OnClick()方法，在其中使用ArcGIS.Desktop.Core.Geoprocessing.OpenToolDialog(toolPath, param_values)方法打开工具箱，示例如下。若想要不打开工具箱而直接执行工具，则使用ArcGIS.Desktop.Core.Geoprocessing.ExecuteToolAsync(toolPath,param_values)方法异步执行工具。

如果要使用系统工具箱，则直接用工具箱名\工具名调用即可，如 。如需使用自建工具箱，则使用工具箱路径\工具箱名(包括后缀)\工具名调用，如@"E:\ArcGIS\MyProject\sixTool\sixTool.pyt\OpenHDFTool"

此外，不论是打开工具还是执行工具，都必须输入参数，且创建参数时必须至少有一个输入，否则虽然不会抛出语法错误，但是工具不能正常执行，原因未明。

internal class FactorsCorrelationAnalysis : Button
{
    protected override void OnClick()
    {
        //创建工具参数
        //工具必须有参数
        string input_points = "";
        var param_values = Geoprocessing.MakeValueArray(input_points); //创建参数时必须至少有一个输入，否则工具不会正常显示

        //获取sixTools的绝对路径
        string nowPath = System.Windows.Forms.Application.StartupPath; //获取启动程序的可执行文件所在的目录
        string ArcGISPath = System.IO.Directory.GetParent(nowPath).FullName; //获取当前目录的父目录的绝对路径
        string toolRelativePath = @"Resources\ArcToolBox\Scripts\sixTool.pyt\FactorsCorrelationAnalysisTool";
        string toolPath = System.IO.Path.Combine(ArcGISPath, toolRelativePath);
        //MessageBox.Show(toolPath);

        //打开工具箱中的工具
        Geoprocessing.OpenToolDialog(toolPath, param_values);//必须输入工具参数
    }
}

待续

---

本文参考：

1. 博客 https://blog.csdn.net/xiangqiang2015/article/details/81741689
2. 博客 https://blog.csdn.net/DynastyRumble/article/details/104683339
3. Esri官方wiki https://github.com/esri/arcgis-pro-sdk/wiki
4. Pro API reference https://pro.arcgis.com/en/pro-app/sdk/api-reference/index.html#topic10500.html
5. 官方DAML ID Reference https://github.com/Esri/arcgis-pro-sdk/wiki/ArcGIS-Pro-DAML-ID-Reference