Many people ask what a Transaction is. Sounds scary, like you may need your credit card or something, but fear not, they are really very simple. Here I will give a brief overview on what a Transaction is in the context of the RevitAPI and show some worked examples of where you need them.

What is a Transaction and why do we need them?

Transactions are used when you need to modify the Revit Document for any reason, some examples of when you will need them are:-

  • Creating/Moving/Copying/Deleting an Element
  • Modifying Element Parameters
  • Visual Graphics Changes

There are obviously more cases when you will need them but these are just examples.

Consider Transactions to be like sending a parcel, that parcel contains something (or many somethings) important to the recipient, so the sender would want to have the ability to Track, Record & Return those items. This is sort of how Transactions work, you are sending a change to the Revit Document, you want to know that the update has started, what its Status is and if it has reached its destination…and, like most Transactions in the real world, you want to have the ability to say “That’s awful!!! I hate it!” and send it back – This is called a RollBack and after performing a Transaction, that transaction will appear in your Undo History.

Revit API Vs. Dynamo/Python…

The RevitAPI and the TransactionManager in Dynamo do the same thing, however, they are initiated different. The TransactionManager is like a wrapper for the RevitAPI Transactions, this is there to protect Revit when Dynamo crashes and is left in an open Transaction, Dimitar Venkov explains this also here. To show you what I mean let’s compare using Visual Studio or Sharp Develop to write Transactions in C# and then in Dynamo/Python. In C# you write them like this…

using( Transaction t = new Transaction(doc) )
    {
        t.Start();
        Try
        {
           //Make some changes to the Revit Document...
           t.Commit();
        }
        Catch
        {
           //Maybe throw an error message...
           t.Rollback();
        }
    }

and with Dynamo/Python, you would write the equivalent like so…

 import clr
 
 clr.AddReference("RevitServices")
 import RevitServices
 from RevitServices.Persistence import DocumentManager
 from RevitServices.Transactions import TransactionManager
 doc =  DocumentManager.Instance.CurrentDBDocument
 
 clr.AddReference("RevitAPI")
 from Autodesk.Revit.DB import *
 
 TransactionManager.Instance.EnsureInTransaction(doc)
 st = SubTransaction()
 st.Start()
 try:            
     #Make some changes to the Revit Document...
     st.Commit()
 except:
     #Maybe Throw an Error Message...
     st.RollBack()
 TransactionManager.Instance.TransactionTaskDone()

Note: for the Dynamo/Python example I have included the references to the RevitAPI as the purpose is not to show you how to do it in C# but in Dynamo/Python.

You do not need to create SubTransactions in Dynamo/Python. In fact, in most cases you won’t and just let the TransactionManager handle it, so we could just use the following…

 import clr
 
 clr.AddReference("RevitServices")
 import RevitServices
 from RevitServices.Persistence import DocumentManager
 from RevitServices.Transactions import TransactionManager
 doc =  DocumentManager.Instance.CurrentDBDocument
 
 clr.AddReference("RevitAPI")
 from Autodesk.Revit.DB import *
 
 TransactionManager.Instance.EnsureInTransaction(doc)
 try:            
     #Make some changes to the Revit Document...
 except:
     #Maybe Throw an Error Message...
 TransactionManager.Instance.TransactionTaskDone()

You may notice the try/except statements, these are quite important when using Transactions (and coding in general), you want to avoid having failures where you can help it and being able to report what has Passed/Failed.

Examples

Some examples of using the TransactionManager and Transactions are in these worked examples…

Delete those Elements (with TaskDialog advanced features)…

(More to follow 🙂 )

Advertisement