Skip To Content

Using ArcGIS Earth Automation API

Administrator configuration

As an administrator, you can configure ArcGIS Earth Automation API using the ArcGISEarth.WCFNamedPipeIPC.json configuration file in the ArcGIS Earth installation directory, which is typically in the C:\Program Files\ArcGIS\Earth\bin\plugins folder.

The autoStart function automatically enables ArcGIS Earth Automation API when ArcGIS Earth starts. The default is false. When autoStart=true, ArcGIS Earth can host the WCF service on your local machine at startup. Check the ArcGIS Earth Automation API status from the Advanced application settings.

Connecting to ArcGIS Earth

Establishing connections

ArcGIS Earth Automation API implements the WCF named pipe transport mechanism for interprocess communication (IPC) on-machine usage. Once the connection is established, the client app can start communication with ArcGIS Earth.

To work with ArcGIS Earth Automation API, you need a specific endpoint address for sending requests. The endpoint address for ArcGIS Earth Automation API is defined as net.tcp//localhost/arcgisearth.

Complete the following steps to set up connections for your app, or visit ArcGIS Earth Automation API GitHub for more details.

  1. Copy the following code to create a contract file, or download the ready-to-use ArcGIS Earth Automation API contract file sample IEarthNamedpipeService.cs from GitHub.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;
    using System.ServiceModel;
    using System.Runtime.Serialization;
    
    namespace ArcGISEarth.WCFNamedPipeIPC
    {
    
        [DataContract]
        public class EarthNamedpipeFault
        {
    
            public string Message { get; set; }
        }
    
        [ServiceContract(Namespace = "ArcGISEarth/2018/07")]
        public interface IEarthNamedpipeService
        {
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            string GetCameraJson();
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            bool SetCamera(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            bool FlyTo(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            string AddLayer(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            string GetLayerLoadStatus(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            void RemoveLayer(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            string GetWorkspace();
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            void ImportWorkspace(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            bool ClearLayers(string json);
    
            [FaultContract(typeof(EarthNamedpipeFault))]
            [OperationContract]
            Task<System.Drawing.Bitmap> GetSnapshotAsync();
        }
    }

  2. Add the following references to your program:

    System.Drawing
    System.Runtime.Serialization
    System.ServiceModel

  3. Call to connect with ArcGIS Earth, as shown in the following code:
    // Create binding
    int MaxBuffer = 2147483647;
    NetNamedPipeBinding binding = new NetNamedPipeBinding(NetNamedPipeSecurityMode.None);
    binding.MaxBufferPoolSize = MaxBuffer;
    binding.MaxBufferSize = MaxBuffer;
    binding.MaxReceivedMessageSize = MaxBuffer;
    
    // Create endpoint
    // Note, the address is "net.tcp//localhost/arcgisearth" by default
    string address = "net.tcp//localhost/arcgisearth";
    ServiceEndpoint se = new ServiceEndpoint(
    	ContractDescription.GetContract(typeof(IEarthNamedpipeService)),
        binding,
        new EndpointAddress(address));
    
    _factory = new ChannelFactory<IEarthNamedpipeService>(se);
    IEarthNamedpipeService channel = _factory.CreateChannel();
    
    // Get JSON description
    string cameraJson = channel.GetCameraJson();

Handling exceptions

ArcGIS Earth Automation API uses EarthNamedpipeFault to return an exception, as shown in the following code. Its Message property has details.

try
{
    if (_channel.ClearLayers(json))
    {
        return cSuccess;
    }
}
catch (FaultException<EarthNamedpipeFault> ex)
{
    return ex.Message;
}