The Building Coder

External Command Replay

Matt Mason of Avatech Solutions pointed out a few important items related to the preceding post on replaying a journal file:

One topic that you did not cover – using the journal file with Revit external commands.

Here are some things that I've noticed in the past:

• If your external command has dialog boxes, your application will freeze if Revit is being driven by a journal.
• The alternative to this is to use the JournalData StringStringMap in the ExternalCommandData which is passed to you.
  • You can read values from the StringStringMap and use them instead of your dialog boxes.
  • You can write the values at the end of your command – based on what the user selected – so that your existing commands can be played back.
• When last I looked at it (2009?) there were problems playing back your command if it included calls to select elements using PickOne or WindowSelect.

Thank you Matt for these valuable hints!

Solar Radiation Technology Preview

A Solar Radiation Technology Preview for Revit is now available on the Autodesk Labs site. Scott Sheppard provides some additional background information on this as well.

Journal File Replay

In spite of pretty mixed weather I went on a climb in the alps with my friend Robert on Saturday, the route Kurze Kombination (4c) on the mountain Schmalstöckli (2012 m) close to the Lidernenen Hütte.

Here I am after the climb, just below the summit:

And this is Robert on the summit itself:

We would made another climb on the same mountain if the weather had not been pretty grey and moist. Anyway, now it is Monday morning, and I am back again to Revit programming.

We mentioned the Revit journal file repeatedly in previous posts, but a basic introduction to this topic was still missing. There is a good reason for this, because Autodesk does not provide any official support for the usage of journal files as a means of automating a portion of the design or production process. The only official support for journal files is as a replay mechanism for testing or reporting issues. One can make use of the journaling mechanism totally at one's own risk, and there will almost certainly be changes, incompatibilities between versions, and other problems.

The testing and reporting mechanism provided by the journaling mechanism is fully accessible to Revit add-ins as well. This access is demonstrated by the Revit SDK Journaling sample. Anyone interested in making use of journaling for any purpose whatsoever should have a good look at this sample in order to understand the mechanism in more depth.

Being unsupported, the journaling mechanism should be used only as a last resort. One example of a preferable approach for some tasks is to prompt the user instead.

Still, with some imagination and due to the lack of automation support for driving Revit from outside or invoking Revit commands such as the IFC export programmatically, it does sometimes offer interesting possibilities.

All the uses mentioned above are related to driving Revit by replaying an existing or an automatically generated journal file. Another way of using the journal file is to read out its contents dynamically during an on-going session to find out what is going on. I mentioned an idea to determine the last Revit command from it, and Greg Wesner discussed getting the journal file path for other monitoring purposes.

Here are some recent questions on this topic, one of which lead to me finally putting together an example and proving to myself that a journal file can be used pretty reliably to drive a completely encapsulated sequence of commands, including Revit start up and shutdown. But first, let us look at a negative result.

Question: Is it possible to play back a Revit journal file while Revit is already running and a document is already opened?

Answer: Sorry, I am not aware of any way to play back a journal file in the middle of a running session, with an opened document. The only way I know of using journal files for programmatic purposes is to include the entire sequence of starting up Revit, opening the document, executing the desired action, and closing down Revit again within the journal file execution. You may possibly omit the closing down part, in which case Revit will be left open, if you are willing to give up control to the user at that point.

Here is the question that led me to test running Revit from a journal file and including steps in it which provide me API access for additional control during the replay process:

Question: Is it possible to use the Revit API to create a new family within the OnStartup method of an external application?

Answer: The argument provided to OnStartup is a ControlledApplication instance. This object provides methods to manipulate the ribbon, access the shared parameters file, access some application level properties and set up application level event handler.

It does not include access to the documents. That access is provided by the Documents collection on the Application class, which is provided as an argument to external commands, which are only active after OnStartup has completed and a document has been opened.

If you wish to start up Revit and immediately create a new family document, you can do so once manually and save the journal file that is generated by this interaction. The journal file can then later be used to restart Revit and re-execute this process.

If you wish to continue working programmatically with the new family document, you can set up an event handler for the DocumentCreated or DocumentOpened notification.

Some notes on external applications and document event handling are provided by the blog entries:

