Managing edit sessions and edit operations

Summary

This topic discusses the best approaches to manage edit sessions and use edit operations to add, update, or insert rows in the geodatabase.

About managing edit sessions and edit operations

The editor is a thin client to the geodatabase. Many of the methods exposed on the editor class map closely to those available on the workspace. See the following table for examples:

	IEditor	IWorkspaceEdit
Start an edit session	StartEditing	StartEditing
Stop an edit session	StopEditing	StopEditing
Start an edit operation	StartOperation	StartEditOperation
Stop an edit operation	StopOperation	StopEditOperation
Abort an edit operation	AbortOperation	AbortEditOperation
Rollback an edit operation	UndoOperation	UndoEditOperation
Reapply an edit operation	RedoOperation	RedoEditOperation
Commit edits	StopEditing(True)	StopEditing(True)

When writing an extension to ArcMap, while editor methods in many cases call the geodatabase methods internally, these should not be used in place of editor methods, nor should they be used interchangeably. Editor methods often perform additional logic, which includes firing appropriate events, managing selections, and handling editor related user interface (UI) components, such as the Attributes dialog box, and so on.

Starting an edit session

Inside ArcMap, the editor allows a single editable workspace at any given time, which is referred to as the edit workspace or current workspace. This condition is enforced across all data frames (maps) in the current map document. Before starting an edit session, ensure that another workspace in the map is not already being edited. See the following code example:

