Trace parameters specify how the trace analysis proceeds across the utility network. Essential trace parameters, described in this section, include:
Trace type
Use one of the supported traces (such as upstream, downstream, subnetwork, and so on) to create the parameters with starting locations. Refer to the Trace a utility network overview for a description of the supported trace types.
var traceParameters = new UtilityTraceParameters(UtilityTraceType.Downstream, _startingLocations);
Trace locations
A trace location can be one of the following:
- Starting point
- Barrier
- Filter barrier
All of the traces except shortest path require at least one starting point. Barriers are optional. A filter barrier is only required for an isolation trace when no trace filter barrier condition was specified. The respective collections for these contain UtilityElement objects that can be created as explained in the Analyze your network topic.
Once you have a utility element, you can add it to the collection that fits its purpose.
traceParameters.StartingLocations.Add(startingElement);
traceParameters.Barriers.Add(barrierElement);
traceParameters.FilterBarriers.Add(filterBarrierElement);
Trace configuration
A trace configuration allows you to do things like:
- Stop the trace at protective devices if they are open. For example, the flow of electricity in a network will be stopped if a fuse is open.
- Control the types of features traced. For example, trace only pipes with a diameter greater than six inches.
- Filter the types of features returned as trace results. For example, only return elements identified by the trace that represent wooden poles.
- Define functions to run calculations on network attributes associated with traced features. For example, the sum of the length of all the wire traced. Several functions can be specified for a trace.
See the Trace configuration topic for more information.
Below is an example of trace configuration for isolation trace.
var domainNetwork = _utilityNetwork.Definition?.GetDomainNetwork("Water");
traceParameters.TraceConfiguration = new UtilityTraceConfiguration()
{
DomainNetwork = domainNetwork,
TargetTier = domainNetwork?.GetTier("Water Pressure"),
Filter = new UtilityTraceFilter()
{
Barriers = new UtilityCategoryComparison("Isolating", UtilityCategoryComparisonOperator.Exists)
}
};
Trace results
You can add a variety of trace result types (UtilityTraceResultType) to the UtilityTraceParameters result types collection to define the results returned from a trace. At least one type of trace result is required, but you can request several.
- Element results—Provide information about the individual network features. This is the default result returned.
- Function results—Calculate values based on network attributes. Note that this type of result requires your trace configuration to include function inputs.
- Geometry results—Allow you to display the results on the map. This result type is supported by ArcGIS Enterprise 10.8.1 or later and for mobile geodatabase, you need ArcGIS Maps SDKs for Native Apps version 200.1 or later.
See the Work with trace results topic for more information about trace results.
The following example shows creating a trace function, including it with the trace configuration, and requesting its result in the output.
var shapeLengthAttribute = _utilityNetwork.Definition?.GetNetworkAttribute("Shape length");
var addShapeLength = new UtilityTraceFunction(UtilityTraceFunctionType.Add, shapeLengthAttribute);
traceParameters.TraceConfiguration.Functions.Add(addShapeLength);
traceParameters.ResultTypes.Add(UtilityTraceResultType.FunctionOutputs);