ArcGIS Runtime SDK for .NET

Local Server

Local Server, an optional component of ArcGIS Runtime SDK for .NET, is primarily for executing offline geoprocessing tasks in your ArcGIS Runtime apps. These tasks work in the same way as geoprocessing tasks published from ArcGIS Online or ArcGIS Enterprise. Running a geoprocessing task on Local Server requires an ArcGIS Pro or ArcMap geoprocessing package (.gpkx or .gpk file). These packages are authored in ArcGIS Desktop either using Model Builder or by writing a Python script.

Local Server also allows developers to consume map image layers or feature layers from content in an ArcGIS Pro or ArcMap map package (.mpkx or .mpk file). These packages are authored and created using ArcGIS Desktop. This capability has been included to support workflows in earlier versions of ArcGIS Runtime. If you're starting a new project and require offline data, use sync-enabled geodatabases, which are generated from feature services. See Create an offline map for details.

Local Server can be downloaded for Windows (32- and 64-bit) .

To develop with Local Server you must install the ArcGIS Runtime Local Server SDK and add the Esri.ArcGISRuntime.LocalServices NuGet package to your WPF application project. To deploy your app with Local Server capabilities you must configure the ArcGIS Runtime Local Server manifest file which is automatically generated in your WPF application project folder.

Installing the Local Server SDK

Install Local Server on Windows

  1. Ensure your development machine meets the system requirements for ArcGIS Runtime Local Server SDK .NET. Development and deployment machines must also have the following packages installed:
    • Microsoft Visual C++ Redistributable for Visual Studio 2017
    • Development and deployment on Windows 8.1, Windows Server 2012, Windows Server 2012 R2, or Windows 7 SP1 also requires installation of the Windows 10 Universal C Runtime via the following Windows Updates or Update Packages:
      • Update for Windows 8.1 (KB2999226)
      • Update for Windows 8.1 for x64-based Systems (KB2999226)
      • Update for Windows Server 2012 R2 (KB2999226)
      • Update for Windows Server 2012 (KB2999226)
      • Update for Windows 7 (KB2999226)
      • Update for Windows 7 for x64-based Systems (KB2999226)
  2. Download Local Server from the Downloads page. You'll need to log in with an ArcGIS developer account. Sign up for a free account if you haven't already. Save the file to a location on your development machine.
  3. Extract the file you downloaded, and then double-click the Setup.exe file to start the installation wizard.
  4. Follow the instructions. In the Destination Folder dialog, you can change the default installation directory by clicking the Change button, then navigating to the desired folder. Make sure you have write permissions to this folder on your development machine. Ensure no other users are using the folder.
  5. On the last panel of the wizard, click Finish. The ArcGIS Runtime Local Server is now installed at the installation folder you chose in the previous step.

Installing database client software for enterprise geodatabase connections

If any of your Local Server packages make use of enterprise geodatabase connections (SDE), then you may need to install the client software for the database you are connecting to. The section on Database connections gives details on the configuration of database client software.

Install and deploy Local Server

When developing an ArcGIS Runtime app, you can use a lightweight client API to work with classes in Local Server. The Local Server components themselves are installed separately with ArcGIS Runtime Local Server SDK. To limit the file size of your deployed app, you can limit the Local Server components to contain only those used in your app.

Local Server Runtime SDK and client API

To develop with Local Server, you need to add the Esri.ArcGISRuntime.LocalServices NuGet package to your project.

LocalServices NuGet package

This package provides the Local Server client API for you to program against in your WPF application project, but does not install the underlying Local Server SDK. The first time you build your project with the client API package included, you will receive a build error like the following if the underlying Local Server SDK is not installed on your machine.

Visual Studio build error

You can download the setup for the Local Server SDK at https://developers.arcgis.com/downloads/apis-and-sdks?product=local-server. Once the Local Server SDK is installed on your development machine, Visual Studio will be able to locate the Local Server components and you can successfully build projects that include the client API.

