How to create an edit session

Summary
This topic discusses approaches for creating edit sessions, including the use of edit operations in an ArcGIS Engine application, with emphasis on the use of the EngineEditor singleton object.

Starting an edit session

An edit session is started by calling the IEngineEditor.StartEditing method with two arguments—IMap and IWorkspace. Every editable layer from the same workspace that is in the map can be edited in the edit session. The IEngineEditLayers.IsEditable property indicates whether a particular layer is editable. When working with SDE workspaces, set IEngineEditor.EditSessionMode to specify whether versioned or non-versioned layers are editable, as it is not possible to edit both types in a single edit session.
The following code example starts an edit session on the workspace of the first feature layer in the map and sets this as the layer to edit:
[C#] 
//Declare the Engine editor at the class level.
private IEngineEditor m_engineEditor = new EngineEditorClass();

private void StartEditing(IMapControl2 m_mapControl)
{
    IMap map = m_mapControl.Map;

    //If an edit session has already been started, exit.
    if (m_engineEditor.EditState != esriEngineEditState.esriEngineStateNotEditing)
        return ;

    //Start editing the workspace of the first feature layer found.
    for (int layerCounter = 0; layerCounter <= map.LayerCount - 1; layerCounter++)
    {
        ILayer currentLayer = map.get_Layer(layerCounter);
        if (currentLayer is IFeatureLayer)
        {
            IFeatureLayer featureLayer = currentLayer as IFeatureLayer;
            IDataset dataset = featureLayer.FeatureClass as IDataset;
            IWorkspace workspace = dataset.Workspace;
            m_engineEditor.StartEditing(workspace, map);
            ((IEngineEditLayers)m_engineEditor).SetTargetLayer(featureLayer);
            break;
        }
    }
}
[VB.NET] 
'Declare the Engine editor at the class level.
Private m_engineEditor As IEngineEditor = New EngineEditorClass()

Public Sub StartEditing(ByVal m_mapControl As IMapControl2)
    
    Dim map As IMap = m_mapControl.Map
    
    'If an edit session has already been started, exit.
    If m_engineEditor.EditState <> esriEngineEditState.esriEngineStateNotEditing Then
        Return
    End If
    
    'Start editing the workspace of the first feature layer found.
    Dim layerCounter As Integer
    For layerCounter = 0 To map.LayerCount - 1 Step layerCounter + 1
        Dim currentLayer As ILayer = map.Layer(layerCounter)
        If TypeOf currentLayer Is IFeatureLayer Then
            Dim featureLayer As IFeatureLayer = CType(currentLayer, IFeatureLayer)
            Dim dataset As IDataset = CType(featureLayer.FeatureClass, IDataset)
            Dim workspace As IWorkspace = dataset.Workspace
            m_engineEditor.StartEditing(workspace, map)
            (CType(m_engineEditor, IEngineEditLayers)).SetTargetLayer(featureLayer)
            Exit For
        End If
    Next
End Sub
The Start Editing command (ControlsEditingStartCommand) works in a similar manner.
Attempting to start an edit session on a workspace already being edited by the same application results in an error and can be checked using the IEngineEditor.EditState property.
When editing, the workspace and map being edited can be obtained using IEngineEditor.EditWorkspace and IEngineEditor.Map properties, respectively.

Performing an edit operation

Perform all edits made in an edit session within an edit operation (provides the ability to undo or redo edits by adding each edit operation onto the operation stack): 
  1. Use the IEngineEditor.StartOperation method to create an edit operation. 
  2. Use error handling and program logic to ensure that any edits made within the operation are valid. If required, IEngineEditor.AbortOperation can be used to cancel the operation.
  3. To finish the edit operation and add it to the operation stack, call IEngineEditor.StopOperation. The string argument allows the operation to be identified on the operation stack and is used as the ToolTip for the Undo and Redo commands.

    The following code example shows how to create an edit operation: 
[C#] 
private void cmdEditOperation()
{
    m_engineEditor.StartOperation()

    try
    {
        //Perform feature edits here.
        //.....   
        if (someEditValidationChecksMethod == true)
        {
            m_engineEditor.StopOperation("Test edit operation");
        }
        else
        {
            m_engineEditor.AbortOperation();
        }
    }
    catch (Exception ex)
    {
        m_engineEditor.AbortOperation();
        //Add code to handle exception.
    }
}
[VB.NET] 
'Abort the operation.

Private Sub cmdEditOperation()
    
    m_engineEditor.StartOperation()
    
    Try
    'Perform feature edits here.
    '.....
    If someEditValidationChecksMethod = True Then
        m_engineEditor.StopOperation("Test edit operation")
    Else
        m_engineEditor.AbortOperation()
    End If
    Catch ex As Exception
    m_engineEditor.AbortOperation()
    'Add code to handle exception.
    End Try
    
End Sub
Edit operations cannot be nested. Calling IEngineEditor.StartOperation within another edit operation causes an error.
IEngineEditEvents.OnBeforeStopOperation can analyze edits made before the edit operation is committed to the geodatabase. The operation will already be committed when the IEngineEditEvents.OnStopOperation event fires.

Saving an edit session

Edits made during the edit session can be saved by executing ControlsEditingSaveCommand. Alternatively, call IEngineEditor.StopEditing with the saveChanges argument set to true followed by IEngineEditor.StartEditing to continue with the edit session.

Stopping an edit session

Edits made within the edit session are held in memory. Stopping the edit session saves changes to disk or rollbacks the entire transaction to the state before editing started. In both cases, the operation stack is cleared of all edit and sketch operations.
The following code example stops an edit session and prompts the user to save edits if any changes have been made:
[C#] 
private void btnStopEditing_Click(object sender, EventArgs e)
{
    if (m_EngineEditor.HasEdits() == false)
        m_EngineEditor.StopEditing(false);
    else
    {
        if (MessageBox.Show("Save Edits?", "Save Prompt", MessageBoxButtons.YesNo) 
            == DialogResult.Yes)
            m_EngineEditor.StopEditing(true);
        else
            m_EngineEditor.StopEditing(false);
    }
}
[VB.NET] 
Private Sub btnStopEditing_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnStopEditing.Click
    If (m_EngineEditor.HasEdits() = False) Then
        m_EngineEditor.StopEditing(False)
    Else
        If (MessageBox.Show("Save Edits?", "Save Prompt", MessageBoxButtons.YesNo) = DialogResult.Yes) Then
            m_EngineEditor.StopEditing(True)
        Else
            m_EngineEditor.StopEditing(False)
        End If
    End If
End Sub


See Also:

How to create a sketch operation
How to work with the operation stack
How to listen to edit events



Development licensing Deployment licensing
Engine Developer Kit Engine
ArcGIS for Desktop Basic
ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced