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 Geoprocessing.
// Create a local geoprocessing service from a geoprocessing package using a path relative to your application executable.
LocalGeoprocessingService localgeoprocessingService = new LocalGeoprocessingService(@"..\Data\MessageInABottle.gpkx");
try
{
// Start the local service.
await localgeoprocessingService.StartAsync();
}
catch (InvalidOperationException invalidOpEx)
{
Console.WriteLine("LocalService is already in Started state");
}
catch (LocalServerException localServerEx)
{
Console.WriteLine("deployment license level does not meet minimum required");
}
catch (Exception ex)
{
Console.WriteLine("error encountered starting service");
}
// If the service did not start handle error and return.
if (localgeoprocessingService.Error != null || localgeoprocessingService.Status != LocalServerStatus.Started)
{
Console.WriteLine("Unable to start Local Server");
return;
}
// Get the URL for the specific geoprocessing task endpoint.
string geoprocessingTaskUrl = localgeoprocessingService.Url + "/MessageInABottle";
// Create the geoprocessing task with the URL.
GeoprocessingTask messageInBottleTask = await GeoprocessingTask.CreateAsync(new Uri(geoprocessingTaskUrl));
// Create parameters, run Jobs, process results.
// ...
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.
// Create a local map service from a map package on disk.
LocalMapService pointsOfInterestMapService = new LocalMapService(@"..\Data\PointsofInterest.mpkx");
try
{
// Start the local service.
await pointsOfInterestMapService.StartAsync();
}
catch (InvalidOperationException invalidOpEx)
{
Console.WriteLine("LocalService is already in Started state");
}
catch (LocalServerException localServerEx)
{
Console.WriteLine("deployment license level does not meet minimum required");
}
catch (Exception ex)
{
Console.WriteLine("error encountered starting service");
}
// If the service did not start handle error and return.
if (pointsOfInterestMapService.Error != null || pointsOfInterestMapService.Status != LocalServerStatus.Started)
{
Console.WriteLine("Unable to start Local Server");
return;
}
// Create a new ArcGISMapImageLayer.
ArcGISMapImageLayer pointsOfInterestmapImageLayer = new ArcGISMapImageLayer(pointsOfInterestMapService.Url);
// Add the layer to the map.
map.OperationalLayers.Add(pointsOfInterestmapImageLayer);
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.
// Create a local feature service from a map package on disk
LocalFeatureService pointsOfInterestFeatureService = new LocalFeatureService(@"..\Data\PointsofInterest.mpkx");
try
{
// Start the local service.
await pointsOfInterestFeatureService.StartAsync();
}
catch (InvalidOperationException invalidOpEx)
{
Console.WriteLine("LocalService is already in Started state");
}
catch (LocalServerException localServerEx)
{
Console.WriteLine("deployment license level does not meet minimum required");
}
catch (Exception ex)
{
Console.WriteLine("error encountered starting service");
}
// If the service did not start handle error and return.
if (pointsOfInterestFeatureService.Status != LocalServerStatus.Started)
{
Console.WriteLine("Unable to start Local Server");
return;
}
// Create a new service feature table from the feature service endpoint with layer index 0.
ServiceFeatureTable pointsOfInterestTable = new ServiceFeatureTable(new Uri(pointsOfInterestFeatureService.Url + "/0"));
// Create a new feature layer to display the features in the table.
FeatureLayer pointsOfInterestFeatureLayer = new FeatureLayer(pointsOfInterestTable);
// Add the layer to the map.
map.OperationalLayers.Add(pointsOfInterestFeatureLayer);
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 ArcGIS. 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 (Synchronous), asynchronously (Asynchronous), or asynchronously with a dedicated local map service instance to draw the result (Asynchronous). 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 Synchronous 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 Asynchronous 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 Asynchronous execution type.
// Create LocalGeoprocessingService and set service properties.
LocalGeoprocessingService messageInABottleGeoprocessingService = new LocalGeoprocessingService(@"..\Data\MessageInABottle.gpkx")
{
// Properties such as ServiceType and MaxRecords must be set before local services are started.
ServiceType = GeoprocessingServiceType.SynchronousExecute,
MaxRecords = 10000
};
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 App 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.
private async Task StartLocalServer()
{
try
{
// Start the Local Server instance (Esri.ArcGISRuntime.LocalServices.LocalServer)
await LocalServer.Instance.StartAsync();
}
catch (InvalidOperationException invalidOpEx)
{
Console.WriteLine("Local Server installation is invalid or LocalServer is already in Started state");
}
catch (DirectoryNotFoundException dirNotFoundEx)
{
Console.WriteLine("folder locations for AppDataPath or TempPath do not exist");
}
catch (LocalServerException localServerEx)
{
Console.WriteLine("deployment license level does not meet minimum required");
}
catch (Exception ex)
{
Console.WriteLine("Error starting service");
}
if (LocalServer.Instance.Error != null || LocalServer.Instance.Status != LocalServerStatus.Started)
{
Console.WriteLine("Unable to start Local Server");
return;
}
// Continue on to create local services...
}
When an application is closed the Local Server will automatically shutdown. You can also control this shutdown explicitly by calling StopAsync, for example if you want to stop the Local Server while your application continues running.
private async Task StopLocalServer()
{
try
{
// Stop the Local Server instance (Esri.ArcGISRuntime.LocalServices.LocalServer).
await LocalServer.Instance.StopAsync();
}
catch (InvalidOperationException invalidOpEx)
{
Console.WriteLine("LocalServer is already in the Stopped state");
}
catch (Exception ex)
{
Console.WriteLine("Error when starting Local Server");
}
}
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. This API and the 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 that can be found in C (where x is the current release number).
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.