Work with local services
In this topic
ArcGIS Runtime provides two primary patterns for offline workflows: the services pattern and the desktop pattern described in Create an offline map.
The pattern names represent the source of the content used within your ArcGIS Runtime based app, with the services pattern involving requesting content from published GIS services and the desktop pattern involving the creation of ArcGIS Runtime content from ArcGIS for Desktop. Your solution may combine both workflows depending on the type of content and connectivity scenarios your app supports.
A third pattern, available with ArcGIS Runtime for .NET (Windows Desktop) and referred to as the Local Server pattern, involves some aspects of both primary patterns. When using this pattern, you work with the Local Server. The Local Server is effectively a miniserver for serving up local services that do not require an Internet connection. The content for the Local Server pattern is created from ArcGIS for Desktop in the form of map packages and geoprocessing packages. One key feature of using this pattern is the ability to run offline geoprocessing completely on the device itself, without access to the Internet.
Available local services are local map services, local feature services, and local geoprocessing services. Local map services and local feature services are started from map packages (.mpk files). Local geoprocessing services are started from geoprocessing packages (.gpk files).
Map packages (.mpk) contain a representation of the original map document on which the local map service will be based. Map packages are read-only and cannot persist changes to the map. However, it is possible to make edits to the feature data referenced by map packages. For guidance on editing workflows, refer to Editing.
When sharing maps as map packages, you must choose whether the datasets are included within the map package or if the layers reference those datasets externally to the package, which might be as files on disk or in an enterprise geodatabase. This choice has a significant effect on the size of the map package and should be based on the workflows your app supports. If your app is intended only for viewing map data, you should choose to include the data within the package. If the users of your app do need to make edits to feature data in the map, you should choose to have the map package reference the data externally. It is important to note that map package layers reference their datasets via absolute paths and that only file geodatabases (.gdb) or enterprise geodatabases can be edited via the Local Server. Therefore, when creating map packages that reference the data, ensure the path by which the layer references the data on the map authoring machine will be the same as the path on the deployment machine. Your application deployment workflow will need to account for deploying the file geodatabase to be edited onto the deployment machine and retrieving the dataset once the editing activity is complete.
Geoprocessing packages (.gpk) are created from the result of a tool or model successfully executed in ArcGIS for Desktop, and they contain all the information required to execute the tool when running in the local service hosted by the Local Server. This includes validated input and output data plus any intermediate data used within the model. The Local Server supports a subset of the geoprocessing tools available with ArcGIS for Desktop or ArcGIS for Server, as listed in Supported geoprocessing tools. Additionally, only a subset of the input and output data types available in ArcGIS for Desktop are supported.
To learn more about packages used by ArcGIS Runtime, see Packages used by ArcGIS Runtime.
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 app 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, it provides a Url property through which other API classes such as layers and tasks interact with the local service. The Url property of the local service can be used as the Url for an ArcGISDynamicMapServiceLayer, a ServiceFeatureTable, or a Geoprocessor task. If your app 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 (Execute), asynchronously (SubmitJob), or asynchronously with a dedicated local map service instance to draw the result (SubmitJobWithMapServerResult). 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 asychronous. 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 Execute 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 SubmitJob 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 SubmitJobWithMapServerResult execution type.
The following code sample shows how to start a local geoprocessing service programmatically.
//LocalGeoprocessingServices are started from Geoprocessing packages (.Gpk files).
//Settings such as ServiceType and max records need to be set on the service before it starts.
= new LocalGeoprocessingService(GPK_PATH, GeoprocessingServiceType.Execute, 1000);
//Local services must be started programmatically using the StartAsync method
Once started, the Url property of the LocalGeoprocessingService can be used as the ServiceUri property of a Geoprocessor Task.
_gpTask = new Geoprocessor(new Uri(gpService.UrlGeoprocessingService));
Local Server Utility
Just as with full server and online services, there are times when you would like access to additional information on services running in the Local Server and also information on the interaction between the API and the service. The ArcGIS Runtime API and Local Server provide facilities for this. It is important here to make a distinction between the Local Server instance within the SDK installation the API uses by default versus a Local Server deployment. The instance included with the SDK installation includes all the components and has several features enabled that can help you debug local services, whereas a deployed instance of the Local Server has 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 instance of the Local Server but must be explicitly included in a deployment when specifying options in the deployment builder. The Local Server Utility provides you with the ability to control how apps work with the Local Server. You can specify logging to help debug ArcGIS Runtime issues, enable HTTP traffic to be viewed in a network monitoring tool, select port range to avoid conflicts, delete temporary files, and provide error reports.
The Local Server Utility can be found in the ArcGIS Runtime SDK for .NET for Windows Desktop installation at the following location on a 64-bit machine:
C:\Program Files (x86)\ArcGIS SDKs\DotNet10.2.4\WindowsDesktop\bin\arcgisruntime10.2.4\LocalServer64\bin\LocalServerUtility.exe
ArcGIS Runtime REST Services Directory
The Local Server provides a services directory like the ArcGIS Services Directory available with online services. This provides a user-friendly HTML view of the service metadata JSON. You can use the HTML service definition and task pages to discover how to code against your services.
The services directory can be accessed via the Local Server URL and can be viewed in a browser to explore service parameters. The Local Server instance in the SDK installation by default includes the HTML server pages, while a deployment of the Local Server does not. This setting is controlled via the Local Server Utility (Generate HTML Server Pages). 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 you disable this option, the Local Server will have a predictable 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, the random prefix option was added to provide additional security from applications running on the local machine.