Trace(TraceArgument) Method

In This Topic

Executes a trace.

Syntax

C#
Visual Basic (Declaration)

public abstract IReadOnlyList<Result> Trace( 
   TraceArgument traceArgument
)

Public Overloads MustOverride Function Trace( _
   ByVal traceArgument As TraceArgument _
) As IReadOnlyList(Of Result)

Parameters

traceArgument: The input arguments to the trace.

Return Value

A IReadOnlyList of concrete Result whose type corresponds to ResultType set in TraceArgument.ResultTypes.

Exceptions

Exception	Description
System.ArgumentNullException	traceArgument is null.
System.NotSupportedException	This operation is not supported in client-server mode.
System.InvalidOperationException	If the ArcGIS.Core.Data.UtilityNetwork.Terminal in any ArcGIS.Core.Data.UtilityNetwork.Element in TraceArgument.StartingLocations, TraceArgument.Barriers or TraceArgument.FilterBarriers is null and the associated ArcGIS.Core.Data.UtilityNetwork.TerminalConfiguration has multiple terminals.
ArcGIS.Core.Data.Exceptions.GeodatabaseException	A geodatabase-related exception has occurred.

Remarks

Derived implementations may impose stronger preconditions. For example, a concrete Tracer implementation may throw a System.ArgumentException if is created using the TraceArgument.TraceArgument Constructor(Subnetwork) constructor when ArcGIS.Core.Data.UtilityNetwork.Subnetwork does not apply to the particular tracer.

Example

Trace a utility network using a named trace configuration

private void TraceUtilityNetworkUsingNamedTraceConfiguration(UtilityNetwork utilityNetwork, NamedTraceConfiguration namedTraceConfiguration, Element startElement)
{
  // Get the trace manager from the utility network
  using (TraceManager traceManager = utilityNetwork.GetTraceManager())
  {
    // Get a tracer from the trace manager using the named trace configuration
    Tracer upstreamTracer = traceManager.GetTracer(namedTraceConfiguration);

    // Trace argument holding the trace input parameters
    TraceArgument upstreamTraceArgument = new TraceArgument(namedTraceConfiguration, new List<Element> { startElement });

    // Trace results 
    IReadOnlyList<Result> upstreamTraceResults = upstreamTracer.Trace(upstreamTraceArgument);
  }
}

Export a utility network trace as a JSON file