• External application OnStartup implementation in VB.
• External application implementing automatic synchronisation using document save and close events.
• Transactions and document modification in a DocumentOpened event handler.
• Document modification in the DocumentClosing event handler.
• Programmatic handling of dialogue box events.

Following this suggestion to implement an external application reacting to an event to programmatically process a newly created family file created by driving Revit from a journal file led to the following new question:

Question: I have created a journal file that opens a family document on Revit start up. However, it issues an error when calling my external application's OnStartup method saying "The journal file could not be run to completion."

Answer: I cannot reproduce the problem you describe. In my experience, the message that the journal file could not run to completion is due to other problems. I do not believe it is caused by the event handler registration. To test this, I implemented a new external application AutoExecuteOnOpen which does what you say, registering event handlers for the DocumentCreated and DocumentOpened events in the OnStartup method. Both of these simply print a message to the Visual Studio debug output window:

public IExternalApplication.Result OnStartup(
  ControlledApplication a )
{
  a.DocumentCreated 
    += new EventHandler<DocumentCreatedEventArgs>( 
      a_DocumentCreated );
 
  a.DocumentOpened 
    += new EventHandler<DocumentOpenedEventArgs>( 
      a_DocumentOpened );
 
  return IExternalApplication.Result.Succeeded;
}
 
public IExternalApplication.Result OnShutdown(
  ControlledApplication a )
{
  a.DocumentCreated
    -= new EventHandler<DocumentCreatedEventArgs>(
      a_DocumentCreated );
 
  a.DocumentOpened
    -= new EventHandler<DocumentOpenedEventArgs>(
      a_DocumentOpened );
 
  return IExternalApplication.Result.Succeeded;
}
 
void a_DocumentCreated( 
  object sender, 
  DocumentCreatedEventArgs e )
{
  Debug.Print( "DocumentCreated" );
}
 
void a_DocumentOpened( 
  object sender, 
  DocumentOpenedEventArgs e )
{
  Debug.Print( "DocumentOpened" );
}

I registered this external application in Revit.ini.

I then ran through the following sequence and saved the resulting journal file:

• Start up Revit.
• Open a family document.
• Close the family document.
• Shut down Revit.

These steps resulted in a new journal file:

C:\Program Files\Autodesk Revit Architecture 2010\Journals\journal.0180.txt

I saved this journal file for replay and had no problem rerunning it. It executes all the following expected steps without problems:

• Start up Revit.
• Load the external application.
• Open a family document.
• Fire the DocumentOpened event.
• Print the message.
• Close the family document.
• Shut down Revit.

In the first attempt at implementing my external application event handlers, I displayed a message box. This did not work, at least not when run from the debugger, because clicking OK in the message box had no effect, so the journal file execution was blocked at that point. Replacing the message box by a simple Debug.Print statement solved that problem. This shows that the entire execution process is very sensitive and picky, though.

Here is a copy of my journal file and here the entire Visual Studio solution AutoExecuteOnOpen

Export Family Instance to gbXML

The Green Building XML Schema or gbXML was developed to facilitate the transfer of building information stored in CAD building information models, enabling interoperability between building design models and a wide variety of engineering analysis tools. It has been widely adopted by leading CAD vendors and is on the road to becoming a de-facto industry standard schema, so we obviously see more and more application developers interested in using and supporting it, leading to questions such as the following one.

Question: When exporting a Revit MEP model to gbXML, only system families, doors and windows are exported. All other families such as Generic, etc. are missing in the gbXML output. This includes almost all the families that we use as shading devices, which are generic families. How can we resolve this?

Answer: If you launch the export via the API, you can specify certain settings before calling the Export method. Please set ProjectInfo.gbXMLSettings.ExportComplexity to the enumeration value defining the degree of complexity you wish to export. Here are the possible settings, which are documented in the Revit API help file RevitAPI.chm:

