Use Local Server

Run local geoprocessing services

Local geoprocessing service instances are created from geoprocessing packages (.gpkx files), authored and packaged using ArcGIS Pro. When packaging a geoprocessing result in ArcGIS Pro for use with local server, use the Package Result geoprocessing tool and ensure the Support ArcGIS Runtime option in the Parameters pane is checked. If this option is unchecked the geoprocessing package will not support creating a local service.

To run a local geoprocessing service, create and start the local service then use the URL property to create a GeoprocessingTask.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// start local geoprocessing service once local server has started
server.addStatusChangedListener(status -> {
  if (status.getNewStatus() == LocalServerStatus.STARTED) {
    try {
      String gpServiceURL = new File("/path/to/file.gpkx").getAbsolutePath();
      // need map server result to add contour lines to map
      localGPService =
        new LocalGeoprocessingService(gpServiceURL);
    } catch (Exception e) {
      e.printStackTrace();
    }

    localGPService.addStatusChangedListener(s -> {
      // create geoprocessing task once local geoprocessing service is started
      if (s.getNewStatus() == LocalServerStatus.STARTED) {
        // add `/Contour` to use contour geoprocessing tool
        GeoprocessingTask gpTask = new GeoprocessingTask(localGPService.getUrl() + "/Contour");
      }
    });
    localGPService.startAsync();
  }
});

Access output data from local geoprocessing services

When running geoprocessing tools in the context of local server, the recommended approach for output data is to write the output data to a specific location on the local file system instead of returning a parameter of type GeoprocessingDataFile and using the GetFileAsync method to return the content via http. You can derive the location in your application code or it can be defined by the script/model using one of the follow approaches:

• Expose an input parameter in the script/model representing the path where the output should be written to the local file system. Your application code should calculate/derive the location and pass that into the task input parameters.

• Calculate/derive a path within the script/model where the output will be written to the local file system and return that as an output parameter in the script/model. The application code would then retrieve the location form the task output parameters.

Create and display local map services

Local map service instances are created from map packages (.mpkx files), authored and packaged using ArcGIS Pro. When packaging a map package in ArcGIS Pro, use the Package Map geoprocessing tool and ensure the Support ArcGIS Runtime option in the Parameters pane is checked. If this option is unchecked the map package will not support creating a local service.

To display a local map service, create and start the local service, then use the URL property to create an ArcGIS map image layer and add to the map.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// start map image service
String mapServiceURL = new File("/path/to/file.mpkx").getAbsolutePath();
LocalMapService mapImageService = new LocalMapService(mapServiceURL);
mapImageService.addStatusChangedListener(status -> {
  // check that the map service has started
  if (status.getNewStatus() == LocalServerStatus.STARTED) {
    // get the url of where map service is located
    String url = mapImageService.getUrl();
    // create a map image layer using url
    ArcGISMapImageLayer imageLayer = new ArcGISMapImageLayer(url);
    // set viewpoint once layer has loaded
    imageLayer.addDoneLoadingListener(() -> {
      if (imageLayer.getLoadStatus() == LoadStatus.LOADED && imageLayer.getFullExtent() != null) {
        mapView.setViewpoint(new Viewpoint(imageLayer.getFullExtent()));
      }
    });
    imageLayer.loadAsync();
    // add image layer to map
    mapView.getMap().getOperationalLayers().add(imageLayer);
  }
});
mapImageService.startAsync();

Create and display local feature services

Local feature service instances are created from map packages (.mpkx files), authored and packaged using ArcGIS Pro. When packaging a map package in ArcGIS Pro, use the Package Map geoprocessing tool and ensure the Support ArcGIS Runtime option in the Parameters pane is checked. If this option is unchecked the map package will not support creating a local service.

To display a local feature service, create and start the local service, then use the URL property to create a feature layer and add to the map or to query the feature service use the URL to create a service feature table.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// start feature service
String featureServiceURL = new File("path/to/file.mpkx").getAbsolutePath();
LocalFeatureService featureService = new LocalFeatureService(featureServiceURL);
featureService.addStatusChangedListener(status -> {
  if (status.getNewStatus() == LocalServerStatus.STARTED) {
    // get the url of where feature service is located
    String url = featureService.getUrl() + "/0";
    // create a feature layer using the url
    ServiceFeatureTable featureTable = new ServiceFeatureTable(url);
    featureTable.loadAsync();
    FeatureLayer featureLayer = new FeatureLayer(featureTable);
    featureLayer.addDoneLoadingListener(() -> {
      if (featureLayer.getLoadStatus() == LoadStatus.LOADED && featureLayer.getFullExtent() != null) {
        mapView.setViewpoint(new Viewpoint(featureLayer.getFullExtent()));
      }
    });
    featureLayer.loadAsync();
    // add feature layer to map
    map.getOperationalLayers().add(featureLayer);


  }
});
featureService.startAsync();

Manage local services

When using the Local Server you are effectively a server administrator. You choose which services to create, determine the server-side properties of the services, and manage the service life cycles. Unlike online services, where all the service parameters are predefined by the service publisher, you must specify the local service settings via the API based on how your application needs to interact with the local service.

