ArcObjects Library Reference  (NetworkAnalysis)    

NetworkLoader CoClass

A container for specifying the parameters for building a geometric network.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Extended Error Information

Use the ISupportErrorInfo method InterfaceSupportsErrorInfo to determine if the object supports extended error information. If the object supports extended error info, VC++ developers should use the OLE/COM IErrorInfo interface to access the ErrorInfo object. Visual Basic developers should use the global error object Err to retrieve this extended error information.

Interfaces

Interfaces Description
INetworkLoader Provides access to members used to create a new geometric network.
INetworkLoader2 Provides access to members that specify parameters for creating a new geometric network.
INetworkLoaderProps Provides access to memebers that return the default names of fields and domains used by the network loader.
ISupportErrorInfo Indicates whether a specific interface can return Automation error objects.

Event Interfaces

Interfaces Description
INetworkLoaderProgress (default) Provides access to events that occur when building a geometric network using a NetworkLoader object.

Remarks

Building a geometric network is a very delicate process.  The NetworkLoader object assumes that you have exclusive access to the target feature dataset.  If you do not, then errors in the building process can occur and can result in possible data corruption.  We highly recommend that you use the Build Geometric Network Wizard in ArcCatalog to build your geometric network.  The main reason is that the Build Geometric Network Wizard automatically checks for other users accessing the data and locks the feature dataset during the building process for you.

If you do decide to create your own geometric network building tool using the NetworkLoader object, we strongly recommend that you thoroughly test your tool on scrap copies of data before attempting to use it on non-recoverable data.

[C#]

To build a geometric network using the NetworkLoader object in C# you first need to create the object.  Since INetworkLoader2 inherits from INetworkLoader, we can access the methods from both interfaces by declaring a single INetworkLoader2 variable.

INetworkLoader2 networkLoader2 = new NetworkLoaderClass() as INetworkLoader2;

At this point you can start specifying the parameters of how you want your geometric network built.

Feature Dataset Name
A geometric network is built within a feature dataset. The NetworkLoader needs a reference to the FeatureDatasetName object in which you want to build the geometric network.  The featureDatasetName variable in the code below is a reference to the IFeatureDatasetName interface.

networkLoader2.FeatureDatasetName = featureDatasetName;

Network Name
You need to give your geometric network a name. The name of the geometric network must be unique within the geodatabase. If you only have one geometric network in your feature dataset you might choose to give it the same name as that of the feature dataset.

networkLoader2.NetworkName = "water";

Type of Network
A network can be on of two types: utility or street. To build a utility network you would specify the following:

networkLoader2.NetworkType = esriNTUtilityNetwork;

Snapping
When a geometric network is built, how the features are connected is determined by their spatial relationship. You might know for instance that your line features are exactly located but your point features are not. In this case you would want to specify that your point features should be snapped. Your line features would stay in the same position but the coordinates of your points would be changed to match with the line features. If you select more than one feature class to be snapped then the mean coordinate is computed.

Snap Tolerance
The snap tolerance controls the search distance used for establishing connectivity during the network building process. The snap tolerance is specified in map units.

The following code shows you how to specify your snap tolerance as the value in the Double variable mySnapTol.  Before setting the snap tolerance, it is best to check to make sure that the snap tolerance you propose is not less than the minimum snap tolerance in the MinSnapTolerance parameter.

if (mySnapTol < networkLoader2.MinSnapTolerance)
{
Console.WriteLine("The proposed snap tolerance " + dMySnapTol +
" is less than the minimum snap tolerance of " +
networkLoader2.MinSnapTolerance + " for this feature dataset.");
return;
}
networkLoader2.SnapTolerance = mySnapTol;

Adding Feature Classes
A geometric network is built from feature classes. These feature classes must be contained within the feature dataset you specify. There are a few restrictions on which feature classes you can use. They must be either lines or points. They must not already be participating in a geometric network. In the case of SDE, they must not be registered as versioned.  You can check for any of these violations by calling the CanUseFeatureClass method.

networkLoader2.AddFeatureClass("FeatureClassName", esriFTSimple, null, isSnapped);

The NetworkLoader object can only build geometric networks with simple junction features, simple edge features, and complex edge features. You can look at the help for the INetworkFeature interfacefor more information on these types of features.

Adding Weights
You can also specify weights to be added to your network. To learn more about weights see the NetWeight object help.

networkLoader2.AddWeight("WeightName", esriWeightType, BitGateSize);

For weights other than type esriWTBitGate, the BitGateSize parameter should be set to zero.

Adding Weight Associations
The weights you specified for your network need to have values. These values are taken from attributes of your feature classes. Adding weight associations tells the network which attributes belong to which weights. A weight can be associated with multiple feature classes. These associations are dependent on the type of field and the type of weight you created. For example, a weight of type esriWTDouble can only be associated with a field of type esriFieldTypeDouble. For weights of type esriWTBitGate, the type of the field can be either esriFieldTypeInteger or esriFieldTypeSmallInteger.

networkLoader2.AddWeightAssociation("WeightName", "FeatureClassName", "FieldName");

Ancillary Roles
You also need to specify which feature classes will have an ancillary role. A feature class that you specify as having an ancillary role means its features can either be sources or sinks and it will determine flow in your network. The feature classes you want to be built as having an ancillary role must be point feature classes. Multiple feature classes in the network can have ancillary roles. To do this, simply call the PutAncillaryRole method for each feature class to have ancillary roles.

The field name you specify will contain the ancillary role attribute for this feature class. It is strongly recommended to use the default name for the ancillary role field. The default name for the ancillary role field can be obtained from the DefaultAncillaryRoleField property on the INetworkLoaderProps interface. If you specify an existing field to use as the ancillary role field, it is best to check that this field is of the correct type and domain can become an ancillary role field. You can check this by calling the CheckAncillaryRoleField method. If the field specified does not exist, then the NetworkLoader will automatically add it to the feature class when it builds the network, populating all values in this field with the value 0. The following code demonstrates using the default ancillary role field name and checking the ancillary role field before calling PutAncillaryRole:

INetworkLoaderProps networkLoaderProps = networkLoader2 as INetworkLoaderProps;
string defARFld = networkLoaderProps.DefaultAncillaryRoleField;
esriNetworkLoaderFieldCheck ckFld = networkLoader2.CheckAncillaryRoleField("FeatureClassName", defARFld);
switch (ckFld)
{
case esriNLFCValid:
case esriNLFCNotFound:
networkLoader2.PutAncillaryRole("FeatureClassName", esriNCARSourceSink, defARFld);
break;
default:
Console.WriteLine("The field " + defARFld + " could not be used as an ancillary role field.");
return;
break;
}

Enabled/Disabled Field
Every feature class in your network must have a field that determines whether a feature is enabled or disabled. Enabled and disabled features affect how flow and the trace results are determined.

It is strongly recommended to use the default name for the enabled/disabled field. If you do not make a call to PutEnabledDisabledFieldName for a feature class, then the NetworkLoader assumes that you wish to use the default name for the enabled/disabled field. The default name for the enabled/disabled field can be obtained from the DefaultEnabledField property on the INetworkLoaderProps interface.

If you specify an existing field to use as the enabled/disabled field, it is best to check that this field is of the correct type and domain to be used as an enabled/disabled field. You can check this by calling the CheckEnabledDisabledField method. You also have the option of resetting all values in the existing field to True, or preserving the existing values. See the help for the PreserveEnabledValues property for more details.

If the field specified does not exist, then the NetworkLoader will automatically add it to the feature class when it builds the network, populating all values in this field with the value True. The following code demonstrates using the default enabled/disabled field name and checking the enabled/disabled field before calling PutEnabledDisabledFieldName (See the Note below). It also sets the PreserveEnabledValues property to True:

INetworkLoaderProps networkLoaderProps = pNetworkLoader2 as INetworkLoaderProps;
string defEDFld = networkLoaderProps.DefaultEnabledField;
esriNetworkLoaderFieldCheck ckFld = networkLoader2.CheckEnabledDisabledField("FeatureClassName", defEDFld);
switch(ckFld)
{
case esriNLFCValid:
case esriNLFCNotFound:
networkLoader2.PutEnabledDisabledFieldName("FeatureClassName", "EnabledDisabledName");
break;
default:
Console.WriteLine("The field " + defEDFld + " could not be used as an enabled/disabled field.");
return;
break;
}
networkLoader2.PreserveEnabledValues = true;

Note: In reality, this code (with exception to the call to PreserveEnabledValues) would not be necessary, since in the absence of calls to PutEnabledDisabledFieldName for a feature class, the NetworkLoader assumes that you wish to use the default enabled/disabled field for that feature class. The code is provided here for illustrative purposes.

Configuration Keyword
If you specified a feature dataset that is a member of an SDE geodatabase, then you may specify a configuration keyword for building your geometric network. A configuration keyword is used to specify storage and location parameters for optimal space and disk location efficiency. The configuration keyword is provided by your database administrator.

networkLoader2.ConfigurationKeyword = "myConfigKeyword";

Build Your Network
Finally, after specifying all of the parameters for your network you need to tell the NetworkLoader object to build it. You can do this by calling the LoadNetwork method.

networkLoader2.LoadNetwork();
[C++]
[Visual Basic 6.0]

To build a geometric network using the NetworkLoader object in Visual Basic you first need to create the object.  Since INetworkLoader2 inherits from INetworkLoader, we can access the methods from both interfaces by declaring a single INetworkLoader2 variable.

Dim pNetworkLoader2 As INetworkLoader2
Set pNetworkLoader2 = New NetworkLoader

At this point you can start specifying the parameters of how you want your geometric network built.

Feature Dataset Name
A geometric network is built within a feature dataset. The NetworkLoader needs a reference to the FeatureDatasetName object in which you want to build the geometric network.  The pFeatureDatasetName variable in the code below is a reference to the IFeatureDatasetName interface.

Set pNetworkLoader2.FeatureDatasetName = pFeatureDatasetName

Network Name
You need to give your geometric network a name. The name of the geometric network must be unique within the geodatabase. If you only have one geometric network in your feature dataset you might choose to give it the same name as that of the feature dataset.

pNetworkLoader2.NetworkName = "water"

Type of Network
A network can be on of two types: utility or street. To build a utility network you would specify the following:

pNetworkLoader2.NetworkType = esriNTUtilityNetwork

Snapping
When a geometric network is built, how the features are connected is determined by their spatial relationship. You might know for instance that your line features are exactly located but your point features are not. In this case you would want to specify that your point features should be snapped. Your line features would stay in the same position but the coordinates of your points would be changed to match with the line features. If you select more than one feature class to be snapped then the mean coordinate is computed.

Snap Tolerance
The snap tolerance controls the search distance used for establishing connectivity during the network building process. The snap tolerance is specified in map units.

The following code shows you how to specify your snap tolerance as the value in the Double variable dMySnapTol.  Before setting the snap tolerance, it is best to check to make sure that the snap tolerance you propose is not less than the minimum snap tolerance in the MinSnapTolerance parameter.

If dMySnapTol < pNetworkLoader2.MinSnapTolerance Then
MsgBox "The proposed snap tolerance " & dMySnapTol & _
" is less than the minimum snap tolerance of " & _
pNetworkLoader2.MinSnapTolerance & " for this feature dataset."
Exit Sub
End If
pNetworkLoader2.SnapTolerance = dMySnapTol

Adding Feature Classes
A geometric network is built from feature classes. These feature classes must be contained within the feature dataset you specify. There are a few restrictions on which feature classes you can use. They must be either lines or points. They must not already be participating in a geometric network. In the case of SDE, they must not be registered as versioned.  You can check for any of these violations by calling the CanUseFeatureClass method.

pNetworkLoader2.AddFeatureClass "FeatureClassName", esriFTSimple, Nothing, bIsSnapped

The NetworkLoader object can only build geometric networks with simple junction features, simple edge features, and complex edge features. You can look at the help for the INetworkFeature interface for more information on these types of features.

Adding Weights
You can also specify weights to be added to your network. To learn more about weights see the NetWeight object help.

pNetworkLoader2.AddWeight "WeightName", esriWeightType, BitGateSize

For weights other than type esriWTBitGate, the BitGateSize parameter should be set to zero.

Adding Weight Associations
The weights you specified for your network need to have values. These values are taken from attributes of your feature classes. Adding weight associations tells the network which attributes belong to which weights. A weight can be associated with multiple feature classes. These associations are dependent on the type of field and the type of weight you created. For example, a weight of type esriWTDouble can only be associated with a field of type esriFieldTypeDouble. For weights of type esriWTBitGate, the type of the field can be either esriFieldTypeInteger or esriFieldTypeSmallInteger.

pNetworkLoader2.AddWeightAssociation "WeightName", "FeatureClassName", "FieldName"

Ancillary Roles
You also need to specify which feature classes will have an ancillary role. A feature class that you specify as having an ancillary role means its features can either be sources or sinks and it will determine flow in your network. The feature classes you want to be built as having an ancillary role must be point feature classes. Multiple feature classes in the network can have ancillary roles. To do this, simply call the PutAncillaryRole method for each feature class to have ancillary roles.

The field name you specify will contain the ancillary role attribute for this feature class. It is strongly recommended to use the default name for the ancillary role field. The default name for the ancillary role field can be obtained from the DefaultAncillaryRoleField property on the INetworkLoaderProps interface. If you specify an existing field to use as the ancillary role field, it is best to check that this field is of the correct type and domain can become an ancillary role field. You can check this by calling the CheckAncillaryRoleField method. If the field specified does not exist, then the NetworkLoader will automatically add it to the feature class when it builds the network, populating all values in this field with the value 0. The following code demonstrates using the default ancillary role field name and checking the ancillary role field before calling PutAncillaryRole:

Dim pNetworkLoaderProps As INetworkLoaderProps, sDefARFld As String
Dim eCkFld As esriNetworkLoaderFieldCheck
Set pNetworkLoaderProps = pNetworkLoader2
sDefARFld = pNetworkLoaderProps.DefaultAncillaryRoleField
eCkFld = pNetworkLoader2.CheckAncillaryRoleField("FeatureClassName", sDefARFld)
Select Case eCkFld
Case esriNLFCValid, esriNLFCNotFound
pNetworkLoader2.PutAncillaryRole "FeatureClassName", esriNCARSourceSink, sDefARFld
Case Else
MsgBox "The field " & sDefARFld & " could not be used as an ancillary role field."
Exit Sub
End Select

Enabled/Disabled Field
Every feature class in your network must have a field that determines whether a feature is enabled or disabled. Enabled and disabled features affect how flow and the trace results are determined.

It is strongly recommended to use the default name for the enabled/disabled field. If you do not make a call to PutEnabledDisabledFieldName for a feature class, then the NetworkLoader assumes that you wish to use the default name for the enabled/disabled field. The default name for the enabled/disabled field can be obtained from the DefaultEnabledField property on the INetworkLoaderProps interface.

If you specify an existing field to use as the enabled/disabled field, it is best to check that this field is of the correct type and domain to be used as an enabled/disabled field. You can check this by calling the CheckEnabledDisabledField method. You also have the option of resetting all values in the existing field to True, or preserving the existing values. See the help for the PreserveEnabledValues property for more details.

If the field specified does not exist, then the NetworkLoader will automatically add it to the feature class when it builds the network, populating all values in this field with the value True. The following code demonstrates using the default enabled/disabled field name and checking the enabled/disabled field before calling PutEnabledDisabledFieldName (See the Note below). It also sets the PreserveEnabledValues property to True:

Dim pNetworkLoaderProps As INetworkLoaderProps, sDefEDFld As String
Dim eCkFld As esriNetworkLoaderFieldCheck
Set pNetworkLoaderProps = pNetworkLoader2
sDefEDFld = pNetworkLoaderProps.DefaultEnabledField
eCkFld = pNetworkLoader2.CheckEnabledDisabledField("FeatureClassName", sDefEDFld)
Select Case eCkFld
Case esriNLFCValid, esriNLFCNotFound
pNetworkLoader2.PutEnabledDisabledFieldName "FeatureClassName", "EnabledDisabledName"
Case Else
MsgBox "The field " & sDefEDFld & " could not be used as an enabled/disabled field."
Exit Sub
End Select
pNetworkLoader2.PreserveEnabledValues = True

Note: In reality, this code (with exception to the call to PreserveEnabledValues) would not be necessary, since in the absence of calls to PutEnabledDisabledFieldName for a feature class, the NetworkLoader assumes that you wish to use the default enabled/disabled field for that feature class. The code is provided here for illustrative purposes.

Configuration Keyword
If you specified a feature dataset that is a member of an SDE geodatabase, then you may specify a configuration keyword for building your geometric network. A configuration keyword is used to specify storage and location parameters for optimal space and disk location efficiency. The configuration keyword is provided by your database administrator.

pNetworkLoader2.ConfigurationKeyword = "myConfigKeyword"

Build Your Network
Finally, after specifying all of the parameters for your network you need to tell the NetworkLoader object to build it. You can do this by calling the LoadNetwork method.

pNetworkLoader2.LoadNetwork
[Visual Basic .NET]

To build a geometric network using the NetworkLoader object in VB.NET you first need to create the object.  Since INetworkLoader2 inherits from INetworkLoader, we can access the methods from both interfaces by declaring a single INetworkLoader2 variable.

Dim networkLoader2 As INetworkLoader2 = New NetworkLoader

At this point you can start specifying the parameters of how you want your geometric network built.

Feature Dataset Name
A geometric network is built within a feature dataset. The NetworkLoader needs a reference to the FeatureDatasetName object in which you want to build the geometric network.  The featureDatasetName variable in the code below is a reference to the IFeatureDatasetName interface.

networkLoader2.FeatureDatasetName = featureDatasetName

Network Name
You need to give your geometric network a name. The name of the geometric network must be unique within the geodatabase. If you only have one geometric network in your feature dataset you might choose to give it the same name as that of the feature dataset.

networkLoader2.NetworkName = "water"

Type of Network
A network can be on of two types: utility or street. To build a utility network you would specify the following:

networkLoader2.NetworkType = esriNTUtilityNetwork

Snapping
When a geometric network is built, how the features are connected is determined by their spatial relationship. You might know for instance that your line features are exactly located but your point features are not. In this case you would want to specify that your point features should be snapped. Your line features would stay in the same position but the coordinates of your points would be changed to match with the line features. If you select more than one feature class to be snapped then the mean coordinate is computed.

Snap Tolerance
The snap tolerance controls the search distance used for establishing connectivity during the network building process. The snap tolerance is specified in map units.

The following code shows you how to specify your snap tolerance as the value in the Double variable mySnapTol.  Before setting the snap tolerance, it is best to check to make sure that the snap tolerance you propose is not less than the minimum snap tolerance in the MinSnapTolerance parameter.

If mySnapTol < networkLoader2.MinSnapTolerance Then
Console.WriteLine("The proposed snap tolerance " & mySnapTol & _
" is less than the minimum snap tolerance of " & _
networkLoader2.MinSnapTolerance & " for this feature dataset.")
Exit Sub
End If
networkLoader2.SnapTolerance = mySnapTol

Adding Feature Classes
A geometric network is built from feature classes. These feature classes must be contained within the feature dataset you specify. There are a few restrictions on which feature classes you can use. They must be either lines or points. They must not already be participating in a geometric network. In the case of SDE, they must not be registered as versioned.  You can check for any of these violations by calling the CanUseFeatureClass method.

networkLoader2.AddFeatureClass("FeatureClassName", esriFTSimple, Nothing, isSnapped)

The NetworkLoader object can only build geometric networks with simple junction features, simple edge features, and complex edge features. You can look at the help for the INetworkFeature interface for more information on these types of features.

Adding Weights
You can also specify weights to be added to your network. To learn more about weights see the NetWeight object help.

networkLoader2.AddWeight("WeightName", esriWeightType, BitGateSize)

For weights other than type esriWTBitGate, the BitGateSize parameter should be set to zero.

Adding Weight Associations
The weights you specified for your network need to have values. These values are taken from attributes of your feature classes. Adding weight associations tells the network which attributes belong to which weights. A weight can be associated with multiple feature classes. These associations are dependent on the type of field and the type of weight you created. For example, a weight of type esriWTDouble can only be associated with a field of type esriFieldTypeDouble. For weights of type esriWTBitGate, the type of the field can be either esriFieldTypeInteger or esriFieldTypeSmallInteger.

networkLoader2.AddWeightAssociation("WeightName", "FeatureClassName", "FieldName")

Ancillary Roles
You also need to specify which feature classes will have an ancillary role. A feature class that you specify as having an ancillary role means its features can either be sources or sinks and it will determine flow in your network. The feature classes you want to be built as having an ancillary role must be point feature classes. Multiple feature classes in the network can have ancillary roles. To do this, simply call the PutAncillaryRole method for each feature class to have ancillary roles.

The field name you specify will contain the ancillary role attribute for this feature class. It is strongly recommended to use the default name for the ancillary role field. The default name for the ancillary role field can be obtained from the DefaultAncillaryRoleField property on the INetworkLoaderProps interface. If you specify an existing field to use as the ancillary role field, it is best to check that this field is of the correct type and domain can become an ancillary role field. You can check this by calling the CheckAncillaryRoleField method. If the field specified does not exist, then the NetworkLoader will automatically add it to the feature class when it builds the network, populating all values in this field with the value 0. The following code demonstrates using the default ancillary role field name and checking the ancillary role field before calling PutAncillaryRole:

Dim networkLoaderProps As INetworkLoaderProps = CType(networkLoader2, INetworkLoaderProps)
Dim defARFld As String = networkLoaderProps.DefaultAncillaryRoleField
Dim ckFld As esriNetworkLoaderFieldCheck = networkLoader2.CheckAncillaryRoleField("FeatureClassName", defARFld)
Select Case ckFld
Case esriNLFCValid, esriNLFCNotFound
networkLoader2.PutAncillaryRole("FeatureClassName", esriNCARSourceSink, defARFld)
Case Else
Console.WriteLine("The field " & defARFld & " could not be used as an ancillary role field.")
Exit Sub
End Select

Enabled/Disabled Field
Every feature class in your network must have a field that determines whether a feature is enabled or disabled. Enabled and disabled features affect how flow and the trace results are determined.

It is strongly recommended to use the default name for the enabled/disabled field. If you do not make a call to PutEnabledDisabledFieldName for a feature class, then the NetworkLoader assumes that you wish to use the default name for the enabled/disabled field. The default name for the enabled/disabled field can be obtained from the DefaultEnabledField property on the INetworkLoaderProps interface.

If you specify an existing field to use as the enabled/disabled field, it is best to check that this field is of the correct type and domain to be used as an enabled/disabled field. You can check this by calling the CheckEnabledDisabledField method. You also have the option of resetting all values in the existing field to True, or preserving the existing values. See the help for the PreserveEnabledValues property for more details.

If the field specified does not exist, then the NetworkLoader will automatically add it to the feature class when it builds the network, populating all values in this field with the value True. The following code demonstrates using the default enabled/disabled field name and checking the enabled/disabled field before calling PutEnabledDisabledFieldName (See the Note below). It also sets the PreserveEnabledValues property to True:

Dim networkLoaderProps As INetworkLoaderProps = CType(pNetworkLoader2, INetworkLoaderProps)
Dim defEDFld As String = networkLoaderProps.DefaultEnabledField
Dim ckFld As esriNetworkLoaderFieldCheck = networkLoader2.CheckEnabledDisabledField("FeatureClassName", defEDFld)
Select Case ckFld
Case esriNLFCValid, esriNLFCNotFound
networkLoader2.PutEnabledDisabledFieldName("FeatureClassName", "EnabledDisabledName")
Case Else
Console.WriteLine("The field " & defEDFld & " could not be used as an enabled/disabled field.")
Exit Sub
End Select
networkLoader2.PreserveEnabledValues = True

Note: In reality, this code (with exception to the call to PreserveEnabledValues) would not be necessary, since in the absence of calls to PutEnabledDisabledFieldName for a feature class, the NetworkLoader assumes that you wish to use the default enabled/disabled field for that feature class. The code is provided here for illustrative purposes.

Configuration Keyword
If you specified a feature dataset that is a member of an SDE geodatabase, then you may specify a configuration keyword for building your geometric network. A configuration keyword is used to specify storage and location parameters for optimal space and disk location efficiency. The configuration keyword is provided by your database administrator.

networkLoader2.ConfigurationKeyword = "myConfigKeyword"

Build Your Network
Finally, after specifying all of the parameters for your network you need to tell the NetworkLoader object to build it. You can do this by calling the LoadNetwork method.

networkLoader2.LoadNetwork()

Working with Events

[Visual Basic 6.0]

When working with NetworkLoader's default outbound interface in Visual Basic 6 declare variables as follows:

Private WithEvents pNetworkLoader as NetworkLoader