ArcGIS Pro 3.3 API Reference Guide
ArcGIS.Core.Data.UtilityNetwork.Trace Namespace / Tracer Class / Trace Method / Trace(TraceArgument) Method
The input arguments to the trace.
Example

In This Topic
    Trace(TraceArgument) Method
    In This Topic
    Executes a trace.
    Syntax
    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
    Remarks
    Derived implementations may impose stronger preconditions. For example, a concrete Tracer implementation may throw a System.ArgumentException if traceArgument 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.
    See Also