private void ExportUtilityNetworkTraceAsJSON(UtilityNetwork utilityNetwork)
{
  using (TraceManager traceManager = utilityNetwork.GetTraceManager())
  using (UtilityNetworkDefinition utilityNetworkDefinition = utilityNetwork.GetDefinition())
  using (NetworkSource deviceNetworkSource = GetNetworkSource(utilityNetworkDefinition, "GasDevice") as NetworkSource)
  using (FeatureClass distributionDeviceFeatureClass = utilityNetwork.GetTable(deviceNetworkSource) as FeatureClass)
  using (FeatureClassDefinition distributionDeviceDefinition = distributionDeviceFeatureClass.GetDefinition())
  using (AssetGroup deviceAssetGroup = deviceNetworkSource.GetAssetGroup("Regulator"))
  using (AssetType deviceAssetType = deviceAssetGroup.GetAssetType("Pressure Reducing"))
  using (NetworkAttribute deviceStatusNetworkAttribute = utilityNetworkDefinition.GetNetworkAttribute("DeviceStatus"))
  using (NetworkAttribute accessibleNetworkAttribute = utilityNetworkDefinition.GetNetworkAttribute("Accessible"))
  {
    // Domain and tier information
    DomainNetwork domainNetwork = utilityNetworkDefinition.GetDomainNetwork("Gas");
    Tier pipeDistributionSystemTier = domainNetwork.GetTier("Pipe Distribution");

    // Start elements
    Element startingPoint1 = utilityNetwork.CreateElement(deviceAssetType, Guid.Parse("{28CF437E-950C-41B7-B839-8BC45570DE40}"));
    Element startingPoint2 = utilityNetwork.CreateElement(deviceAssetType, Guid.Parse("{63C22828-7BC9-49ED-A14A-A596559B6CB3}"));

    startingPoint1.Terminal = startingPoint1.AssetType.GetTerminalConfiguration().Terminals.First(x => x.IsUpstreamTerminal);
    startingPoint2.Terminal = startingPoint2.AssetType.GetTerminalConfiguration().Terminals.First(x => x.IsUpstreamTerminal);

    List<Element> startingPoints = new List<Element>() { startingPoint1, startingPoint2 };
    List<Element> barriers = new List<Element>();

    // Set up trace filter: DeviceStatus = Open (1) AND Accessible = 1
    NetworkAttributeComparison statusNetworkAttributeComparison = new NetworkAttributeComparison(deviceStatusNetworkAttribute, Operator.Equal, 1);
    NetworkAttributeComparison networkAttributeComparison = new NetworkAttributeComparison(accessibleNetworkAttribute, Operator.Equal, 1);
    
    // Set trace configuration 
    TraceConfiguration traceConfiguration = new TraceConfiguration
    {
      AllowIndeterminateFlow = true,
      IgnoreBarriersAtStartingPoints = false,
      IncludeBarriersWithResults = true,
      IncludeContainers = true,
      IncludeContent = true,
      IncludeIsolatedFeatures = false,
      IncludeUpToFirstSpatialContainer = false
    };

    traceConfiguration.Filter.Barriers = new And(statusNetworkAttributeComparison, networkAttributeComparison);
    traceConfiguration.DomainNetwork = domainNetwork;
    traceConfiguration.SourceTier = pipeDistributionSystemTier;

    // Attribute fields of a network source
    List<string> deviceFields = distributionDeviceDefinition.GetFields().Select(f => f.Name).ToList();

    // Network attributes 
    List<string> networkattributeNames = new List<string>();

    IReadOnlyList<NetworkAttribute> networkAttributes = utilityNetworkDefinition.GetNetworkAttributes();

    foreach (NetworkAttribute networkAttribute in networkAttributes)
    {
      networkattributeNames.Add(networkAttribute.Name);
    }

    // Result Types
    List<ResultType> resultTypeList = new List<ResultType>() { ResultType.Feature };

    // Resutl Options
    ResultOptions resultOptions = new ResultOptions()
    {
      IncludeGeometry = true,
      NetworkAttributes = networkattributeNames,
      ResultFields = new Dictionary<NetworkSource, List<string>>() { { deviceNetworkSource, deviceFields } }
    };

    // Trace Arguments
    TraceArgument traceArgument = new TraceArgument(startingPoints)
    {
      Barriers = barriers,
      Configuration = traceConfiguration,
      ResultTypes = resultTypeList,
      ResultOptions = resultOptions
    };

    ConnectedTracer connectedTracer = traceManager.GetTracer<ConnectedTracer>();

    // Set export options 
    TraceExportOptions exportOptions = new TraceExportOptions()
    {
      ServiceSynchronizationType = ServiceSynchronizationType.Asynchronous,
      IncludeDomainDescriptions = true,
    };

    // Path to export JSON
    string jsonPath =  $"{Path.GetTempPath()}TraceResults.json";
    Uri jsonUri = new Uri(jsonPath);

    // Export 
    connectedTracer.Export(jsonUri, traceArgument, exportOptions);

    string jsonAbsolutePath = HttpUtility.UrlDecode(jsonUri.AbsolutePath);
    if (jsonUri.IsFile && File.Exists(jsonAbsolutePath))
    {
      // Work with the JSON results
    }
  }
  NetworkSource GetNetworkSource(UtilityNetworkDefinition unDefinition, string name)
  {
    IReadOnlyList<NetworkSource> allSources = unDefinition.GetNetworkSources();
    foreach (NetworkSource source in allSources)
    {
      if (name.Contains("Partitioned Sink"))
      {
        if (source.Name.Replace(" ", "").ToUpper().Contains(name.Replace(" ", "").ToUpper()) ||
            source.Name.Replace(" ", "").ToUpper()
              .Contains(name.Replace("Partitioned Sink", "Part_Sink").Replace(" ", "").ToUpper()))
        {
          return source;
        }
      }

      if (name.Contains("Hierarchical Sink"))
      {
        if (source.Name.Replace(" ", "").ToUpper().Contains(name.Replace(" ", "").ToUpper()) ||
            source.Name.Replace(" ", "").ToUpper()
              .Contains(name.Replace("Hierarchical Sink", "Hier_Sink").Replace(" ", "").ToUpper()))
        {
          return source;
        }
      }

      if (source.Name.Replace(" ", "").ToUpper().Contains(name.Replace(" ", "").ToUpper()))
      {
        return source;
      }
    }

    return null;
  }
}

Fetch features and network attributes from a utility network during trace

