ArcGIS Maps SDKs

Code examples for this blog are written in C# using ArcGIS Maps SDK for .NET but all the concepts apply to Java, Qt, Swift, and Kotlin.

ArcGIS Maps SDKs for Native Apps (formerly known as ArcGIS Runtime SDK) have improved in some exciting ways in the past few releases, especially when it comes to supporting utility networks and disconnected workflows. We’ll be releasing a series of blogs to share the latest capabilities available to developers working with utility networks in mobile and offline native applications.

In this first blog of the series, we’ll show how you can take advantage of the most significant new features for developers working with utility networks by exploring capabilities that allow you to perform analysis and tracing offline with a sneak peek into its future.

Check out the second part and third part of this blog series, where we cover how the 200.1 release of the Native Maps SDKs has grown in offline tracing functionalities for utility networks in mobile geodatabases including sync-enabled geodatabase from an updated ArcGIS Enterprise 11.1 server.

Working offline

Before we go too far into the details, let’s talk about working while disconnected. Work started on feature-service-based utility networks in ArcGIS Runtime 100.6, with each new release bringing new functionalities. The 200.0 release of the ArcGIS Maps SDK for Native Apps has brought many of these capabilities to utility networks in mobile geodatabases.

When working offline, you’ll need access to a mobile geodatabase, which can be one of the following:

a stand-alone mobile geodatabase that is exported from ArcGIS Pro 2.7 or higher
a sync-enabled mobile geodatabase that is generated from ArcGIS Enterprise Feature Service 10.9 or higher using a GeodatabaseSyncTask or OfflineMapSyncTask

Querying associations

A transformer highlighted with blue-dotted lines that depict its connectivity with fuses and connection points.

Associations enable the modeling of connectivity, containment, and structure attachment between non-spatial and non-coincident network features. The ability to query these associations is an important workflow for mobile users and has historically required you to be connected to a feature-service-based utility network. As of ArcGIS Runtime 100.11 and ArcGIS Enterprise 10.9, you can now use a utility network in mobile geodatabases to query associations for a specific utility element or an area of interest using the same code for a feature-service-based utility network.

The following code uses an element for retrieving containment associations, and an extent for determining attachment and connectivity associations of its contents.

// Specify a utility element container
var containments = await utilityNetwork.GetAssociationsAsync(container, UtilityAssociationType.Containment);
            
// Get features for its contents
var contents = from containment in containments select containment.ToElement;
var contentFeatures = await utilityNetwork.GetFeaturesForElementsAsync(contents);

// Get an extent for its contents
var featureGeometries = from content in contentFeatures select content.Geometry;
var contentExtent = GeometryEngine.CombineExtents(featureGeometries);

// Specify an area of interest
var associations = await utilityNetwork.GetAssociationsAsync(contentExtent);

When your map contains partial feature data, associations are returned with some elements potentially marked invalid. This means that while the association type, the utility element’s global ID, and network source remains accurate, the utility element’s object ID, asset group, and asset type cannot be determined; and therefore, GetFeaturesForElements, will not be able to return features for such elements.

You can have partial feature data through any of the following means:

having a subset of layers and tables
providing a definition expression on the tables
requesting for a smaller area of interest than the utility network extent

Tracing the network

Highlighted result of a subnetwork trace on a stand-alone mobile geodatabase with Naperville Electric data.

One of the most requested features for utility networks is the ability to trace a utility network while disconnected. If you didn’t already know, we added this capability in the 200.0 release of ArcGIS Maps SDK for Native Apps.

First, load the utility network that is created from your mobile geodatabase. Once loaded from the source, the utility network’s definition includes the capabilities the UtilityNetwork object supports, such as whether tracing and/or querying associations are supported.

At a minimum, a simple trace needs a single starting point that can be supplied by creating a utility element from either a feature or an asset type. You can repeat this process if you need to add additional starting locations or even barriers. Some asset types support more than one terminal; in these cases, you will need to specify the terminal on the utility element before they can be used in a trace.

The code below demonstrates both ways of creating a utility element.

// Get an asset type from the utility network definition
var networkSource = utilityNetwork.Definition?.GetNetworkSource("Electric  Device");
var assetGroup = networkSource?.GetAssetGroup("Circuit Breaker");
var assetType = assetGroup?.GetAssetType("Three Phase");

// Specify an asset type and global id to create a starting point
var startingPoint = utilityNetwork.CreateElement(assetType, Guid.Parse("{1CAF7740-0BF4-4113-8DB2-654E18800028}"));

// Set a terminal for asset types supporting more than terminal
startingPoint.Terminal = startingPointt.AssetType.TerminalConfiguration?.Terminals.FirstOrDefault();

// Query a feature
var query= new QueryParameters(){ WhereClause = "GlobalId like '{B9E37A9F-52F3-58FBEA4902}'"};
var queryResult = await networkSource.FeatureTable.QueryFeaturesAsync(query);
var arcgisFeature = queryResult.FirstOrDefault() as ArcGISFeature;

// Specify a feature to create a barrier
var barrier = utilityNetwork.CreateElement(arcgisFeature);