Deploying Local Server

The first time you build a project that uses Local Server, a deployment manifest file will be created in your project directory (ArcGISLocalServer_100.x.AGSDeployment).

Note:

The deployment file is created in your project directory, but is not added to your Visual Studio project. To see it listed in the Solution Explorer window, you will need to choose to Show All Files.

This is an XML-formatted text file that defines the components (listed as Package elements) of Local Server to deploy for your app. The two top-level Package elements in the file provide the ability to read map and geoprocessing packages produced from ArcGIS Pro or ArcMap respectively. Under each of those parent elements are child Package elements that provide specific functionality for that data format, such as geoprocessing or Python scripting support. By default, only the ArcMap Local Server component is included. To include additional capabilities (either within the ArcMap Local Server or to add ArcGIS Pro support), you need to edit this file manually. Only those Local Server packages with an enabled value of true are included in the deployment. The following configuration setting adds support for ArcGIS Pro map and geoprocessing packages (only available for 64-bit deployments).
<!--This local server has support for ArcGIS Pro mpkx and gpkx packages. It is 64 bit only-->
<Package id="Pro" name="ArcGIS Pro Compatible Server" enabled="true">
Note:

If you choose to include the ArcGIS Pro compatible Local Server with your deployment, but are not building for 64-bit, you will receive a build error. To include ArcGIS Pro support, your project must be set to build for x64 or Any CPU with the prefer 32-bit option unchecked.

When you build your project, the components you have enabled in ArcGISLocalServer_100.x.AGSDeployment will be included in the output for the platform(s) you're building. If building for 64-bit, for example, the requested Local Server components will be copied to your project's output folder under LocalServer100.x\64\.. If building for Any CPU (and Prefer 32-bit is unchecked in your project build properties), you will have a 32 and a 64 folder under the LocalServer100.x parent folder.
Note:

Previous versions of ArcGIS Runtime SDK for .NET provide a Visual Studio menu to add an ArcGIS Runtime deployment manifest to the project as well as a UI for updating this file. If you have a previous version installed, you will receive an error when trying to add the older deployment manifest file to a project that uses the current version ("unsupported SDK version").

Apart from installing the Local Server SDK and ensuring you have edited the deployment file to include the components you need, there are no additional steps for deploying Local Server capabilities for your ArcGIS Runtime SDK for .NET app.

Start a Local Server instance

You must start a Local Server instance if you want your app to use any services on the Local Server. Only one instance of the Local Server can be running at any time.

  1. LocalServer is a singleton object, which means there is always just one instance of the LocalServer class available in your code. You do not need to create an instance of LocalServer, you simply access it with the Instance static property. The following code stores the LocalServer instance in a private field, wires a listener for the StatusChanged event, then starts the server.
    private Esri.ArcGISRuntime.LocalServices.LocalServer _localServer;
    private async void StartLocalServer()
    {
        // Get the singleton LocalServer object using the static "Instance" property
        _localServer = Esri.ArcGISRuntime.LocalServices.LocalServer.Instance;
                
        // Handle the StatusChanged event to react when the server is started
        _localServer.StatusChanged += ServerStatusChanged;
                
        // Start the local server instance
        await _localServer.StartAsync();
    }
    
    private void ServerStatusChanged(object sender, Esri.ArcGISRuntime.LocalServices.StatusChangedEventArgs e)
    {
        // Check if the server started successfully
        if(e.Status == Esri.ArcGISRuntime.LocalServices.LocalServerStatus.Started)
        {
            // Start specific local services here ...
        }
    }
  2. Once the Local Server has started, you can start services (such as geoprocessing services, for example) as described in the following sections.
  3. When an application is closed down, the Local Server should also be shut down by calling StopAsync.
    _localServer.StopAsync();
    // ... or ...
    Esri.ArcGISRuntime.LocalServices.LocalServer.Instance.StopAsync();

Run geoprocessing services

