Namespace: Autodesk.Revit.DB Class: Transaction

Transaction.Start(String)

Method

Description:
Starts the transaction with an assigned name.

Remarks:

A transaction may be started only after it was instantiated or after it was previously committed or rolled back.

Be aware that every time a transaction starts, Failure Handling Options will be reset to their default values. If a specific failure handling is required, programmers need to use SetFailureHandlingOptions(FailureHandlingOptions) before the transaction is committed or rolled back.

Syntax

public TransactionStatus Start(
	string name
)

Public Function Start ( 
	name As String
) As TransactionStatus

public:
TransactionStatus Start(
	String^ name
)

member Start : 
        name : string -> TransactionStatus

Examples

public bool TransactionBoundaries(Autodesk.Revit.DB.Document document)
{
    bool result = false;

    // All and any transaction should be enclosed in a 'using'
    // block or guarded within a try-catch-finally blocks
    // to guarantee that a transaction does not out-live its scope.
    using (Transaction transaction = new Transaction(document))
    {
       transaction.Start("Transaction name");

       // some modification of the document here, likely resulting in 
       // changes of the 'result' value
       // ..... 

       if (result == true)
       {
          // Modifications ended successfully, but it is still possible
          // for the transaction to fail due to model regeneration
          // (and other internal processes that validate the model)
          if (TransactionStatus.Committed != transaction.Commit())
          {
             result = false;
          }
       }
       else  // if modifications failed, transaction is to be rolled back
       {
          transaction.RollBack();
       }
    }
    return result;
}

Public Function TransactionBoundaries(document As Autodesk.Revit.DB.Document) As Boolean
    Dim result As Boolean = False

    ' All and any transaction should be enclosed in a 'using'
    ' block or guarded within a try-catch-finally blocks
    ' to guarantee that a transaction does not out-live its scope.
    Using transaction As New Transaction(document)
        transaction.Start("Transaction name")

        ' some modification of the document here, likely resulting in 
        ' changes of the 'result' value
        ' ..... 

        If result = True Then
            ' Modifications ended successfully, but it is still possible
            ' for the transaction to fail due to model regeneration
            ' (and other internal processes that validate the model)
            If TransactionStatus.Committed <> transaction.Commit() Then
                result = False
            End If
        Else
            ' if modifications failed, transaction is to be rolled back
            transaction.RollBack()
        End If
    End Using
    Return result
End Function

Parameters

Parameter	Type	Description
name	String	Name of the transaction; If the transaction already has name, this new one will preplace it. The name will appear on the Undo menu in Revit if the transaction is successfully committed.

Return Value

Type	Description
TransactionStatus	If finished successfully, this method returns TransactionStatus.Started. Note that unless starting is successful, changes cannot be made to the document.

Exceptions

Exception	Condition
ArgumentException	The name argument is an empty string.
ArgumentNullException	A non-optional argument was null
InvalidOperationException	Cannot modify the document for either a read-only external command is being executed, or changes to the document are temporarily disabled. -or- The transaction's document is currently in failure mode. No transaction operations are permitted until failure handling is finished. -or- The transaction started already and has not been completed yet. -or- Starting a new transaction is not permitted. It could be because another transaction already started and has not been completed yet, or the document is in a state in which it cannot start a new transaction (e.g. during failure handling or a read-only mode, which could be either permanent or temporary).