• Simple: Curtain Walls and Curtain Systems are exported with one “huge” opening with the total opening area equal to all openings; a curtain wall with 50 panels is exported as 1 opening.
• SimpleWithShadingSurfaces: Export with simple type and shading surfaces.
• Complex: Curtain Walls and Curtain Systems are exported with several openings, panel by panel; a curtain wall with 50 panels is exported as 50 openings.
• ComplexWithShadingSurfaces: Include complex type and shading surfaces.
• ComplexWithMullionsAndShadingSurfaces: Include complex type, shading surfaces and mullion. Mullions in Curtain Walls and Systems are exported as shading surfaces. A "simplified" analytical shading surface is produced from a mullion based on its centerline, thickness and offset.

Unfortunately, none of these settings actually cause the generic family instances to be included in the export.

After testing all ExportComplexity cases via the user interface settings for Export Complexity, I see that none of them export generic family instances.

One option would be to model the devices using system families instead, since the component families are not exported. For example, using a small slab might be a possibility.

Thanks to Joe Ye for handling this case.

Two typical Problems

I just handled two cases with typical recurring problems that I would like to remind everybody to watch out for:

• Use modal dialogues.
• Set Copy Local to False.

Use modal dialogues

You should always use modal dialogues in your Revit external command, unless you really know what you are doing. Otherwise, you may quickly run into problems:

Question: I am trying to load a type symbol and am having issues with it. The method returns true indicating that the type symbol has been loaded, but it does not show up anywhere in the Revit user interface. For instance, I am loading a window type from a family that has never been loaded before. I would expect to see it in the Revit user interface afterwards, however it is not there. Right now we have to cancel the family browser and reset the project browser for the family or type to load. I am pretty sure that we are getting our wires crossed.

Answer: I looked at your sample application, and yes, I can tell you what the problem is. Crossed wires is actually a pretty apt description. This is your application execution sequence:

• The command is launched.
• The dialogue box is displayed. It is modeless, so it remains visible forever or until explicitly closed.
• The command terminates and returns IExternalCommand.Result.Succeeded.
• The user interacts with the dialogue, for instance by pushing the 'Begin Test' button.

Unfortunately, in the last step, you are no longer in a context in which the Revit API will allow you to interact with it in any way, because your command has already terminated.

Please use a modal dialogue instead, and do not return from the command until your use of the Revit API is concluded. When you return, the transaction that Revit manages for your command is terminated. Your return code of Succeeded, Failed or Cancelled determines whether the transaction is committed or aborted.

Some hints on modal versus modeless dialogues are discussed in the posts on driving Revit from outside and using modeless dialogues. More information on the automatic transaction handling performed by Revit for your external command is discussed in the introduction to transactions, transaction responsibility and the document IsModified property.

Set Copy Local to False

Always ensure that the Copy Local flag on your application's reference to the RevitAPI.dll assembly in your Visual Studio project is set to false, as described in the post on the document IsModified property. I still keep seeing cases where this flag is left in its default setting of True.

Host Reference

Still enjoying my climbing and sunshine holiday with my sons in Avignon. Yesterday we went climbing and exploring the cliffs or 'calanque' of Cassis, east of Marseille (more images):

Besides climbing, swimming in the Gard river and Mediterranean Sea, and blogging now and then, my sons are also artistically active:

Returning to the Revit API, however: We already touched on the relationship between a host and its hosted elements in some previous posts. The first such topic was the relationship inverter, making use of the explicit property providing a reference to the host of hosted elements such as doors, windows and other family instances. Since this property only specifies the relationship in one direction, we implemented the relationship inverter to obtain the inverse references.

No such explicit property is provided in either direction in the association between a tag and the tagged element, and that discussion mentions four ideas for possible workarounds instead.

Here is another question on a similar topic, the relationship between a wall and its wall footing:

Question: How can I obtain a reference to a wall footing from the wall attached to it? And vice versa, is it possible to obtain a reference to the wall supported by a wall footing?

Answer: As in the case of the tag and the tagged element, the Revit API does not provide any direct access to the link in either direction, neither to get the reference of a wall footing from the wall attached to it or vice versa. The workaround via the Document.Delete method mentioned as one of the four workarounds to determine the association between a tag and the tagged element can be used in this case as well: You call the method to delete the wall. It automatically includes the wall footing in the deletion, and returns the element ids of all deleted objects in an ElementIdSet, from which you can pick out the wall footing. If you encapsulate this operation in a transaction which is aborted after the call, the deletion will not be committed, and you will have obtained the desired information with no changes made to the model. Here is a sample code snippet to implement this:

I added a new command class CmdWallFooting to The Building Coder sample implementing this functionality. Here is the source code of its Execute method:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
ContFooting footing = null;
 
Wall wall = Util.SelectSingleElementOfType( 
  doc, typeof( Wall ), "a wall" ) as Wall;
 
if ( null == wall )
{
  message = "Please select a single wall element.";
}
else
{
  doc.BeginTransaction();
  ElementIdSet delIds = null;
  try
  {
    delIds = doc.Delete( wall );
  }
  catch ( System.Exception )
  {
    message = "Deletion failed.";
    doc.AbortTransaction();
    return CmdResult.Failed;
  }
  doc.AbortTransaction();
 
  foreach ( ElementId id in delIds )
  {
    ElementId refId = id;
    Element elem = doc.get_Element( ref refId );
    if ( null == elem )
      continue;
    footing = elem as ContFooting;
    if ( null != footing )
      break;
  }
}
string s = Util.ElementDescription( wall );
 
Util.InfoMsg( ( null == footing )
  ? string.Format( "No footing found for {0}.", s )
  : string.Format( "{0} has {1}.", s,
    Util.ElementDescription( footing ) ) );
 
return CmdResult.Failed;

This is the result of running the new command on the wall depicted above:

Another efficient workaround has become possible in Revit 2010 by making use of the new API method FindReferencesByDirection. It finds both elements and geometric references that intersect a ray extending in a certain direction from an origin point. The Revit 2010 SDK Samples AvoidObstruction and RaytraceBounce demonstrate the use of this new method. By using a couple of points on the wall footing, we can easily determine which wall is located directly above it, and vice versa as well. This provides a much stronger possibility to the workarounds using general geometric proximity suggested in the post on the tag association.

Here is version 1.1.0.34 of the complete Visual Studio solution with the new command.

Document Modification in an Event

Here is a question raised by Phillip Miller on the topic of the new 2010 events:

Question: I'm having trouble with the DocumentClosing event. I want to set parameters of objects as Revit closes down the document. I'm using element.Parameter("Schedule").Set(nul), but the error says that Revit can't do it outside of the transaction. I tried wrapping the command in a Transaction but that fails as well. I am however using the same code to set parameters on objects during the DocumentOpened event. Any suggestions or can it even be done?

Answer: First, here is some background information on the various document closing events in the Revit 2009 and 2010 APIs.

In 2009, we have the Application.OnDocumentClosed event, to be notified after a document is closed. OnDocumentClosed is marked obsolete in 2010, and we are asked to use the DocumentClosed event instead. The Revit 2009 API also provides the OnClose event on the Document class, to be notified before the current document is closed. This is also marked obsolete in 2010, and replaced by the DocumentClosing event.

In 2010, the Application.DocumentClosing event notifies when Revit is just about to close a document, and DocumentClosed notifies immediately after it has finished closing it. On the Document class, DocumentClosing notifies when Revit is just about to close the document.

The documentation on the Application.DocumentClosing event states that the document may not be modified during this event, so that is probably why your parameter modification is failing.

On the Document.DocumentClosing event, the documentation states that the event is raised when Revit is just about to close the document, and that this document-level event precedes the application-level event of the same name. This event is cancellable, except when it is raised during close of the application. Here again, the document may not be modified during this event.

This seems a bit strange to me, because one reason to want to watch this event might be in order to add some last-minute information to it, such as the parameter modification you are attempting.

Aaah, I just had an idea. When the document is being closed, we can assume that Revit really has finished with it and nothing more can be done, no further modifications applied or saved. If we wish to modify a document, then that only makes sense if the modifications will also be saved. In that case, we do not need to watch out for DocumentClosing, but for DocumentSaving.

In all of the document and application level DocumentSaving and DocumentSavingAs events, the documentation states that the document may be modified during this event.

So the solution to your issue is to use the DocumentSaving and DocumentSavingAs events instead of DocumentClosing, since you actually wish to apply modifications before closing the document.

Further Exploration and Background

After providing the information above, the discussion with Phillip continued, and he provided the following update:

Thank you so much for your quick reply. It was very helpful and unfortunately confirmed for me what I thought was happening. I thought the whole idea of DocumentClosing was that I would be able to do things to the document before it closes?

Essentially what I am doing is passing parameters from Revit objects to a calculator that I have created. It does calculations on the information and then passes the correct information back to Revit and sets the parameters. All this information is then shown in schedules.

What I would like to do: on document closing, set the parameters that our calculator calculates to nothing. Therefore, when a person opens it without our tools, the schedules show with all the correct info except what our calculator calculates. The fields will be blank. When a person opens the document that has our tools installed, the parameters will be recalculated and populated again.

A work around maybe: catch the document closing event, set a project wide variable or maybe a registry entry to False. Then cancel the doc closing and fire up the save event. Catch the save event, and if the variable is False, set all of our parameters to nothing, then close Revit. This time, in the Document Close event, the document will close because the variable is false. Maybe this would work.

Can we through the API save a Revit document and close a Revit document?

Once again thank you so much for taking the time to look at this for me. It is greatly appreciated. I have learnt so much from your blog even though it is in C#.

I have tried calling the Doc.Save() method from within the DocClosing event and guess what. It is disabled. I think the only way I can do this is to always cancel the Document closing and pop up with a message that the user needs to use my close document command where I can set the parameters and then close the document. Not a very nice way of doing things, but it looks as though I will just have to wait and hope that in the 2011 API it is different.

Further Replies

As said, DocumentClosing is sent when the document is closing, but after all changes have been applied. So calling Save from this context is also not possible. I would not bank on this being different in any future releases of the API.

The Revit API does of course allow us to both save and close a document. For instance, the Document class itself provides Save, SaveAs and Close methods. Just not in the closing event, when no more changes are possible.

As repeatedly stated, there should be no difference between having the blog code in C# or VB, since conversion is easy and the features are identical. I am sorry if that makes it harder for you to read, though.

I am absolutely no expert on copy protection, but it all seems a bit dodgy to me. I would hope that you can find some simpler and more streamlined method. Good luck, in any case, and thank you very much Phillip for the interesting discussion!

Tag Association

Unfortunately, the Revit API does not currently provide any direct method to access the tag of a tagged element, and vice versa. Normally, I do not write about things that do not work. In this case, however, we have a couple of suggestions for workarounds. I would love to hear back from you whether you are already using any of the methods described below, or other techniques not described, in spite of the lack of direct API support. So this is the question:

Question: How can I find the tag associated with a given family instance, or the tagged element from a given tag?

I want to find a tag that was associated to a family instance through the API. I can go through the document and find both the family instance and the associated IndependentTag object, but I see no clear link between the two. The IndependentTag has a TagHeadPosition which I can match up with the family instance location, but I would hope there is a more accurate way to determine the relationship. When you delete the family instance, the IndependentTag also gets deleted, so Revit is maintaining some kind of link internally.

Can you tell me how to find the FamilyInstance through the IndependentTag or vice versa?

Answer: Unfortunately, the Revit API does not currently provide any direct method to access the relationship between a tag and the tagged element. Here are some workarounds that we currently suggest:

1. Use Document.Delete() and the ElementIdSet returned.
2. Maintain an association list for programmatically created elements and associated tags.
3. Use the element sequence in the database.
4. Use geometric proximity between the tag and the tagged element.

Here are the detailed descriptions of each of these approaches:

Document.Delete()

Use the Document.Delete() method to temporarily delete the tagged element, and retrieve the affected tag through the ElementIdSet returned.

The tagged element is regarded as a sort of parent object or host of the tag. Therefore, to find the tag of a given tagged element, we can delete the host, which in turn deletes all its tags and other child objects. One of the method overloads of Document.Delete() returns an ElementIdSet with the element ids of all the elements that will be deleted for the specific host element. Since we do not really want to delete any elements at all, we can wrap the deletion call in a transaction, retrieve the ElementIdSet, and abort the transaction and thus the deletion by calling AbortTransaction. This provides a way to access the associated tags of an element. For example, deleting the wall displayed below will return three tags: the wall tag, door tag and window tag. You can check the tag category to determine which one is the wall tag.