Geoprocessing services can be used from Local Server with a geoprocessing package file (.gpkx or .gpk file). The geoprocessing packages are authored and published using ArcGIS Pro or ArcMap. When preparing a geoprocessing package with ArcGIS Pro, be sure to check the Support ArcGIS Runtime box in the Parameters pane. If this box is not checked, the .gpkx file will not run as a Local Server service. For more information about geoprocessing, see Run a geoprocessing task.

A local geoprocessing service can be started provided that the Local Server is started. The following code shows how to start the service and set up a task to use the "Message in a bottle" sample geoprocessing package.

// Create a local GP service from a geoprocessing package on disk
LocalGeoprocessingService localServiceGP = new LocalGeoprocessingService(@"D:\Data\message-in-a-bottle.gpkx");
                
// Handle the status changed event to check when it's loaded
localServiceGP.StatusChanged += (svc, args) =>
{
    // If service started successfully, create a gp task
    if (args.Status == LocalServerStatus.Started)
    {
        // Get the URL for the specific geoprocessing tool
        var gpSvcUrl = (svc as LocalGeoprocessingService).Url.AbsoluteUri + "/MessageInABottle";

        // Create the geoprocessing task
        GeoprocessingTask gpMsgInBottleTask = new GeoprocessingTask(new Uri(gpSvcUrl));
                        
        // Create parameters, run the task, process results, etc.
        // ...
    }
};
// Start the local geoprocessing service
await localServiceGP.StartAsync();

To learn how to use ArcGIS Pro to create a geoprocessing result that can be shared as a geoprocessing package, try the DevLab.

Run map image layer services

Map services can be consumed from Local Server using a map package file. Provided that the Local Server is started, you can start a service. Once the service is started, the URL is obtained and used to add an ArcGISMapImageLayer to your map.

// Create a local map service from a map package on disk
var mapService = new LocalMapService(@"D:\Data\USAMapPackage.mpkx");

// Handle the status changed event to check when it's loaded
mapService.StatusChanged += (svc, args) => 
{
    // If started successfully, add a layer from the service
    if(args.Status == LocalServerStatus.Started)
    {
        // Get the service URL
        var mapServiceUrl = (svc as LocalMapService).Url;
                        
        // Create a new ArcGISMapImageLayer
        ArcGISMapImageLayer localServiceLayer = new ArcGISMapImageLayer(mapServiceUrl);

        // Set layer opacity to semi-transparent
        localServiceLayer.Opacity = 0.5;
        
        // Add the layer to the map
        MyMapView.Map.OperationalLayers.Add(localServiceLayer);
    }
};
// Start the local map service
await mapService.StartAsync();
ArcGISMapImageLayer from a local map service

Run feature services

Feature services can also be consumed from a Local Server instance. As with map services, these services use a map package file (.mpkx or .mpk) that has been authored and published from ArcGIS Desktop.

The code below shows how to start the service, obtain the URL, and use this to add a feature layer to the map.

// Create a local feature service from a map package on disk
LocalFeatureService featureService = new LocalFeatureService(_pathToMpkxFile);

// Handle the status changed event to check when it's loaded
featureService.StatusChanged += (svc, args) =>
{
    // If started successfully, add a layer from the service
    if (args.Status == LocalServerStatus.Started)
    {
        // Get the service URL
        var featureServiceUrl = (svc as LocalFeatureService).Url.AbsoluteUri;

        // Create a new service feature table 
        ServiceFeatureTable localServiceTable = new ServiceFeatureTable(new Uri(featureServiceUrl + "/2"));

        // Create a new feature layer to display the features in the table
        FeatureLayer featureLyr = new FeatureLayer(localServiceTable);

        // Add the layer to the map
        MyMapView.Map.OperationalLayers.Add(featureLyr);
    }
};
// Start the local feature service
await featureService.StartAsync();

Supported raster formats

Local Server supports the raster dataset file formats supported by ArcGIS Desktop.