ProConcepts Network Diagrams
The network diagrams API provides access to the network diagrams framework. It provides classes that allow you to do the following:
- Retrieve existing diagram templates.
- Create, store, and delete network diagrams.
- Retrieve stored network diagrams that cover a given extent or contain particular utility network elements.
- Update, overwrite, append, or extend network diagrams.
- Apply predefined layout algorithms on the entire content or parts of a network diagram.
- Retrieve the utility network network features related to a set of diagram features.
- Code custom layouts on a network diagram.
The network diagram does not provide functionality to create or configure diagram templates. These tasks can be accomplished using the geoprocessing API.
Language: C#
Subject: Network Diagrams
Contributor: ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization: Esri, http://www.esri.com
Date: 10/06/2024
ArcGIS Pro: 3.4
Visual Studio: 2022
Almost all of the methods in the utility network API should be called on the Main CIM Thread (MCT). The API reference documentation on the methods that need to run on the MCT are specified as such. These method calls should be wrapped inside the QueuedTask.Run call. Failure to do so will result in ConstructedOnWrongThreadException being thrown. See Working with multithreading in ArcGIS Pro to learn more.
Note: This topic assumes a basic understanding of the utility network information model. See the online help for more information.
Like the geodatabase API, many objects in the managed network diagram API use unmanaged resources (i.e. resources not managed by garbage collection) that must be explicitly released by the application. Unmanaged resources include file locks and database connections, among others. Since network diagrams are often services-based, many of these resources actually exist on the server.
The preferred pattern to manage these underlying unmanaged resources is by calling Dispose once you are done using them. Dispose frees up the unmanaged resources, releasing any underlying file locks or active database connections (You can also use a “using” construct that will call Dispose for you - there are many examples of “using” in the Pro snippets and samples).
More information on these patterns, along with special cases that you should consider, can be found in the resource management section of the geodatabase ProConcepts doc.
The items described in this document are included in the ArcGIS.Core.Data.NetworkDiagrams namespace.
Many of the network diagram-related REST services are synchronous. These use the Network Diagram Server and have low processing overhead. Unfortunately, they can be susceptible to timeout if processing takes too long. To work around this, several of the REST endpoints provide asynchronous versions. Processing is offloaded from the Network diagram Server to the Geoprocessing Server. While this does cause a performance hit, the Geoprocessing Server is designed to handle long-running jobs and is not susceptible to timeouts. With these services, ArcGIS Pro will poll the service until the operation completes.
Some of the C# methods in the network diagram API can provide access to the asynchronous versions of these REST endpoints. These take an ServiceSynchronizationType as a parameter, which is an enum with two values: Synchronous and Asynchronous. It's important to note that from a C# developer's perspective, these are synchronous C# methods. Like other methods in the API, they will block the current thread until the operation completes.
When calling these routines on a file or mobile geodatabase, the ServiceSynchronizationType parameter is ignored.
The DiagramManager class serves as the core class in the network diagrams API. It can be obtained using the GetDiagramManager() method on the UtilityNetwork class.
The diagram manager can be used for the following:
- Create new network diagrams
- Retrieve existing network diagrams
- Retrieve diagram templates
- Retrieve the related network using the
GetNetwork<T>()method.
A DiagramTemplate contains the configuration properties defining the content (diagram rule and layout definitions) and presentation (diagram layer definitions) of a type of network diagram. If the name of a template is known, it can be obtained from the DiagramManager class using the GetDiagramTemplate() method. The GetDiagramTemplates() method on the same class returns a list of all the diagram templates in the system.
The NetworkDiagram class represents a diagram generated from a portion of the utility network.
New network diagrams are created using the CreateNetworkDiagram() factory method on the DiagramManager class. This routine creates a temporary network diagram from a diagram template and a set of utility network feature GlobalIDs.
Existing network diagrams can be retrieved from either the diagram manager or the diagram template used to create them. Network diagrams can be fetched by name, from an envelope, or from a set of utility network feature GlobalIDs using the GetNetworkDiagram() and GetNetworkDiagrams() overloads on both the DiagramManager and DiagramTemplate classes.
The NetworkDiagram class includes a number of properties and methods that provide information about the diagram. Most can be explained from the class reference.
GetConsistencyState() returns the consistency state of the diagram.
| Consistency State | Description |
|---|---|
| DiagramIsConsistent | The diagram and the features that comprise it are both consistent and validated. |
| DiagramNotConsistentWithTopology | The network topology has been validated for the diagram features, but the diagram has not yet been updated. Call NetworkDiagram.Update() to update the diagram. |
| DiagramHasDirtyFeatures | The network topology has not been validated for the diagram features. Call UtilityNetwork.ValidateNetworkTopology(). |
Additional information about a network diagram can be obtained by calling the GetDiagramInfo() method. The following code shows how to examine one of the NetworkDiagramInfo properties to return a list of inconsistent nonsystem network diagrams:
public List<NetworkDiagram> GetInconsistentDiagrams(UtilityNetwork utilityNetwork)
{
// Get the DiagramManager from the utility network
using (DiagramManager diagramManager = utilityNetwork.GetDiagramManager())
{
List<NetworkDiagram> myList = new List<NetworkDiagram>();
// Loop through the network diagrams in the diagram manager
foreach (NetworkDiagram diagram in diagramManager.GetNetworkDiagrams())
{
NetworkDiagramInfo diagramInfo = diagram.GetDiagramInfo();
// If the diagram is not a system diagram and is in an inconsistent state, add it to our list
if (!diagramInfo.IsSystem && diagram.GetConsistencyState() != NetworkDiagramConsistencyState.DiagramIsConsistent)
{
myList.Add(diagram);
}
else
{
diagram.Dispose(); // If we are not returning it we need to Dispose it
}
}
return myList;
}
}The GetContent() method can be used to return diagram information and content as a JSON string. This string can be used to transfer data into external systems, such as network calculation or analysis software.
A network diagram consists of a set of diagram elements that are either junctions, edges, or containers. The elements are represented by the DiagramElement class hierarchy.
The AssociatedGlobalID and AssociatedSourceID properties can be used to retrieve the corresponding utility network row. AssociatedSourceID corresponds to the ID property of the NetworkSource class.
The ID property returns the internal diagram ID of the element. The FromID and ToID properties of an edge diagram element refer to the ID of the two DiagramJunctionElements on either side. Likewise, the ContainerID property refers to the ID of the DiagramElement that is the container.
Diagram elements are returned by diagram element queries.
Diagram aggregations are created when a utility network feature is reduced or collapsed in a network diagram. The utility network feature does not, therefore, correspond to a single diagram element. The GetAggregations() method on the NetworkDiagram object returns a list of DiagramAggregation objects. These provide details on all the diagram elements that are aggregated in the diagram, this is, reduced or collapsed.
The properties of this object are as follows:
| Property | Description |
|---|---|
| AggregatedBy | The diagram element ID for the diagram element under which it has been reduced or collapsed. |
| AggregationType | The type of network diagram aggregation (described in detail below). |
| AssociatedGlobalID, AssociatedSourceID | These two properties can be used to retrieve the corresponding utility network feature. AssociatedSourceID refers to the ID property of a Network Source object. |
The aggregation types are described as follows:
- JunctionAggregation—For utility network features aggregated under a diagram junction element. This diagram junction may correspond to the following:
- A utility network container point or polygon represented as a point in the diagram. This diagram point is related to a set of utility network content features that have been collapsed in the network diagram.
- A utility network junction point represented as a point in the diagram. This diagram point is related to a set of utility network features that have been reduced in the network diagram.
- EdgeAggregation—For utility network features aggregated under a diagram edge element. This diagram edge may correspond to the following:
- A utility network container line represented as an edge in the diagram. This diagram edge is related to a set of utility network content features that have been collapsed in the network diagram.
- A reduction edge diagram. This diagram edge is related to a set of utility network features that have been reduced in the network diagram.
- ContainerAggregation—For utility network features reduced under a diagram polygon. This diagram polygon may correspond to the following:
- A utility network container point or polygon represented as a polygon in the diagram with all or part of its related content features inside the diagram polygon.
- NoneAggregation—For utility network features aggregated in the diagram without a corresponding diagram element.
- For example, unconnected system junctions are systematically reduced to nothing when running a Reduce Junction rule that processes unconnected junctions.
- In the same way, depending on the Reduce Junction rule settings, certain disconnected portions of the utility network may be reduced to nothing in the resulting diagram.
Network diagrams provide two methods to fetch feature information.
First, you can fetch the information from diagram features using the FindDiagramFeatures() method. This method retrieves a list of FindResultItem objects that correspond to all features in the diagram that meet the following conditions:
- Associated with a set of utility network feature GlobalIDs
- Represent connectivity associations
Features that are represented in the diagram or are aggregated within the diagram are both included.
The FindResultItem class provides GlobalID, ObjectID, SourceID (corresponding to NetworkSource.ID) and GeometryType properties.
Second, the FindNetworkRows() method provides similar functionality, returning a list of FindResultItem objects that correspond to utility network rows. FindInitialNetworkRows() is a similar method that only returns the network rows initially used as input for the diagram generation.
These two methods can be used to build extensions that communicate information back and forth between diagrams and regular maps. Some examples from the core product are the Apply To Diagrams and Apply To Maps commands on the Utility Network and Network Diagram tab groups on the ribbon.
Diagram elements are returned using the QueryDiagramElements() method on the NetworkDiagram class. There are three overloads for this method.
The QueryDiagramElements(DiagramElementQueryByElementTypes query) overload takes a DiagramElementQueryByElementTypes object to specify the types of diagram elements to return from a network diagram.
The QueryDiagramElements(DiagramElementQueryByExtent query) overload takes a DiagramElementQueryByExtent object to specify the extent to use as a constraint to retrieve the diagram elements.
Finally, the QueryDiagramElements(DiagramElementQueryByObjectIDs query) overload takes a DiagramElementQueryByObjectIDs object to retrieve the diagram elements that correspond to a set of object IDs from diagram features.
The DiagramElementQueryResult class returns the set of diagram elements that are returned from the query.
The following code example shows how to retrieve junction diagram elements whose extent intersects a map extent.
// Create a DiagramElementQueryByExtent to retrieve diagram element junctions whose extent
// intersects the active map extent
DiagramElementQueryByExtent elementQuery = new DiagramElementQueryByExtent();
elementQuery.ExtentOfInterest = MapView.Active.Extent;
elementQuery.AddContents = false;
elementQuery.QueryDiagramJunctionElement = true;
elementQuery.QueryDiagramEdgeElement = false;
elementQuery.QueryDiagramContainerElement = false;
// Use this DiagramElementQueryByExtent as an argument to the QueryDiagramElements method
DiagramElementQueryResult result = networkDiagram.QueryDiagramElements(elementQuery);Network diagrams can be updated with the Update() method. This synchronizes a diagram based on the latest network topology; it incorporates any changes that were made to the features since the last update.
Append() is used to add features to an existing network diagram, while Overwrite() completely rebuilds the network diagram from a new set of features. Extend() is used to extend the entire content of the network diagram by one-row level of adjacency. The NetworkDiagramExtendType designates whether the one level of adjacency applies to connectivity, attachment, or containment. Not every diagram can be extended, the NetworkDiagramInfo.CanExtend property can be used to check this.
Store() persists a temporary network diagram in the database, and Delete() removes it from the database.
None of these editing methods can process utility network subnetwork system diagrams. These can only be updated by Subnetwork.Update() or deleted by the subnetwork. In addition, not every diagram template permits storage. The NetworkDiagramInfo.CanStore property can be used to check this.
Network diagrams also contain a set of flags, which can be retrieved by type using the GetFlags() method. This method returns a set of DiagramFlag classes.
Likewise, flags can be added with AddFlag() and removed with RemoveFlag(), which removes a single flag, or RemoveFlags(), which removes all of them.
There are three ways that can be used to change the layout of a diagram:
- Apply a predefined diagram layout
- Create a custom layout
- Reapply the template layout
These are described in the sections that follow.
The API provides a class hierarchy of DiagramLayoutParameters classes. The concrete subclasses each correspond to a geoprocessing tool and most correspond to a diagram layout that is available in the ArcGIS Pro user interface.
The properties in these classes are used to specify the desired layout. This parameter is then passed to NetworkDiagram.ApplyLayout() to change the layout of the diagram.
If you only want to change the layout of a subset of the diagram, you can create and use a DiagramElementObjectIDs object and also pass that to NetworkDiagram.ApplyLayout().
The collection of ObjectIDs passed into the DiagramElementObjectIDs can come from a map selection or a DiagramElement query.
To create a completely custom layout, the first step is to gather a set of diagram elements with a DiagramElement query. The Shape property of these diagram elements can be modified according to a custom algorithm. Once they are edited, they can be packaged into a NetworkDiagramSubset object and passed into the SaveLayout() method.
The following code example shows how to use a diagram query to fetch a set of diagram elements. The shapes of the elements are changed, and the SaveLayout() method is used to update the diagram. This allows you to write your own layout algorithms.
// Retrieve a diagram
using (NetworkDiagram diagramTest = diagramManager.GetNetworkDiagram(diagramName))
{
// Create a DiagramElementQueryByElementTypes query object to get the diagram elements we want to work with
DiagramElementQueryByElementTypes query = new DiagramElementQueryByElementTypes();
query.QueryDiagramJunctionElement = true;
query.QueryDiagramEdgeElement = true;
query.QueryDiagramContainerElement = true;
// Retrieve those diagram elements
DiagramElementQueryResult elements = diagramTest.QueryDiagramElements(query);
// Create a NetworkDiagramSubset object to edit this set of diagram elements
NetworkDiagramSubset subset = new NetworkDiagramSubset();
subset.DiagramJunctionElements = elements.DiagramJunctionElements;
subset.DiagramEdgeElements = elements.DiagramEdgeElements;
subset.DiagramContainerElements = elements.DiagramContainerElements;
// Edit the shapes of the diagram elements - left as an exercise for the student
TranslateDiagramElements(subset);
// Save the new layout of the diagram elements
diagramTest.SaveLayout(subset, true);
}The final way to change a layout is to reapply the template layout with the ApplyTemplateLayouts() method.
The network diagram editing methods provide their own transaction management. Therefore, they cannot be included in another editing transaction (for example, Geodatabase.ApplyEdits()). In addition, because the edits performed by these methods cannot be undone, they cannot be called from within an existing editing session; all existing edits must be saved or reverted prior to calling these methods.
These rules apply to the following methods on the NetworkDiagram class:
AddFlag()Append()ApplyLayout()ApplyTemplateLayouts()Delete()ExtendDiagram()Overwrite()RemoveFlag()RemoveFlags()SaveLayout()Store()Update()
The same restrictions also apply to DiagramManager.CreateNetworkDiagram().
The DiagramLayer class represents a network diagram layer in a network diagram window (a kind of map). This class resides in a mapping rather than a geodatabase namespace, ArcGIS.Desktop.Mapping.
The GetNetworkDiagram() method returns the NetworkDiagram class displayed by this window.
The ConsistencyState property returns the consistency state of the diagram. The possible values are DiagramIsConsistent, DiagramNotConsistentWithTopology, and DiagramHasDirtyFeatures.
The DiagramLayer class inherits from CompositeLayer.
The following code snippet shows how to take a network diagram and open a network diagram window that corresponds to it:
// Create a diagram layer from a NetworkDiagram (myDiagram)
DiagramLayer diagramLayer = await QueuedTask.Run<DiagramLayer>(() =>
{
// Create the diagram map
var newMap = MapFactory.Instance.CreateMap(myDiagram.Name, ArcGIS.Core.CIM.MapType.NetworkDiagram, MapViewingMode.Map);
if (newMap == null)
return null;
// Open the diagram map
var mapPane = ArcGIS.Desktop.Core.ProApp.Panes.CreateMapPaneAsync(newMap, MapViewingMode.Map);
if (mapPane == null)
return null;
//Add the diagram to the map
return newMap.AddDiagramLayer(myDiagram);
}); 