Unfortunately, this does not provide any way to access the host element from a given tag.

Association List

If the elements and their associated tags are generated by an application, the application can maintain an internal list of pairs of element ids for both.

Database Element Sequence

When iterating over all database elements, they are returned in the sequential order in which they were added to the database. Normally the door and window tags will follow immediately after the door and window they are attached to. This holds both for elements generated through the user interface, as well as for many API-generated instances.

Geometric Proximity

Collect all family instance elements and tags of the category you are interested in, for instance all doors and door tags, and pair them up by identical level and geometric proximity. That should generate a pretty reliable pairing in all normal cases.

Introducing DevLabs

Kean Walmsley just posted an exciting announcement on the DevLabs we are holding in various Autodesk offices around the world to provide even more direct development support to our partners. The Revit API sessions are in Beijing, China, in August, and in Bangalore, India, in September.

New 2010 Events

The Event API in Revit has been completely rewritten in 2010 to be compliant to the .NET event standard. The old events are still available but have been deprecated. Matt Mason already posted an overview of some of the new event handling features. Transitioning from the old events to the new ones can include some pitfalls, and one has now been uncovered.

Question: My application connects to a database when a project is opened. It uses the following code which is called when a document is opened:

void revitApp_OnDocumentOpened( Document doc )
{
  try {
    doc.BeginTransaction();
    // . . .
    doc.EndTransaction();
  }
  catch (Exception ex)
  {
    MessageBox.Show( ex.Message );
  }
}

In Revit 2009, this occasionally produces the following error message when doc.BeginTransaction() is called, especially when work sharing is enabled in a project: "Attempted to read or write protected memory. This is often an indication that other memory is corrupt." This worked fine in the past. What is going wrong now?

Answer: The OnDocumentOpened event is one of the old pre-2010 events. In these, an API transaction can be started, but it is not guaranteed whether it will be successful or not. This is one reason why the old events have been declared obsolete in 2010. The Revit development team recommends moving on to the new 2010 events instead.

In this case, you can use the application.DocumentOpened event. In this new event, you can modify the document directly without having to call BeginTransaction to open your own transaction. The transaction required has already been created by the event framework before calling the event handler, so the document is immediately modifiable. Thus, the calls to begin, end and abort a transaction are not allowed in the new event handlers and an InvalidOperationException is thrown if one of them is called during the event. Here is what the Revit API documentation on the DocumentOpened event has to say about this:

This event is raised immediately after Revit has finished opening a document. It is raised even when document opening failed or was cancelled (during DocumentOpening event).

Check the 'Status' field in event’s argument to see whether the action itself was successful or not.

This event is not cancellable, for the process of opening document has already been finished.

If the action was successful, the document may be modified during this event. A transaction is already created at the time of the event and will be automatically closed at the end of the event. There is no need to create another transaction during this event and it is, in fact, prohibited.

Please be aware that the following API functions are not available for the current document during this event:

• Close()
• BeginTransaction()
• AbortTransaction()
• EndTransaction()
• Save()
• SaveAs()

Exception InvalidOperationException will be thrown if any of the above methods is called during this event.

The DocumentOpened event is meant to replace the older OnDocumentOpened event, which is now Obsolete.

Many thanks to Saikat Bhattacharya for handling this case!

Revit 2010 API Webcast

Don't forget to register for the upcoming Revit 2010 API webcast Wednesday next week, April 29 2009. The course name is Revit API, the language is English, and the location is 'Webcast'.

Transaction Responsibility

The last post on transactions explained the need to open a transaction of our own before trying to modify a document during an event. That is actually not all. We also need to remember that starting a transaction is not permitted at all times, and also that starting a new transaction or ending one may fail. This leaves us with a certain amount of responsibility. Therefore, we should add some error handling to ensure that failures are handled gracefully. The sample should be amended like this:

void application_OnDocumentNewed( Document doc )
{
  // we cannot modify the document 
  // unless a transaction is started
 
  if( doc.BeginTransaction() )
  {
    // once a new transaction is started
    // we are responsible for ending or 
    // aborting it, so we have to put 
    // everything in a try-catch block
 
    try
    {
      CreateUserDefinedParameters( doc );
 
      // we are responsible for ending 
      // the transaction we started
 
      doc.EndTransaction();
    }
    catch( Exception )
    {
      // if we cannot finish what we wanted
      // we should probably abort the whole thing
 
      doc.AbortTransaction();
      throw; // re-throw the exception
    }
  }
}

