ArcGIS Engine環境下創建自定義的ArcToolbox Geoprocessing工具

      在上一篇日志中介紹了自己通過幾何的方法合並斷開的線要素的ArcGIS插件式的應用程序。但是后來考慮到插件式的程序的配置和使用比較繁瑣，也沒有比較好的錯誤處理機制，於是我就把之前的程序封裝成一個類似於ArcGIS中ArcToolBox中的批處理工具一樣的程序，有輸入文件的選擇和輸出文件的選擇，類似於下面這個工具界面：

 

     首先是查了一下ESRI的幫助文檔ArcObjects Help for .NET，上面有關於如何創建自定義的Geoprocessing工具的幾篇文章，介紹的不是很全面，但是可以知道創建工具的基本步驟和流程以及如何調試。下面創建自定義工具的基本步驟：

Creating a custom geoprocessing function tool 

There are, of course, scenarios for which you must create your own tool using ArcObjects. This requires implementing the IGPFunction2 and IGPFunctionFactory interfaces. The  Building a custom geoprocessing function tool topic provides detailed information and examples. The following steps summarize the process:

1. In a .NET application, create two classes (one will implement IGPFunction2 and the other will implement IGPFunctionFactory). You can create two separate files or keep them in a single file.
2. Set the parameter properties (parameter type, direction, and acceptable values) in the ParameterInfo property of IGPFunction2.
3. Leave the Validation method of IGPFunction2 as an empty stub—the geoprocessing framework automatically performs the validation.
4. The Execute method of IGPFunction is the most important part of your tool. This is where you write your code to implement the specific algorithm.
5. Implement IGPFunctionFactory. This makes your custom function tool accessible to users.

     第一步需要創建兩個類，分別實現IGPFunction2 和IGPFunctionFactory接口。在實現IGPFunction2 接口的類中定義Tool的目錄、名稱、輸入參數、輸出參數、進度條和Execute函數等參數。需要注意的是如果您的工具是有Output FeatureClass，那就需要在除了IArray ParameterInfo中設置輸入、輸出參數以外，還需在Execute函數中創建新的要素類作為輸出要素類，並為其配置幾何信息和字段信息：

parameter = (IGPParameter)paramvalues.get_Element(1);
            parameterValue = m_GPUtilities.UnpackGPValue(parameter);
            Geoprocessor gp = new Geoprocessor();
            // Create the new Output Polyline Feature Class
            CreateFeatureclass cfc = new CreateFeatureclass();       
    
            //根據用戶在output featureclass中命名的name創建新的輸出要素
            IName name = m_GPUtilities.CreateFeatureClassName(parameterValue.GetAsText());
            IDatasetName dsName = name as IDatasetName;
            IFeatureClassName fcName = dsName as IFeatureClassName;
            IFeatureDatasetName fdsName = fcName.FeatureDatasetName as IFeatureDatasetName;

            // Check if output is in a FeatureDataset or not. Set the output path parameter for CreateFeatureClass tool.
            if (fdsName != null)
            {
                cfc.out_path = fdsName;
            }
            else
            {
                cfc.out_path = dsName.WorkspaceName.PathName;
            }
            // Set the output Coordinate System for CreateFeatureClass tool.
            IGPEnvironment env = envMgr.FindEnvironment("outputCoordinateSystem");
            // Same as Input
            if (env.Value.IsEmpty())
            {
                //IGeoDataset ds = inputFeatureClass as IGeoDataset;
                //cfc.spatial_reference = ds.SpatialReference as ISpatialReference3;
            }
            // Use the evnviroment setting
            else
            {
                IGPCoordinateSystem cs = env.Value as IGPCoordinateSystem;
                cfc.spatial_reference = cs.SpatialReference as ISpatialReference3;
            }
            // Remaing properties for Create Feature Class Tool
            cfc.out_name = dsName.Name;
            cfc.geometry_type = "POLYLINE";
            gp.Execute(cfc, null);

      在配置好輸入輸出參數信息后，就可在Execute（）函數中加上您自己的ArcEngine程序了，如果是WinForm或者ArcGIS插件式的AE程序，只需要修改參數，使程序的輸入參數讀取到的是在Tool中輸入的input featureclass，輸出參數是Tool中的output featureclass就可以了，最后程序的處理結果過自動加載到Arcmap地圖窗口中進行顯示。

      在程序寫完后，需要進行調試。這里進行調試和一般的ArcEngine程序不同，程序運行時不會直接命中VS中設置的斷點，需要進行相關的配置才能進行正常的調試。在ESRI的幫助文檔中有詳細的介紹：

