Revit APP Blog

New interfaces have been added to the API related to Transactions. These interfaces will provide a more comprehensive set of options for managing changes being made to the Revit document.

At this time, the new transaction interfaces are not compatible with the automatically-opened transactions created around ExternalCommand callbacks and VSTA macros. So, Autodesk recommends that you not use these interfaces until compatible changes have been made to those frameworks. In order to experiment with the new interfaces, a document needs to be opened or created while in an external command. In the new document, either the old transaction interfaces or the new ones can be used, as long as they are not used together in the same document.

There are three main classes among the new interfaces plus a few supporting classes. The main classes represent three different (but related) transaction contexts.

Transaction — a context required in order to make any changes to a Revit model. Only one transaction can be open at a time; nesting is not allowed. Each transaction must have a name, which will be listed on the Undo menu in Revit once a transaction is successfully submitted.

SubTransaction — can be used to enclose a set of model modifying commands. Sub-transactions are optional. They are not required in order to modify the model. They are a convenience tool to allow logical splitting of larger tasks into smaller ones. Sub-transaction can only be created within an already opened transaction and must be closed (either committed or rolled back) before the transaction is closed (committed or rolled back). Unlike transactions, sub-transaction may be nested, but any nested sub-transaction must be closed before the enclosing sub-transaction is closed. Sub-transactions do not have name, for they do not appear on the Undo menu in Revit.

Transaction group — allows grouping together several independent transactions, which gives the owner of a group an opportunity to treat many transactions at once. When a transaction group is to be closed, it can be rolled back, which means that all already submitted transactions will be rolled back at once. If not rolled back, a group can be either submitted or assimilated. In the former case, all submitted transactions (within the group) will be left as they were. In the later case, transactions within the group will be merged together into one single transaction that will bear the group’s name. A transaction group can only be started when there is no transaction open yet, and must be closed only after all enclosed transactions are closed (rolled back or committed). Transaction groups can be nested, but any nested group must be closed before the enclosing group is closed. Transaction groups are optional. They are not required in order to make modifications to a model.

All three transaction objects share some common methods:

Besides having the GetStatus returning the current status, both Commit and RollBack methods also return a status indicating whether or not the method was successful. Available status values include:

The new Transaction interfaces replace the old APIs:

• Document.BeginTransaction()
• Document.EndTransaction()
• Document.AbortTransaction()

which have been removed from the API.

Working in 3D view is different from working in plan view or section view, usually we need to specify a workplane for those actions that only valid for some plan, for example: add a dimension. Create a sketch plan is relative simple, just need to specify an origin and normal to create a plane and pass the plane to the sketchplane constructor. The View has a read&write property SketchPlane to let user specify a sketch plane for 3D view. Code like following:

XYZ vZ = new XYZ(0,0, 1);
XYZ ptCenter = new XYZ(0, 0, 0);
Plane plane = application.Create.NewPlane(vZ, ptCenter);
SketchPlane sketchPlane = uidocument.Create.NewSketchPlane(plane);
view.SketchPlane = sketchPlane;

Just notice that the origin is not so important, so for most cases, you can use the universe origin (0,0,0). And remember to set the sketchplane back after you use is a good habit, like following:

SketchPlane oldSketchPlane = view.SketchPlane
view.SketchPlane = newSketchPlane;
// … Do some work
view.SketchPlane = oldSketchPlane;

External Command Object Lifetime

When no other command or edit modes are active within Autodesk Revit, the registered external command will become enabled. When picked, the command object will be created and the Execute method called. Once this method returns back to Autodesk Revit the command object will be destroyed. Due to this destruction, data cannot persist within the object between command executions. If you wish the data to persist you may use an external file or database to do so.  If you wish the data to persist within the Autodesk Revit project you may use the shared parameters mechanism to store this data.

External Application Object Lifetime

When Autodesk Revit starts, the external application object will be created and the OnStartup method called. Once this method returns back successfully to Autodesk Revit the external application object will be held during the entire Autodesk Revit session. The OnShutdown method will be called when Autodesk Revit shuts down.

One Point:

So if you want to share some data between commands during the Revit session, there is another way: store the data in the external application class.