Thank you to Arnost Lobel and Harry Mattison for providing this feedback!

I have arrived in Perugia by now ... rather slow progress, but getting there.

Transactions

We recently mentioned the need to open a transaction in an event handler. In that case, the transaction was required in a handler for the document closed and saved events on the application object. Here is another similar case involving the application OnDocumentNewed event.

Question: I am trying to set up some shared parameters on OST_Rooms in a ControlledApplication. I can read and bind values from a shared parameter file, and have checked that the binding is set up correctly for the document. However, when I open the properties of a room, I don't see my parameter there. As a little background, we are creating an application to link to a database which will get and set values in the shared parameters for each room.

Answer: If you create a new document explicitly, you need to start a transaction on it. Although in this case you are not creating the new document yourself, starting a transaction solves the problem here as well:

void application_OnDocumentNewed( Document doc )
{
  bool rc = doc.BeginTransaction();
  Debug.Assert( rc, "begin transaction failed" );
  if( rc )
  {
    CreateUserDefinedParameters( doc );
    rc = doc.EndTransaction();
    Debug.Assert( rc, "end transaction failed" );
  }
}

So, once again, you need to encapsulate the modification in a transaction. In the context of an external command, the Revit API will automatically begin a transaction for you. Depending on the IExternalCommand result value returned from the external command's Execute method, the transaction will be either closed or aborted. In all other contexts, however, including all event handlers, no such transaction will be automatically opened for you, so you are responsible for doing so yourself.

Many thanks Lindsay Rader at Advanced Technologies Group, Inc. for raising this question and to Adam Nagy of Autodesk for the answer!

Rome and Cantalupo

I wrote the text above after getting hooked in a small coffee shop in Barcelona providing a wifi connection, on my way to the airport. At least I should have been on my way, instead of sitting there blogging. I very narrowly avoided missing my flight to Rome. I did make it though, checking in as the last passenger before the flight was closed, and am now on a completely uninformed and purely intuitive few-hour tour of some parts of the city. My first station here has turned out to be Viale Nino Manfredi with a fine view over the entire city. From there I took a long walk:

• through the Palatino, almost getting lost in some fenced off areas,
• around the Arco di Constantino and Colloseum,
• through a huge protest march against the Israeli warfare on Gaza,
• around the unbelievably huge and impressive Monumento di Vittorio Emmanuele II,
• through the ruins of the Teatro Marcello,
• across Isola and Fiume Tevere,
• through Trastevere, looking for a hotel and some good food,
• before spontaneously and abruptly deciding to leave Rome immediately after all.

After driving off into the unknown I ended up in a quiet and hidden little place called Cantalupo, which may or may not mean song of wolf, next to Casperia, with no idea of where I actually am, which is a very enjoyable state to be in. There is no hotel in this little town, so I am in a guest house where I first had to spend ten minutes trying to get any one electric light in the room to work. My landlady is an old lady with no teeth. She made me late supper, a delicious three-course meal from nothing, toasting some bruscetta over an open fire in the fireplace, spaghetti al'arrabiata, and cheese with some green vegetable fried in oil that she named for me but I was unable to identify or remember.

I am awakened Sunday morning at half past seven by the firing of cannons. To celebrate the fiesta of the benediction of the animals, I am told. This place is so fantastic ... in case you are interested, the address is Villa delle Rose, Viale Verdi 42, Cantalupo, Rieti, Italy, tel. 0765/514035. From here I will visit Casperia, just a few kilometres away, and then maybe continue towards Perugia, Firenze, Bologna, Verona. In case you are wondering what I am actually up to on this haphazard trip, my purpose is to teach Revit programming in Verona and learn some Italian first, with the ultimate goal of holding the training in Italian.

Well, no internet connection in Casperia, so now I am in the city of Terni, posting from the bonnet of somebody's car, hooked up to somebody's unprotected wifi.

Barcelona Questions