How to debug a function tool running in the background

Summary

This topic shows how to debug a function tool in Visual Studio in a background geoprocessing environment.

Debugging a function tool in background processing

When geoprocessing tools are run in ArcGIS applications, the user has the option to run them in a background process (personal server) instead of running them in ArcMap. For more information, see  Foreground and background processing in the ArcGIS Desktop Help system.

When debugging a tool, attaching Visual Studio to the application (for example, ArcMap) will not trigger execution and validation break points since the code is not running in the application.

To debug tools, you can disable background processing or attach your debugger to the background process. To disable background processing, select Options under the application's Geoprocessing menu and clear the Run in background check box.

Debugging in the background

Complete the following steps to debug the tool in a background process:

1. Start Visual Studio and open your tool project.
2. When you run or build the .NET solution, it creates a dynamic-link library (DLL) that must be registered by the ESRIRegAsm utility. You can add a post-build command to automate the registration process. In the Project properties Build Events section, type the command on the post-build event command line. The following is one example of a post-build command to register with ArcGIS Engine:

"$(ProgramFiles)\Common Files\ArcGIS\bin\esriRegAsm.exe" $(TargetPath) /p:Engine /v:10.1 /s 

If debugging on ArcGIS for Desktop then set product to Desktop as /p:Desktop instead of /p:Engine

3. Also, in the Project properties Debug section, set ArcMap in the Start external program option by browsing to the ArcMap.exe location. The default location is <Install Directory>\bin\ArcMap.exe.
4. Set a breakpoint as necessary for debugging.
5. Click Debug and click Start Debugging (or press F5) to run the project. The ArcMap application starts.
6. From the ArcMap menu, click Geoprocessing > Geoprocessing Options. Confirm that Enabled is checked to ensure that background processing is enabled if you want to debug in the background, then click OK on the dialog box. This starts the background processes (if not already started).
7. In Visual Studio, click Tools, then click Attach to Process. See the following screen shot:
   
8. When you click Attach to Process, the Attach to Process dialog box appears. Under the Available Processes section, there will be two of the background processes (RuntimeLocalServer.exe). Select both of the processes and click Attach. See the following screen shot:
   
   
   
   
9. In ArcMap, right-click the toolbox and select Add, then click Tool to add the function tool to a custom toolbox. The Add Tool dialog box appears. On the Add Tool dialog box, you can see your function tool under a toolbox named after the category you set in your code. See the following screen shot:
   
10. Add the data to ArcMap (if not already added), and run your tool after populating the parameters.
11. At the appropriate execution point, the debugging stops at the breakpoint.

      按照以上步驟，附加上進程並注冊了工具后，就可以設置斷點進行調試了。不過需要注意的是這種進行調試的方法不太穩定——在完成一次調試后，重新打開VS運行程序后，在附加進程的對話框中再也找不到RuntimelocalServer.exe的兩個進程，沒有辦法繼續進行調試。剛開始自己也沒有很好的解決辦法，后來打電話到ESRI技術支持中心，他們那邊的工程師在自己的電腦上調試這類程序也是這種情況說是一個bug，也沒有很好的解決辦法，只是說讓我在winForm中把程序調通再改。后來就是嘗試各種方法，一次在程序運行中嘗試附加進程，結果終於看到了RuntimelocalServer.exe！！！

      也就是說，遇到程序剛開始不能附加指定進程的情況，可以在已經在程序執行對話框這中配置好輸入、輸出參數后（程序已經在執行Execute()函數），再次在VS工具選項中嘗試附加該進程，這時候就會正常命中斷點！

      最后程序調通后，就是Tool的注冊和調用了。Tool的注冊有兩種方法，第一種是在VS中執行程序，Tool會自動注冊到ArcGIS Desktop中；另一種方式是在程序編譯后在程序目錄的Debug文件夾找到.dll動態鏈接庫文件，然后雙擊該文件，選擇Desktop完成Tool在ArcGIS上的注冊。

    然后在ArcCatalog的自定義工具箱中找到Tool目錄和對應工具，雙擊工具即可運行程序。我的Merge Disconnect Line工具運行后的參數配置界面如下：

 在配置好輸入參數和輸出參數后，點擊OK執行程序。

------------------------------------------------------------------------------------------------------------------------

本程序的主要代碼：

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;
using System.Windows.Forms;
using ESRI.ArcGIS.ADF.CATIDs;
using ESRI.ArcGIS.DataManagementTools;
using ESRI.ArcGIS.esriSystem;
using ESRI.ArcGIS.Geodatabase;
using ESRI.ArcGIS.Geometry;
using ESRI.ArcGIS.Geoprocessing;
using ESRI.ArcGIS.Geoprocessor;