// Provide these trace location elements as a starting point or a barrier
var traceParameters = new UtilityTraceParameters(UtilityTraceType.Connected, new[] { startingPoint });
traceParameters.Barriers.Add(barrier);

Specifying a trace type and a starting point is not always enough to run a trace. Subnetwork traces (subnetwork, upstream/downstream) require a domain network, an isolation trace requires a filter, and a shortest path trace requires two junctions. Most workflows also require defining condition and function barriers to limit traversability of the trace. If you have specific calculations you want your trace to perform, your trace will need to be configured with operations on network attributes to create function results.

Tracing with named trace configurations

While you can create trace configurations on demand, they are typically configured ahead of time by a user and then loaded in the application at runtime. One easy way to achieve this is to use named trace configurations, which require services published using ArcGIS Enterprise 10.9 or higher. This allows GIS administrators to create and share the same set of named trace configurations to all desktop, web, and mobile users. Administrators can also choose to share a subset of these named trace configurations with a web map to provide web and mobile users with trace configurations specific to those displays. You can visit the online help to learn more about support for named trace configurations available in ArcGIS Enterprise Feature Service 10.9 or higher.

The following code shows how to get named trace configurations from a specific creator with a particular tag and then run a trace with a configuration matching this search criteria.

// Query for specific named trace configurations
var query = new UtilityNamedTraceConfigurationQueryParameters();
query.Creators.Add("unadmin");
query.Tags.Add("electric");

var queryResult = await utilityNetwork.QueryNamedTraceConfigurationsAsync(query);

// Trace with named trace configuration
if (queryResult.FirstOrDefault() is UtilityNamedTraceConfiguration config)
{
    var traceParameters = new UtilityTraceParameters(config, new[] { startingPoint });
    var traceResults = await utilityNetwork.TraceAsync(traceParameters);
}

Stand-alone mobile geodatabase

To perform offline tracing, you will need a geodatabase with a full utility network topology which currently can only be created using ArcGIS Pro 2.7 or higher. This includes tables necessary for querying associations and tracing with named trace configurations.

Offline utility networks currently support connected, subnetwork, upstream, and downstream traces in partitioned domain networks with element and function results. They do not support isolation, loops, or shortest path traces in hierarchical domain networks with aggregated geometry results.

The following code checks for supported trace types, domain networks, and result types.

if (traceParameters.TraceType == UtilityTraceType.Connected ||
    traceParameters.TraceType == UtilityTraceType.Subnetwork ||
    traceParameters.TraceType == UtilityTraceType.Upstream ||
    traceParameters.TraceType == UtilityTraceType.Downstream ||
    traceParameters.TraceConfiguration?.DomainNetwork is null ||
    traceParameters.TraceConfiguration.DomainNetwork.TierType == UtilityTierType.Partitioned ||
    !traceParameters.ResultTypes.Any(r => r == UtilityTraceResultType.Geometry))
{
    var traceResults = await utilityNetwork.TraceAsync(traceParameters);
}

Sync-enabled mobile geodatabase

A sync-enabled mobile geodatabase can be generated directly from a feature service or by taking a web map with utility network offline. If the online utility network source is an ArcGIS Enterprise Feature Service 10.9 or higher, the resulting offline utility network will support querying associations.

Future releases of the ArcGIS Maps SDK for Native Apps and ArcGIS Enterprise will support creating geodatabases with full utility network topology using the OfflineMapTask or GeodatabaseSyncTask to enable tracing.

These are the currently available functionalities for a utility network from a stand-alone mobile and sync-enabled mobile geodatabase.

A table that lists supported functionalities for utility networks in a stand-alone mobile and sync-enabled geodatabase.

Conclusion

ArcGIS Maps SDKs for Native Apps is continuously and persistently growing support for utility networks; delivering the core functionalities that were once only available for feature-service-based utility networks are now becoming more available in geodatabase-based utility networks. In fact, all the code examples shared in this blog are applicable to both online and offline. We invite you to look at our documentation and samples within the Utility network section of the .NET guide.

Whether you are new to ArcGIS Maps SDK for Native Apps or already using the SDK, we hope this blog has been helpful so you can write apps that also leverage the power of utility networks in disconnected environments. You can be assured that the team is working hard to deliver all utility network capabilities to better support your workflow – online or offline.

Don’t forget to check out the parts 2 and 3 of this series, where we share how to configure the utility network’s offline capability when downloading from a service, and leverage the new tracing workflows are available for utility networks in mobile geodatabases!

We look forward to hearing how your native apps have explored utility networks for tracing and analysis!

About the author

Jennifer Nery

Jennifer Nery is a senior API Developer for the ArcGIS Maps SDK for .NET with over 14 years of experience in designing and developing APIs, toolkits, samples, and applications for desktop and mobile. Jennifer actively participates in the full development of utility networks, enhancement of feature layers, expanding support for branch versioning and session management, and is passionate about seeing these awesome features come to life for developers in ArcGIS Maps SDK for Native Apps!

Article Discussion:

0 Comments

Inline Feedbacks

View all comments

Using Arcade to Create a Status Graphic

Read this article

Offline utility networks in ArcGIS Maps SDKs for Native Apps