Working with topology errors

Accessing a topology

Accessing a topology can be done using several methods. Determining which method to use is largely a function of your working environment. If you are accessing a topology and its properties in ArcGIS Engine or another stand-alone application, the ITopologyContainer interface is preferable. If you are obtaining a reference to a topology in ArcMap, you have the following two options:

Obtain a reference to a topology via its TopologyLayer in the table of contents (TOC). This method is useful if you only want to interrogate the topology (outside an edit session).
If you are inside an edit session, you can obtain a reference using the TopologyExtension class found in the EditorExt assembly. This determines the topology against which the current editing tools are operating. This method is preferable if you are developing tools or commands to extend the ArcMap editing environment.

See the following code example:

[C#]


        UID topoUiD = new UIDClass();
topoUiD.Value = "esriEditorExt.TopologyExtension";
ITopologyExtension topologyExt = m_application.FindExtensionByCLSID(topoUiD)as
    ITopologyExtension;
ITopology topology;
topology = topologyExt.CurrentTopology as ITopology;

[VB.NET]


        Dim topoUiD As UID = New UIDClass
topoUiD.Value = "esriEditorExt.TopologyExtension"
Dim topologyExt As ITopologyExtension = CType(m_application.FindExtensionByCLSID(topoUiD), ITopologyExtension)
Dim topology As ITopology
topology = CType(topologyExt.CurrentTopology, ITopology)

Finding topology errors

Once you have a reference to a topology, you can access topology errors associated with the topology. The geodatabase provides a set of methods to query the topology errors according to specific characteristics, such as topology rule or error shape type. These methods are available on the IErrorFeatureContainer interface.

In the following code example, the set of topology errors associated with the must not have gaps topology rule are returned. When passing in a null envelope, it retrieves errors for the entire topology that match the search criteria.

[C#]


        IGeoDataset geoDS = topology as IGeoDataset;
IErrorFeatureContainer errorContainer = topology as IErrorFeatureContainer;
IEnumTopologyErrorFeature eErrorFeat;
eErrorFeat = errorContainer.get_ErrorFeaturesByRuleType(geoDS.SpatialReference,
    esriTopologyRuleType.esriTRTAreaNoGaps, null, true, false);
ITopologyErrorFeature topoError;
topoError = eErrorFeat.Next();

[VB.NET]


        Dim geoDS As IGeoDataset = CType(topology, IGeoDataset)
Dim errorContainer As IErrorFeatureContainer = CType(topology, IErrorFeatureContainer)
Dim eErrorFeat As IEnumTopologyErrorFeature
eErrorFeat = errorContainer.get_ErrorFeaturesByRuleType(geoDS.SpatialReference, esriTopologyRuleType.esriTRTAreaNoGaps, Nothing, True, False)
Dim topoError As ITopologyErrorFeature
topoError = eErrorFeat.Next

Selecting topology errors

When inside an edit session, you can manage a set of selected (active) topology errors. This selection is reflected in the Error Inspector and is typically the set of errors used when applying a topology fix. For example, you might want to write a fix to delete all features associated with a must be larger than cluster tolerance topology rule. If you want to clear the current set of active errors, and add those topology errors you retrieved using a query, you can determine the selected errors in the topology using the ITopologyExtension.ActiveError property.

When selecting several topology errors, consider using ITopologyExtension.DelayEvents to avoid notifying clients of the error selection changes until you have finished.

See the following code example:

[C#]


        //Clear the currently selected errors and add the errors returned via query.
topologyExt.ClearActiveErrors(esriTEEventHint.esriTENone);

//Delay firing error selection events until all errors are added.
topologyExt.DelayEvents(true);

while ((topoError = eErrorFeat.Next()) != null)
{
    topologyExt.AddActiveError(topoError, esriTEEventHint.esriTENone);
}

//Fire error selection event.
topologyExt.DelayEvents(false);

[VB.NET]


        ' Clear the currently selected errors and add the errors returned via query.
topologyExt.ClearActiveErrors(esriTEEventHint.esriTENone)

'Delay firing error selection events until all errors are added.
topologyExt.DelayEvents(True)

While Not ((topoError = eErrorFeat.Next) Is Nothing)
    topologyExt.AddActiveError(topoError, esriTEEventHint.esriTENone)
End While

'Fire error selection event.
topologyExt.DelayEvents(False)

Interrogating topology errors

A topology error is a special type of geodatabase feature with a set of unique properties that define the features that result in the topology error, along with their geometry characteristics. This information is particularly useful when evaluating a specific topology error in preparation for understanding and correcting the underlying condition that caused the topology error. When correcting errors, you cannot modify the topology error directly. You must indirectly do so by updating the features that make up the topology error.

In many cases, you might want to update the geometry of the features that created the topology error. One method of providing this type of functionality is to write a command and associate it with a particular topology error, so it is available on the topology error context menu to all users when that error is selected. This provides a simple, efficient way to correct common problems.

Manipulating topology errors

Another common situation is when you have a series of topology errors that need to be flagged as exceptions to the rule. In this case, you can change the properties of a topology error and save your edit back to the geodatabase. It is always important to encapsulate any updates to features (including topology errors) inside an edit session and edit operation.

When updating features associated with an error, provide an appropriate esriTEEventHint. This ensures events that are fired contain additional information that can help clients listening to that event determine the appropriate course of action. See the following code example:

[C#]


        ITopologyRuleContainer topoRuleCont = topology as ITopologyRuleContainer;
editor.StartOperation();

for (int i = 0; i < topologyExt.ActiveErrorCount; i++)
{
    topoError = topologyExt.get_ActiveError(i);

    if (!topoError.IsException)
    {
        topoRuleCont.PromoteToRuleException(topoError);
    }

}

editor.StopOperation("Mark errors as exceptions");

[VB.NET]


        Dim topoRuleCont As ITopologyRuleContainer = CType(topology, ITopologyRuleContainer)
editor.StartOperation()

Dim i As Integer
For i = 0 To topologyExt.ActiveErrorCount - 1
    topoError = topologyExt.get_ActiveError(i)
    
    If Not topoError.IsException Then
        topoRuleCont.PromoteToRuleException(topoError)
    End If
    
Next i

editor.StopOperation("Mark errors as exceptions")

Additional Requirements

The code examples assume you are inside an edit session containing a geodatabase topology with a no gaps rule.
The code examples assume your project includes references to Editor, EditorExt, and Geodatabase assemblies.

Development licensing	Deployment licensing
ArcGIS for Desktop Advanced	ArcGIS for Desktop Standard
ArcGIS for Desktop Standard	ArcGIS for Desktop Advanced