namespace GPMergeDisconnectLine
{     
    /************************************************************************************************/
    //定義GP工具
    public class MergeDisjunctLineFunction : IGPFunction
    {
        //工具的名稱
        private string m_ToolName = "MergeDisconnectLine";
        private string m_metadatafile = "MergeDisconnectLine.xml";
        private IArray m_Parameters;             // Array of Parameters
        private IGPUtilities m_GPUtilities;      

        public MergeDisjunctLineFunction()
        {
            m_GPUtilities = new GPUtilitiesClass();
        }

        public string Name
        {
            get { return m_ToolName; }
        }

        // Set the function tool Display Name as seen in ArcToolbox.
        public string DisplayName
        {
            get { return "Merge Disconnect Line"; }
        }

        public void Execute(IArray paramvalues, ITrackCancel trackcancel, IGPEnvironmentManager envMgr, IGPMessages message)
        {
            //輸入參數
            IGPParameter parameter = (IGPParameter)paramvalues.get_Element(0);
            IGPValue parameterValue = m_GPUtilities.UnpackGPValue(parameter);
            // Open Input Dataset
            IFeatureClass inputFeatureClass = null;
            IQueryFilter qf = null;
            IGPRecordSet gprs = null;
            IRecordSet2 rs2 = null;

            IFeatureClass outputFeatureClass = null;
            int sumCount = 0;
            if (parameterValue.DataType is IDEGeoDatasetType)
            {
                m_GPUtilities.DecodeFeatureLayer(parameterValue, out inputFeatureClass, out qf);
                if (inputFeatureClass == null)
                {
                    message.AddError(2, "Could not open input dataset.");
                    return;
                }
                sumCount = inputFeatureClass.FeatureCount(null);
            }
            else if (parameterValue.DataType is IGPFeatureRecordSetLayerType)
            {
                gprs = parameterValue as IGPRecordSet;
                rs2 = gprs.RecordSet as IRecordSet2;
                //SearchCursor = rs2.get_Cursor(false);
                sumCount = rs2.Table.RowCount(null);
            }

            /*Create FeatureClass  輸出參數！！！*/
            parameter = (IGPParameter)paramvalues.get_Element(1);
            parameterValue = m_GPUtilities.UnpackGPValue(parameter);
            Geoprocessor gp = new Geoprocessor();
            // Create the new Output Polyline Feature Class
            CreateFeatureclass cfc = new CreateFeatureclass();       
    
            //根據用戶在output featureclass中命名的name創建新的輸出要素
            IName name = m_GPUtilities.CreateFeatureClassName(parameterValue.GetAsText());
            IDatasetName dsName = name as IDatasetName;
            IFeatureClassName fcName = dsName as IFeatureClassName;
            IFeatureDatasetName fdsName = fcName.FeatureDatasetName as IFeatureDatasetName;

            // Check if output is in a FeatureDataset or not. Set the output path parameter for CreateFeatureClass tool.
            if (fdsName != null)
            {
                cfc.out_path = fdsName;
            }
            else
            {
                cfc.out_path = dsName.WorkspaceName.PathName;
            }
            // Set the output Coordinate System for CreateFeatureClass tool.
            IGPEnvironment env = envMgr.FindEnvironment("outputCoordinateSystem");
            // Same as Input
            if (env.Value.IsEmpty())
            {
                //IGeoDataset ds = inputFeatureClass as IGeoDataset;
                //cfc.spatial_reference = ds.SpatialReference as ISpatialReference3;
            }
            // Use the evnviroment setting
            else
            {
                IGPCoordinateSystem cs = env.Value as IGPCoordinateSystem;
                cfc.spatial_reference = cs.SpatialReference as ISpatialReference3;
            }
            // Remaing properties for Create Feature Class Tool
            cfc.out_name = dsName.Name;
            cfc.geometry_type = "POLYLINE";
            gp.Execute(cfc, null);

            outputFeatureClass = m_GPUtilities.OpenFeatureClassFromString(parameterValue.GetAsText());
            //Set the properties of the Step Progressor
            IStepProgressor pStepPro = (IStepProgressor)trackcancel;
            pStepPro.MinRange = 0;
            pStepPro.MaxRange = 6;
            pStepPro.StepValue = (1);
            pStepPro.Message = "Merge disjunct polyline is in processing";
            pStepPro.Position = 0;
            pStepPro.Show();

            //合並操作開始
            MergeOperation mOpetation = new MergeOperation();
            pStepPro.Step();
            List<IFeature> allPolylineList = mOpetation.getAllPolyline(inputFeatureClass);
            pStepPro.Step();
            List<IPoint> allNodePointList = mOpetation.GetNodePtsListByLine(allPolylineList);
            pStepPro.Step();
            List<IPoint> distinctNodePointList = mOpetation.GetDistinctNodePtsList(allNodePointList);
            pStepPro.Step();
            List<IFeature> unionLineList = mOpetation.MergeLineListOperate(allPolylineList, distinctNodePointList, inputFeatureClass);
            pStepPro.Step();
            mOpetation.AddField(inputFeatureClass, outputFeatureClass);
            pStepPro.Step();
            mOpetation.WriteUnionLineToFile(unionLineList, outputFeatureClass);
            pStepPro.Step();
            System.Runtime.InteropServices.Marshal.ReleaseComObject(outputFeatureClass);
            //合並操作結束
            pStepPro.Hide();
        }

