Trace(TraceArgument,ServiceSynchronizationType) Method

In This Topic

Executes a trace.

Syntax

Visual Basic (Declaration)
C#

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

public abstract IReadOnlyList<Result> Trace( 
   TraceArgument traceArgument,
   ServiceSynchronizationType serviceSynchronizationType
)

Parameters

traceArgument: The input arguments to the trace.
serviceSynchronizationType: Specifies which implementation of the service endpoint to call. This parameter is ignored for non-services based utility networks.

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

Export a utility network trace as a JSON file

{
  // This routine demonstrates how to perform a trace and export the results as a JSON file
  static 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 = [startingPoint1, startingPoint2];
      List<Element> barriers = [];

      // 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

{
  // This routine demonstrates how to fetch features and network attributes from a utility network during a trace
  static 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 Home, Pro, Enterprise (64 bit)

ArcGIS Pro version: 3.2 or higher.

Reference

Tracer Class
Tracer Members
Overload List

Send feedback