Download Revit 2013 API Developer Guide - The Building Coder

SetTransactionFinalizer
A finalizer is an interface, which, if provided, can be used to perform a custom action at the end of a transaction. Note that it is not invoked when the Commit() or RollBack()
methods are called, but only after the process of committing or rolling back is completed. Transaction finalizers must implement the ITransactionFinalizer interface, which
requires two functions to be defined:
• OnCommitted - called at the end of committing a transaction
• OnRolledBack - called at the end of rolling back a transaction
Note that since the finalizer is called after the transaction has finished, the document is not modifiable from the finalizer unless a new transaction is started.
Getting Element Geometry and AnalyticalModel
After new elements are created or elements are modified, regeneration and auto-joining of elements is required to propagate the changes throughout the model. Without
a regeneration (and auto-join, when relevant), the Geometry property and the AnalyticalModel for Elements are either unobtainable (in the case of creating a new element)
or they may be invalid. It is important to understand how and when regeneration occurs before accessing the Geometry or AnalyticalModel of an Element.
Although regeneration and auto-join are necessary to propagate changes made in the model, it can be time consuming. It is best if these events occur only as often as
necessary.
Regeneration and auto-joining occur automatically when a transaction that modifies the model is committed successfully, or whenever the Document.Regenerate() or
Document.AutoJoinElements() methods are called. Regenerate() and AutoJoinElements() may only be called inside an open transaction. It should be noted that the
Regeneration() method can fail, in which case the RegenerationFailedException will be thrown. If this happens, the changes to the document need to be rolled back by
rolling back the current transaction or subtransaction.
For more details about the AnalyticalModel object, refer to AnalyticalModel in Revit Structure. For more details about the Geometry property, refer to Geometry.
The following sample program demonstrates how a transaction populates these properties:
Code Region 23-3: Transaction populating Geometry and AnalyticalModel properties
public void TransactionDuringElementCreation(UIApplication uiApplication, Level level)
{
Autodesk.Revit.DB.Document document = uiApplication.ActiveUIDocument.Document;
// Build a location line for the wall creation
XYZ start = new XYZ(0, 0, 0);
XYZ end = new XYZ(10, 10, 0);
Autodesk.Revit.DB.Line geomLine =
uiApplication.Application.Create.NewLineBound(start, end);
// To create a wall, a transaction must be first started
Transaction wallTransaction = new Transaction(document, "Creating wall");
if (wallTransaction.Start() == TransactionStatus.Started)
{
// Create a wall using the location line
Wall wall = Wall.Create(document, geomLine, level.Id, true);
// the transaction must be committed before you can
// get the value of Geometry and AnalyticalModel.
if (wallTransaction.Commit() == TransactionStatus.Committed)
{
Autodesk.Revit.DB.Options options =
uiApplication.Application.Create.NewGeometryOptions();
Autodesk.Revit.DB.GeometryElement geoelem = wall.get_Geometry(options);
AnalyticalModel analyticalmodel = wall.GetAnalyticalModel();
}
}
}
The transaction timeline for this sample is as follows:
Figure 134: Transaction timeline
Temporary transactions
It is not always required to commit a transaction. The transaction framework also allows for Trasactions to be rolled back. This is useful when there is an error during the
processing of the transaction, but can also be leverage directly as a technique to create a temporary transaction.
Using a temporary transaction can be useful for certain types of analyses. For example, an application looking to extract geometric properties from a wall or other object
before it is cut by openings should use a temporary transaction in conjunction with Document.Delete(). When the application deletes the elements that cut the target
elements, the cut element’s geometry is restored to its original state (after the document has been regenerated).
To use a temporary transaction:
1. Instantiate the Transaction using the Transaction constructor, and assign it a name.
2. Call Transaction.Start()
3. Make the temporary change(s) to the document (element modification, deletion or creation)
4. Regenerate the document
5. Extract the desired geometry and properties
6. Call Transaction.RollBack() to restore the document to the previous state.
This technique is also applicable to SubTransactions.