        // This is the location where the parameters to the Function Tool are defined. 
        // This property returns an IArray of parameter objects (IGPParameter). 
        // These objects define the characteristics of the input and output parameters. 
        public IArray ParameterInfo
        {                 
            get 
            {
                //Array to the hold the parameters    
                IArray parameters = new ArrayClass();

                IGPParameterEdit3 inputParameter = new GPParameterClass();
                inputParameter.DataType = new GPFeatureLayerTypeClass();
                inputParameter.Value = new GPFeatureLayerClass();

                // Set Input Parameter properties
                inputParameter.Direction = esriGPParameterDirection.esriGPParameterDirectionInput;
                inputParameter.DisplayName = "Input Features";
                inputParameter.Name = "input_features";
                inputParameter.ParameterType = esriGPParameterType.esriGPParameterTypeRequired;
                parameters.Add(inputParameter);

                // Output parameter (Derived) and data type is DEFeatureClass
                IGPParameterEdit3 outputParameter = new GPParameterClass();
                outputParameter.DataType = new DEFeatureClassTypeClass();

                // Value object is DEFeatureClass
                outputParameter.Value = new DEFeatureClassClass();

                // Set output parameter properties
                outputParameter.Direction = esriGPParameterDirection.esriGPParameterDirectionOutput;
                outputParameter.DisplayName = "Output FeatureClass";
                outputParameter.Name = "out_featureclass";
                outputParameter.ParameterType = esriGPParameterType.esriGPParameterTypeRequired;

                // Create a new schema object - schema means the structure or design of the feature class (field information, geometry information, extent)
                IGPFeatureSchema outputSchema = new GPFeatureSchemaClass();
                IGPSchema schema = (IGPSchema)outputSchema;

                // Clone the schema from the dependency. 
                //This means update the output with the same schema as the input feature class (the dependency).                                
                schema.CloneDependency = true;

                // Set the schema on the output because this tool will add an additional field.
                outputParameter.Schema = outputSchema as IGPSchema;
                outputParameter.AddDependency("input_features");
                parameters.Add(outputParameter);

                return parameters;
            }
        }

        //驗證合法性
        public IGPMessages Validate(IArray paramvalues, bool updateValues, IGPEnvironmentManager envMgr)
        {
            if (m_Parameters == null)
                m_Parameters = ParameterInfo;
            if (updateValues)
            {
                //UpdateParameters(paramvalues, envMgr);
            }
            //// Call InternalValidate (Basic Validation). Are all the required parameters supplied?
            //// Are the Values to the parameters the correct data type?
            IGPMessages validateMsgs = m_GPUtilities.InternalValidate(m_Parameters, paramvalues, updateValues, true, envMgr);
            
            //UpdateMessages(paramvalues, envMgr, validateMsgs);
            return validateMsgs;
        }

        //更新參數，有些工具需要設置好一個參數后，才能設置下一個參數，例如需要選擇一個矢量數據之后，
        //才能選擇數據中的字段，這樣的工作可在該代碼中定義，如何定義還需要查看幫助和示例  
        public void UpdateParameters(IArray paramvalues, IGPEnvironmentManager pEnvMgr)
        {
            //m_Parameters = paramvalues;
            // Retrieve the input parameter value
            //IGPValue parameterValue = m_GPUtilities.UnpackGPValue(m_Parameters.get_Element(0));
        }

        
        // This is the function name object for the Geoprocessing Function Tool. 
        // This name object is created and returned by the Function Factory.
        // The Function Factory must first be created before implementing this property.
        public IName FullName
        {
            get
            {     
                IGPFunctionFactory functionFactory = new MergeDisjunctLineFactory();
                return (IName)functionFactory.GetFunctionName(m_ToolName);
            }
        }