private void FetchFeaturesAndAttributes(UtilityNetwork utilityNetwork)
{
  using (TraceManager traceManager = utilityNetwork.GetTraceManager())
  using (UtilityNetworkDefinition utilityNetworkDefinition = utilityNetwork.GetDefinition())
  using (NetworkSource deviceNetworkSource = GetNetworkSource(utilityNetworkDefinition, "GasDevice") as NetworkSource)
  using (FeatureClass distributionDeviceFeatureClass = utilityNetwork.GetTable(deviceNetworkSource) as FeatureClass)
  using (FeatureClassDefinition distributionDeviceDefinition = distributionDeviceFeatureClass.GetDefinition())
  using (AssetGroup deviceAssetGroup = deviceNetworkSource.GetAssetGroup("Regulator"))
  using (AssetType deviceAssetType = deviceAssetGroup.GetAssetType("Pressure Reducing"))
  using (NetworkAttribute deviceStatusNetworkAttribute = utilityNetworkDefinition.GetNetworkAttribute("DeviceStatus"))
  using (NetworkAttribute accessibleNetworkAttribute = utilityNetworkDefinition.GetNetworkAttribute("Accessible"))
  {
    // Domain and tier information
    DomainNetwork domainNetwork = utilityNetworkDefinition.GetDomainNetwork("Gas");
    Tier pipeDistributionSystemTier = domainNetwork.GetTier("Pipe Distribution");

    // Start elements
    Element startingPoint1 = utilityNetwork.CreateElement(deviceAssetType, Guid.Parse("{28CF437E-950C-41B7-B839-8BC45570DE40}"));
    Element startingPoint2 = utilityNetwork.CreateElement(deviceAssetType, Guid.Parse("{63C22828-7BC9-49ED-A14A-A596559B6CB3}"));

    startingPoint1.Terminal = startingPoint1.AssetType.GetTerminalConfiguration().Terminals.First(x => x.IsUpstreamTerminal);
    startingPoint2.Terminal = startingPoint2.AssetType.GetTerminalConfiguration().Terminals.First(x => x.IsUpstreamTerminal);

    List<Element> startingPoints = new List<Element>() { startingPoint1, startingPoint2 };
    List<Element> barriers = new List<Element>();

    // Set up trace filter: DeviceStatus = Open (1) AND Accessible = 1
    NetworkAttributeComparison statusNetworkAttributeComparison = new NetworkAttributeComparison(deviceStatusNetworkAttribute, Operator.Equal, 1);
    NetworkAttributeComparison networkAttributeComparison = new NetworkAttributeComparison(accessibleNetworkAttribute, Operator.Equal, 1);
    
    // Set trace configuration 
    TraceConfiguration traceConfiguration = new TraceConfiguration
    {
      AllowIndeterminateFlow = true,
      IgnoreBarriersAtStartingPoints = false,
      IncludeBarriersWithResults = true,
      IncludeContainers = true,
      IncludeContent = true,
      IncludeIsolatedFeatures = false,
      IncludeUpToFirstSpatialContainer = false
    };

    traceConfiguration.Filter.Barriers = new And(statusNetworkAttributeComparison, networkAttributeComparison);
    traceConfiguration.DomainNetwork = domainNetwork;
    traceConfiguration.SourceTier = pipeDistributionSystemTier;

    // Attribute fields of a network source
    List<string> deviceFields = distributionDeviceDefinition.GetFields().Select(f => f.Name).ToList();

    // Network attributes 
    List<string> networkattributeNames = new List<string>();

    IReadOnlyList<NetworkAttribute> networkAttributes = utilityNetworkDefinition.GetNetworkAttributes();

    foreach (NetworkAttribute networkAttribute in networkAttributes)
    {
      networkattributeNames.Add(networkAttribute.Name);
    }

    // Result Types
    List<ResultType> resultTypeList = new List<ResultType>() { ResultType.Feature };

    // Resutl Options
    ResultOptions resultOptions = new ResultOptions()
    {
      IncludeGeometry = true,
      NetworkAttributes = networkattributeNames,
      ResultFields = new Dictionary<NetworkSource, List<string>>() { { deviceNetworkSource, deviceFields } }
    };

    // Trace Arguments
    TraceArgument traceArgument = new TraceArgument(startingPoints)
    {
      Barriers = barriers,
      Configuration = traceConfiguration,
      ResultTypes = resultTypeList,
      ResultOptions = resultOptions
    };

    // Tracer 
    ConnectedTracer connectedTracer = traceManager.GetTracer<ConnectedTracer>();

    // Async trace result
    IReadOnlyList<Result> traceResults = connectedTracer.Trace(traceArgument, ServiceSynchronizationType.Asynchronous);

    // Iterate trace results
    foreach (Result traceResult in traceResults)
    {
      if (traceResult is FeatureElementResult featureElementResult)
      {
        IReadOnlyList<FeatureElement> featureElements = featureElementResult.FeatureElements;
      }
    }
  }
  // Helper inline function
  NetworkSource GetNetworkSource(UtilityNetworkDefinition unDefinition, string name)
  {
    IReadOnlyList<NetworkSource> allSources = unDefinition.GetNetworkSources();
    foreach (NetworkSource source in allSources)
    {
      if (name.Contains("Partitioned Sink"))
      {
        if (source.Name.Replace(" ", "").ToUpper().Contains(name.Replace(" ", "").ToUpper()) ||
            source.Name.Replace(" ", "").ToUpper()
              .Contains(name.Replace("Partitioned Sink", "Part_Sink").Replace(" ", "").ToUpper()))
        {
          return source;
        }
      }

      if (name.Contains("Hierarchical Sink"))
      {
        if (source.Name.Replace(" ", "").ToUpper().Contains(name.Replace(" ", "").ToUpper()) ||
            source.Name.Replace(" ", "").ToUpper()
              .Contains(name.Replace("Hierarchical Sink", "Hier_Sink").Replace(" ", "").ToUpper()))
        {
          return source;
        }
      }

      if (source.Name.Replace(" ", "").ToUpper().Contains(name.Replace(" ", "").ToUpper()))
      {
        return source;
      }
    }

    return null;
  }
}

Requirements

Target Platforms: Windows 11, Windows 10

ArcGIS Pro version: 3.2 or higher.

Reference

Tracer Class
Tracer Members
Overload List

Send feedback