Thanks to Alex Vila Ortega of Autodesk Spain, I spent the last couple of days here in Barcelona giving a training class on the Revit API, with lots of professional and enthusiastic participants. Here are some of the questions that we explored.

Question: How can I retrieve all the windows hosted by a specific given wall?

Answer: Well, one possibility is to make use of the relationship inverter that we already discussed. This will provide a global dictionary mapping each wall in the entire model to a list of all the windows it hosts. Here is an idea for a more direct and localised approach using API filtering:

We can make use of the fact that each window's host id is available not only from the FamilyInstance Host property, but also through the built-in parameter HOST_ID_PARAM. This means that we can build a filter checking for the following combination of properties:

• Category Windows.
• Type FamilyInstance.
• Built-in parameter value for HOST_ID_PARAM equal to the given wall element id.

The resulting Boolean 'and' combination should return all the windows hosted by a specific wall.

Question: I create new levels through the API and that works fine. However, no views are generated for these levels. How can I generate views for the new levels?

Answer: You might get some ideas by searching globally in the SDKSamples2009 solution for the NewLevel method, which is used to create a new level. One of the places it is used is the FrameBuilder SDK sample, in FrameData.cs:

  Level newLevel
    = createDoc.NewLevel( elevation );

  createDoc.NewViewPlan( newLevel.Name,
    newLevel, ViewType.FloorPlan );

This appears to be creating a level and immediately creating a new plan view for it as well, which seems to be just what you are looking for.

Question: We need to update some parameter values on certain elements from the document closed and saved events on the application object. To do so, we implemented an external application class App in order to hook up automatic synchronisation to document save and close events. We created a method SynchroniseAreaParameters to update the appropriate element parameters, which is registered as an event handler for the OnDocumentClosed, OnDocumentSaved and OnDocumentSavedAs events:

public class App : IExternalApplication
{
  void SynchroniseAreaParameters(
    Document doc )
  {
    ElementIterator i = doc.get_Elements(
      typeof( Room ) );
 
    while( i.MoveNext() )
    {
      Command.UpdateAreaParameter(
        i.Current as Room );
    }
  }
 
  public IExternalApplication.Result OnStartup(
    ControlledApplication app )
  {
    app.OnDocumentClosed
      += new DocumentClosedEventHandler(
        SynchroniseAreaParameters );
 
    app.OnDocumentSaved
      += new DocumentSavedEventHandler(
        SynchroniseAreaParameters );
 
    app.OnDocumentSavedAs
      += new DocumentSavedAsEventHandler(
        SynchroniseAreaParameters );
 
    return IExternalApplication.Result.Succeeded;
  }
 
  public IExternalApplication.Result OnShutdown( ControlledApplication app )
  {
    app.OnDocumentClosed
      -= new DocumentClosedEventHandler(
        SynchroniseAreaParameters );
 
    app.OnDocumentSaved
      -= new DocumentSavedEventHandler(
        SynchroniseAreaParameters );
 
    app.OnDocumentSavedAs
      -= new DocumentSavedAsEventHandler(
        SynchroniseAreaParameters );
 
    return IExternalApplication.Result.Succeeded;
  }
}

Unfortunately, this does not work, although we can see in the debugger that the notifications are dispatched as expected and each step executes correctly with no error. Why are the parameters not updated accordingly?

Answer: The reason why no changes are applied to the document is that you need to encapsulate the modification in a transaction. In the context of an external command, the Revit API will automatically begin a transaction for you. Depending on the IExternalCommand.Result value returned from the external command's Execute method, the transaction will be either closed or aborted. Within the context of an event handler, however, no such transaction will be automatically opened for you, so you are responsible for doing so yourself. Adding two lines to SynchroniseAreaParameters to begin and end a transaction solved the problem:

  void SynchroniseAreaParameters(
    Document doc )
  {
    if( doc.BeginTransaction() )
    {
      ElementIterator i = doc.get_Elements(
        typeof( Room ) );
 
      while( i.MoveNext() )
      {
        Command.UpdateAreaParameter(
          i.Current as Room );
      }
      doc.EndTransaction();
    }
  }

I am looking forward to more exciting topics to explore and things to learn in our remaining day together.