        // This is used to set a custom renderer for the output of the Function Tool.
        public object GetRenderer(IGPParameter pParam)
        {
            return null;
        }

        //幫助的上下文標識 返回0即可 
        public int HelpContext
        {
            get { return 0; }
        }

        // This is the path to a .chm file which is used to describe and explain the function and its operation. 
        public string HelpFile
        {
            get { return ""; }
        }

        // This is used to return whether the function tool is licensed to execute.
        public bool IsLicensed()
        {
            IAoInitialize aoi = new AoInitializeClass();
            ILicenseInformation licInfo = (ILicenseInformation)aoi;
            string licName = licInfo.GetLicenseProductName(aoi.InitializedProduct());
            if (licName == "Advanced")
            {
                return true;
            }
            else
            {
                return false;
            }           
        }

        //元數據文件 這個返回空字符串也可以 
        public string MetadataFile
        {
            get
            {
                string filePath;
                filePath = System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().Location);
                filePath = System.IO.Path.Combine(filePath, m_metadatafile);
                return filePath;
            }
        }

        public UID DialogCLSID
        {
            // DO NOT USE. INTERNAL USE ONLY.
            get { return null; }
        }
    }


    /*IGPFunctionFactory*************************************************************************************************/

    [Guid("526de91e-3fe5-4a46-a7e2-4d1dc3cdb5db"), ComVisible(true)]

    public class MergeDisjunctLineFactory : IGPFunctionFactory
    {
        // Register the Function Factory with the ESRI Geoprocessor Function Factory Component Category.

        #region "Component Category Registration"

        [ComRegisterFunction()]
        private static void Reg(string regKey)
        {
            GPFunctionFactories.Register(regKey);
        }

        [ComUnregisterFunction()]
        private static void Unreg(string regKey)
        {
            GPFunctionFactories.Unregister(regKey);
        }

        #endregion

        // Utility Function added to create the function names.
        private IGPFunctionName CreateGPFunctionNames(long index)
        {
            IGPFunctionName functionName = new GPFunctionNameClass();
            functionName.MinimumProduct = esriProductCode.esriProductCodeAdvanced;
            IGPName name;

            switch (index)
            {
                    //工具箱中只有一個工具
                case (0):
                    name = (IGPName) functionName;
                    name.Category = "DisconnectlineMerge";
                    name.Description = "Merge a disconnect line list to a continuous line";
                    name.DisplayName = "Merge Disconnectline";
                    name.Name = "MergeDisconnectLine";
                    name.Factory = (IGPFunctionFactory) this;
                    break;
            }

            return functionName;
        }

        // Implementation of the Function Factory
        // This is the name of the function factory. 
        // This is used when generating the Toolbox containing the function tools of the factory.
        public string Name
        {
            get { return "DisconnectlineMerge"; }
        }

        // This is the alias name of the factory.
        public string Alias
        {
            get { return "lineMerge"; }
        }

        // This is the class id of the factory. 
        public UID CLSID
        {
            get
            {
                UID id = new UIDClass();
                id.Value = this.GetType().GUID.ToString("B");
                return id;
            }
        }

        // This method will create and return a function object based upon the input name.
        public IGPFunction GetFunction(string Name)
        {
            switch (Name)
            {
                case ("MergeDisconnectLine"):
                    IGPFunction gpFunction = new MergeDisjunctLineFunction();
                    return gpFunction;
            }

            return null;
        }

        // This method will create and return a function name object based upon the input name.
        public IGPName GetFunctionName(string Name)
        {
            IGPName gpName = new GPFunctionNameClass();

            switch (Name)
            {
                case ("MergeDisconnectLine"):
                    return (IGPName) CreateGPFunctionNames(0);

            }
            return null;
        }

        // This method will create and return an enumeration of function names that the factory supports.
        public IEnumGPName GetFunctionNames()
        {
            IArray nameArray = new EnumGPNameClass();
            nameArray.Add(CreateGPFunctionNames(0));
            return (IEnumGPName) nameArray;
        }

        public IEnumGPEnvironment GetFunctionEnvironments()
        {
            return null;
        }
    }
}

 本文是自己這幾天做ArcGIS GP工具的一些心得體會，部分參考ESRI開發者中心文檔。文章和代碼如有不足之處，請和我聯系，感謝！（郵箱：[e-mail]）

-----------------------------------------------------------------------------------------------------

 本文系作者GISQZC原創文章，歡迎轉載，但必須注明出處，否則將追究相關法律責任！