[C#]


        public bool StartEditing(ESRI.ArcGIS.Geodatabase.IWorkspace workspaceToEdit)
{
    //Get a reference to the editor.
    UID uid = new UIDClass();
    uid.Value = "esriEditor.Editor";
    IEditor editor = m_application.FindExtensionByCLSID(uid)as IEditor;

    //Check to see if a workspace is already being edited.
    if (editor.EditState == esriEditState.esriStateNotEditing)
    {
        editor.StartEditing(workspaceToEdit);
        return true;
    }
    else
    {
        return false;
    }
}

[VB.NET]


        Public Function StartEditing(ByVal workspaceToEdit As ESRI.ArcGIS.Geodatabase.IWorkspace) As Boolean
    'Get a reference to the editor.
    Dim uid As UID
    uid = New UIDClass()
    uid.Value = "esriEditor.Editor"
    Dim editor As IEditor
    editor = CType(m_application.FindExtensionByCLSID(uid), IEditor)
    
    'Check to see if a workspace is already being edited.
    If editor.EditState = esriEditState.esriStateNotEditing Then
        editor.StartEditing(workspaceToEdit)
        Return True
    Else
        Return False
    End If
End Function

Saving edits

Most editor methods for managing an edit session have a direct correlation to geodatabase methods. This is also true from the Editor's UI with the exception of the Save Edits command. In this case, the Editor's Save Edits command calls IWorkspaceEdit.StopEditing(True) and IWorkspaceEdit.StartEditing internally.

The geodatabase guarantees the reference to a row object is maintained for the lifetime of the edit session. It does not guarantee the reference to the row is maintained across the edit session boundary. Because the editor is technically stopping one edit session and starting another when the Save Edits command is executed, any references you have to geodatabase objects should be reacquired inside the new edit session. For more information, see IWorkspaceEdit.

Working with edit operations

Enclose edits to rows inside an edit operation. Doing so allows the operation to be added to the operation stack, which provides undo and redo capability for the edit. Some types of features require updates be done inside an edit session, including features that participate in a geometric network or topology.

In addition to managing the life span of edit operations, and providing undo and redo capabilities, the editor provides additional opportunities for you to respond to an operation-related events. One useful event to view and process changes before they are committed is IEditEvents2.BeforeStopOperation. As a developer, this gives you an opportunity to perform preliminary analysis on changes that occurred inside the edit operation before committing that operation to the geodatabase. This differs from IEditEvents2.OnStopOperation in that by the time you receive notification that StopOperation has executed, the operation is committed to the geodatabase. Currently, there is no opportunity to abort the edit operation. Do not call AbortOperation inside any editor event, including BeforeStopOperation.

Nested edit operations

ArcGIS does not support nested edit operations. At ArcGIS 9.1 or earlier, if you called IEditor.StartOperation a second time before calling IEditor.StopOperation on the first operation, the system closed the first operation before executing the second StartOperation call. Starting with ArcGIS 9.2, this behavior was changed requiring the user to close the current edit operation before starting a new edit operation; otherwise, an exception is thrown. See the following code example:

[C#]


        private void EditOperationTest(IEditor m_editor)
{

    //Start first edit operation.
    m_editor.StartOperation();

    //Do some work.
    // ...
    //End work.

    //Start second edit operation before closing the first; throws an exception.
    m_editor.StartOperation();

}

[VB.NET]


        Private Sub EditOperationTest(ByVal m_editor As IEditor)
    
    'Start first edit operation.
    m_editor.StartOperation()
    
    'Do some work.
    ' ...
    'End work.
    
    'Start second edit operation before closing the first.
    m_editor.StartOperation()
    
End Sub

For this reason, minimize the code executed between the StartOperation and StopOperation calls to improve code readability and minimize the likelihood of starting a nested edit operation. You can also determine if you are already inside an edit operation. The following code example shows how you can check the edit operation's state:

[C#]


        private void EditOperation(IEditor m_editor)
{
    //Check to see if you are in an operation.
    IWorkspaceEdit2 workspaceEdit = (IWorkspaceEdit2)m_editor.EditWorkspace;

    if (!workspaceEdit.IsInEditOperation)
    {
        // Close the first operation.
        m_editor.StopOperation("edit");
    }
}

[VB.NET]


        Private Sub EditOperation(ByVal m_editor As IEditor)
    
    'Check to see if you are in an operation.
    Dim workspaceEdit As IWorkspaceEdit2 = CType(m_editor.EditWorkspace, IWorkspaceEdit2)
    
    If (Not workspaceEdit.IsInEditOperation) Then
        ' Close the first operation.
        m_editor.StopOperation("edit")
    End If
    
End Sub

Nonversioned editing sessions

The geodatabase supports versioned and nonversioned edit sessions. The editor also supports both edit session types. Not all feature classes can be edited in a nonversioned edit session. For more information regarding nonversioned editing limitations, see also the geodatabase documentation on Editing with the geodatabase API.

For nonversioned edit sessions, one consideration is handling attributes with NOT NULL or UNIQUE value constraints. The editor supports updating attributes before storing the feature, allowing you to update attributes that can violate a NOT NULL or UNIQUE constraint for fields on that feature.

This behavior can be applied to all editable feature classes or to specific feature classes through the IEditAttributeProperties interface. The following code example defines that the input feature class should have attributes updated before storing the feature:

[C#]


        private void AddClass(IEditor m_editor, IFeatureClass featureClass)
{
    IEditAttributeProperties editAttributeProps = (IEditAttributeProperties)m_editor;

    // Attribute new features before commit.
    editAttributeProps.NonversionedAttributionEnabled = true;

    // Do this for specific feature classes.
    editAttributeProps.AttributeEditAll = false;

    // If no classes are specified, return null.
    if (editAttributeProps.AttributeEditClasses == null)
    {
        editAttributeProps.AttributeEditClasses = new SetClass();
        editAttributeProps.AttributeEditClasses.Add(featureClass);
        return ;
    }

    // Otherwise, see if the class exists and add it.
    if (editAttributeProps.AttributeEditClasses.Count == 0 ||
        !editAttributeProps.AttributeEditClasses.Find(featureClass))
    {
        editAttributeProps.AttributeEditClasses.Add(featureClass);
    }
}

[VB.NET]


        Private Sub AddClass(ByVal m_editor As IEditor, ByVal featureClass As IFeatureClass)
    
    Dim editAttributeProps As IEditAttributeProperties = CType(m_editor, IEditAttributeProperties)
    
    ' Attribute new features before commit.
    editAttributeProps.NonversionedAttributionEnabled = True
    
    ' Do this for specific feature classes.
    editAttributeProps.AttributeEditAll = False
    
    ' If no classes are specified, return null.
    If editAttributeProps.AttributeEditClasses Is Nothing Then
        editAttributeProps.AttributeEditClasses = New SetClass()
        editAttributeProps.AttributeEditClasses.Add(featureClass)
        Return
    End If
    
    ' Otherwise, see if the class exists and add it.
    If editAttributeProps.AttributeEditClasses.Count = 0 OrElse (Not editAttributeProps.AttributeEditClasses.Find(featureClass)) Then
        editAttributeProps.AttributeEditClasses.Add(featureClass)
    End If
    
End Sub

To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):

ESRI.ArcGIS.Editor
ESRI.ArcGIS.Geodatabase
ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)

Additional Requirements

The code examples in this topic require that your project include references to the editor and geodatabase assemblies.

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