The API provides a class to represent each service type, allowing you to set the source content, such as a map or geoprocessing package; set the service properties; and manage the service life cycle by starting and stopping the service as required by your workflow. Services must be set up with the appropriate package type to begin with, and then they can be started. Once the service has started, you can obtain its URL and use it in other API classes such as layers and tasks. For example, you can use the URL of a local map service to create an ArcGISMapImageLayer. If your application no longer requires the service, you can choose to stop specific services via the API, which will allow the system to reclaim any memory used by those services.

When creating local geoprocessing services to run geoprocessing tools and models, you must choose whether the service will run synchronously (SynchronousExecute), asynchronously (AsynchronousSubmit), or asynchronously with a dedicated local map service instance to draw the result (AsynchronousSubmitWithMapServiceResult). Once the service is running, it is not possible to change the execution type. Note that although the terms synchronous and asynchronous are used, these actually refer to the internal infrastructure the Local Server uses to manage these services, and from an API perspective the execution is always asynchronous. The decision is typically based on the type of analysis or processing that will be performed and the result type. If the tool will take less than a few seconds to run, the SynchronousExecute type is recommended. If the tool will take longer and you would like to be able to determine the progress via the API, and perhaps report this to the user, the AsynchronousSubmit type is recommended. In some cases, your analysis might return such a large number of features that it would be inadvisable to obtain the features directly and display them as graphics, and better to instead render them in a result map service. Additionally, raster datasets and raster layers are not directly supported as output data types and instead must be rendered in a result map service. In both these latter cases, you should choose the AsynchronousSubmitWithMapServiceResult execution type.

1
2
3
4
5
// get a url to the local geoprocessing package
String gpServiceURL = new File("path/to/file.gpkx").getAbsolutePath();

// create a local geoprocessing service instance and set the service type to Asynchronous Submit With MapServer Result
localGPService = new LocalGeoprocessingService(gpServiceURL, ServiceType.ASYNCHRONOUS_SUBMIT_WITH_MAP_SERVER_RESULT);

Administer the Local Server instance

LocalServer follows the singleton pattern which means there will be only one instance of LocalServer in your application. Use the LocalServer static property Instance to set instance-wide properties, such as the AppDataPath where geoprocessing and map packages will be extracted, or to access the collection of local services. Starting local services will automatically start the local server instance. Alternatively, for fine-grained control you can explcitly start the local server instance, for example to validate the license and installation before creating any local services.

Debug information for Local Server

There are times when you would like access to additional debug information on services running in the Local Server and on the interaction between the API and the local service, just as you might do with remote services. The ArcGIS Runtime API and Local Server SDK provide facilities for debugging. These are disabled by default. It is important to note the distinction between the Local Server instance within the SDK installation on your development machine and the Local Server deployment you create for your application. The SDK installation includes all components, including several features that can help you debug local services whereas a deployed instance of the Local Server will have debugging options disabled by default to minimize the disk footprint and to ensure the security of the Local Server.

Debug settings are administered via the Local Server Utility application. This is automatically included in the SDK installation of the Local Server but must be explicitly included in a deployment when specifying options in the configuration manifest file. The Local Server Utility provides you with the ability to control how applications work with the Local Server. You can choose to enable HTTP traffic to be viewed in a network monitoring tool, select the default port range to avoid conflicts with other applications, select the log level, and provide error reports.

The Local Server Utility can be accessed from the Windows Start menu or can be located in the Local Server SDK installation folder, for example C:\Program Files\ArcGIS SDKs\LocalServer100.10\64\bin\LocalServerUtility.exe.

Local Server REST Services Directory

Local Server provides a services directory like the ArcGIS REST API Services Directory available with ArcGIS Enterprise and ArcGIS Online. It allows you to browse the service metadata of local services runing on the Local Server instance and obtain information that can be useful when developing applications. The Services Directory is a view of the Local Server REST API in HTML format. You can use this to discover how to write code to run your services.

The services directory can be accessed via the Local Server URL. The Local Server instance in the SDK installation includes the HTML server pages by default, while a deployment of the Local Server does not. This setting is controlled via the Local Server Utility setting Generate HTML Server Pages checkbox. Another setting in the Local Server Utility that determines how you work with the services directory is the Add Random Prefix to Server URLs option. If disabled, the Local Server will have a consistent URL each time it is started by your application, making it easier for you to work with the services directory between debugging sessions. Although local services cannot be accessed outside the local machine by any other user or application, the random prefix is enabled by default to provide additional security from applications running on the local machine.

Supported raster formats

Local Server supports the raster file formats supported by ArcGIS Pro.

Next steps

• Introduction

  Learn about Local Server.

• Install and set up

  Install and setup the Local Server SDK.

• Create geoprocessing and map packages

  Create .gpkx and .mpkx files for use with Local Server.

• Use Local Server

  Learn how to use Local Server services.

• Supported geoprocessing tools

  Check the tools you need are supported.