The Building Coder

DWG Issues and Various Other Updates

One of the highlights mentioned in the overview of the Revit 2014 API is the FreeForm element API that enables modification of solid geometry imported from DWG or SAT.

Several other new DWG and DXF related features include import of DXF markup, import and link of SAT and SketchUp, and access to the DWG, IFC and DGN layer, linetype, lineweight, font and pattern tables.

One result of these enhancements is the possibility to access 3D coordinates in DWG import for the first time.

Besides looking at that, I'll also point out a few other issues further down:

• Differentiate Label and Text in DWG export
• Element Ids in extensible storage
• All-zero language codes in the Revit product GUID
• Another dockable panel sample

Access to 3D Coordinates in DWG Import

One DWG import aspect that has often been requested by developers in the past is the ability to explode 3D DWG files and obtain the resulting coordinates in the Revit project.

Revit 2014 families now provide the ability to explode and retain such 3D geometry.

Daniel Gijsbers discusses making use of this functionality to correlate Civil 3D alignments with Revit Structure.

In Revit 2013, one alternative way to achieve this was to implement an AutoCAD add-in that analyses the geometry and exports the 3D coordinate data. A separate Revit add-in could read the coordinate data and correlate it with the Revit geometry.

Differentiate Label and Text in DWG Export

On a related topic, how can I differentiate between Revit text and label elements after they have been exported to DWG?

Revit Export to DWG results in Labels becoming Text rather than Attributes, as most users might prefer.

It would be interesting to have some flag or embedded information in the exported text that could be used in an AutoCAD application to post-process the information received from Revit and restore the attribute information.

Happily, the exported Labels have Extended Entity Data like this attached:

  TypedValue 0 - type: 1001, value: REVIT
  TypedValue 1 - type: 1002, value: {
  TypedValue 2 - type: 1070, value: 1
  TypedValue 3 - type: 1000, value: 245287
  TypedValue 4 - type: 1002, value: }
  TypedValue 5 - type: 1002, value: {
  TypedValue 6 - type: 1070, value: 5
  TypedValue 7 - type: 1000, value: 243658
  TypedValue 8 - type: 1002, value: }
  TypedValue 9 - type: 1002, value: {
  TypedValue 10 - type: 1070, value: 2
  TypedValue 11 - type: 1000, value: -2000280
  TypedValue 12 - type: 1002, value: }

The xdata on Text elements, on the other hand, look like this instead:

  TypedValue 0 - type: 1001, value: REVIT
  TypedValue 1 - type: 1002, value: {
  TypedValue 2 - type: 1070, value: 1
  TypedValue 3 - type: 1000, value: 261323
  TypedValue 4 - type: 1002, value: }
  TypedValue 5 - type: 1002, value: {
  TypedValue 6 - type: 1070, value: 5
  TypedValue 7 - type: 1000, value: 209618
  TypedValue 8 - type: 1002, value: }
  TypedValue 9 - type: 1002, value: {
  TypedValue 10 - type: 1070, value: 2
  TypedValue 11 - type: 1000, value: -2000300
  TypedValue 12 - type: 1002, value: }

The differing TypedValue 11 is consistently -2000300 for a text and -2000280 for a label element.

What does this mean?

Well, is actually quite easy.

On seeing these large negative numbers in this specific range, an experienced Revit developer will quickly suspect built-in category or parameter enumeration values.

You can check what they actually represent in the Visual Studio debugger, by jumping to the definition of these enumerations and searching for the specific values.

Looking back at an ancient blog post on the DWG and DXF export Xdata specification confirms that these numbers do indeed represent the built-in category of the source element and thus can be used to distinguish the two.

Many thanks to Dale Bartlett, CAD-BIM System Manager at Atkins (Oman), for suggesting this topic.

Dale adds:

It will be interesting to see if this generates any comments.

As far as the AutoCAD geometry export, the purpose was to build a 3D Space Frame from an engineer’s analysis drawing. I did in fact write an XML file from AutoCAD of the geometry and imported it into Revit to build the frame.

It took an hour to build 20,000 elements, which was about a year less than doing it manually!

I’ll revise it with 2014 to make it a one-step-inside-Revit process.

Element Ids in Extensible Storage

Question: I need to store ElementId data using schemas within my Revit add-in.

However, the API documentation states that "ids are subject to change during an Autodesk Revit session and as such should not be retained and used across repeated calls to external commands."

My add-in will be used in a worksharing environment. My testing shows that if I try to save the integer value of an element id, and it changes, my saved id value will be invalid. However, if I store the actual ElementId in a schema I do not have this problem.

Is saving the ElementId using a Schema safe? If not, do you have any suggestions or examples of how to safely store an identifier to elements in a schema?

Answer: Yes, it is completely safe to store ElementId data in extensible storage for the purposes you describe.

The statement you quote refers to the fact that the integer value of an element id will change between sessions. Basically, you can think of it as a pointer. When stored as an element id in extensible storage, the actual links between the associated elements are stored, and the resulting integer values are recalculated from scratch in every new session, maintaining the links intact. The integer value of an element id may be changed by worksharing updates as well, and these changes are also automatically handled for element ids stored in extensible storage, so it is perfectly safe to save them there.

All-zero Language Codes in the Revit Product GUID

Watch out for all-zero language code identifiers in the Revit Product GUID due to the new Multiple Language Interface, or MUI, used in Revit 2014.

For details, please refer to the Revit Product 2014 GUID addendum.

Another Dockable Panel Sample

Guy Robinson published another dockable dialogue sample which does not require a command to be registered.

For details, please refer to the simpler dockable panel addendum.

Relax – Simple Free Cloud Based Data Repository with NoSQL, CouchDB, and IrisCouch

Last week, I mentioned my proposal for the Autodesk Technical Summit in June, to present a cloud-based round-trip 2D Revit model editing project.

That will obviously required a cloud-based data repository. Talking with my colleagues, all of their suggestions were oriented towards the Microsoft Azure and Amazon solutions discussed so far on the cloud and mobile DevBlog.

I was searching for something freer, more open source, and less proprietary, and was rather surprised to discover an utterly relaxing solution that so far looks absolutely perfect for me and my needs.

I first stumbled upon IrisCouch, which led me to CouchDB and NoSQL, which all make me very happy. For didactical purposes, I will discuss them in inverted order, though.

Before I get to that, I would also like to mention my first ski tour of the year:

• Ski Tour Season Opening
• NoSQL
• CouchDB
• IrisCouch
• ID and GUID in Revit Documents
• Visual Revit Programming with Dynamo

My Ski Tour Season Opening

I went on a ski crossing of the Glarner Alps last weekend.

We took the cable lift up to the Fisetenpass and climbed the Gemsfairenstock, Clariden and Piz Cazarauls. We were hoping to get on to the Schärhorn as well, but had to give that up due to bad weather conditions. Instead we headed over the glacier to the Chammlijoch und down the Iiswaendli back to the Klausenpass.

This was my second ascent of the Clariden Mountain, following the last one in September 2011, from the opposite direction and obviously under very different conditions.

A great way to get away from computers for a day or two and face the natural elements instead, at their wildest and fiercest.

Relax – with NoSQL

As said, researching a simple efficient cloud-based data repository for my SVG editing project, I discovered NoSQL, 'not only SQL', a whole new class of database model, hitherto unknown to me.

A NoSQL database provides a simple, lightweight mechanism for storage and retrieval of data that provides higher scalability and availability than traditional relational databases. The NoSQL data stores use looser consistency models to achieve horizontal scaling and higher availability. Some NoSQL systems do allow SQL-like query language to be used.

NoSQL database systems are often highly optimized for retrieval and appending operations and often offer little functionality beyond record storage, e.g. key–value stores. The reduced run-time flexibility compared to full SQL RDBM systems is compensated by marked gains in scalability and performance for certain data models.

Since my application will only require storage of simple key-value pairs and should in theory be massively scalable, this sounds like an optimal choice. In practice, I only expect it to be a toy, of course; the scalability is required only to make it a useful example toy.

Relax – with CouchDB

Apache CouchDB is a NoSQL implementation, one of a new breed of database management systems.

As stated by its official by-line, the one word to describe CouchDB is relax. When you start CouchDB, you see:

Apache CouchDB has started. Time to relax.

CouchDB is built not only for, but of the Web. Its design borrows heavily from web architecture and the concepts of resources, methods, and representations. Data is self-contained:

Replication and backup is extremely simple, basically requiring no more than a modification of the base URL.

CouchDB is implemented in the Erlang programming language, which is used to build massively scalable soft real-time systems with requirements on high availability with uses in telecommunication, banking, e-commerce, computer telephony and instant messaging. Erlang's runtime system has built-in support for concurrency, distribution and fault tolerance.

Here is a 'what is' Q&A, getting started tutorial and full 270-page O'Reilly textbook CouchDB – The Definite Guide.

The textbook samples make use of the cURL command line tool, e.g. the following two command line statements to create a new and list a database:

  curl -X PUT http://127.0.0.1:5984/baseball
  {"ok":true}

  curl -X GET http://127.0.0.1:5984/_all_dbs
  ["baseball"]

Relax – with IrisCouch

As I initially mentioned, the starting point of this exploration of mine was IrisCouch, which terms itself 'easy CouchDB'. It provides a free hosting service, 'a couch in the cloud'. You can sign up in minutes to have your own Apache CouchDB server.

For my purposes, I can install CouchDB on my local machine, develop my data repository locally, and push it all to the cloud by replicating my local database to IrisCouch and changing the base URL to use that for all interaction.

Relax – with DreamSeat

While I explored the theory, my colleague Philippe Leefsma went ahead and implemented a pair of .NET applications uploading and consuming cloud-based data from an IrisCouch-hosted CouchDB database using the DreamSeat CouchDB .NET wrapper library.

Although the DreamSeat documentation boasts support for both complete synchronous and asynchronous API, Philippe used Visual Studio 2012 and its .NET 4.5 async support that automatically and transparently implements the entire support for async call-back. 'Async' methods can use the 'await' keyword, so he wrote a couple of anync wrapper methods for standard synchronous DreamSeat calls.

Well, that provides lots of material to play with in the immediate future, and gives me hope of easily implementing my cloud-based data repository requirements.

Here are a couple of other more directly Revit API related notes:

ID and GUID in Revit Documents

Question: A short question about the way unique ID’s are managed in Revit. I want to export a large number of RVT models through DB link to a single database and I really need to have unique ID’s in my destination tables. So far what I’ve seen is that the records pushed to my database have a field ID which seems to be unique within each Revit file, but not with my set of files.

So is there a way to have really unique identifier like a GUID instead of simple ID in my RVT models? Or at least is there a way to rely on a kind of GUID when we push data through DB link?

Answer: Each Revit element has an ID property, its element id, which is unique within the RVT document, but not globally.

Each Revit element also has a UniqueId property, which is globally unique, unless you do something to sabotage that.

Under normal circumstances, the UniqueId should fulfil your needs.

Visual Revit Programming with Dynamo

One last, final note before closing: if you are interested in a visual programming environment for Revit which allows non-programmers to create workflows to automate Revit functionality and geometry creation, be sure to check out Dynamo, also featured at AutodeskVasari.com.

Cloud & Mobile, Extensible Storage Data Use in Schedules

My topics for today are:

• Cloud and mobile topics I covered so far
• Cloud-based round-trip 2D Revit model editing on any mobile device using SVG
• Extensible storage data use in schedules

I am still meeting with my European DevTech colleagues here in Konk Leon, 'anse du Lèon', the cove of the lion, aka Le Conquet, Brittany.

Yesterday, one of our topics was work we have done so far for cloud and mobile applications. It was very interesting to hear about my peers' rich and varied experiences.

Cloud and Mobile Topics Covered so Far

I documented all my own experiences so far here on the blog, and was able to reuse that for my presentation quite spontaneously with no further preparation:

• Accessing a REST API web service from a Revit .NET add-in – Apollonian sphere packing and AVF.
• Thoughts on mobile indoor positioning, representing room polygons in SVG, the Azure SDK, ASP.NET MVC 4, and implementing a web service.
• An overview of the BIM 360 Glue viewer and REST API.
• BIM 360 Glue REST API authentication using Python.
• A room polygon and furniture picker in SVG.
• 2D SVG editing on mobile devices using the Raphaël JavaScript SVG library.

As I explained at the time, all of the explorations involving SVG are part of a larger master plan.

This plan has now matured to a certain extent and is forcing me to move ahead quite fast in the immediate future.

The main outcome so far is a presentation proposal that I submitted for the internal Autodesk technical summit taking place in June, and the fact that it was accepted.

My cloud and mobile roadmap is thus now clearly focused on implementing that proposal:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device using SVG

I described the roadmap I envision in the discussion of my simple SVG editor. The main components include:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• The SVG editor running in a browser on any device, rendering the model and supporting some simple geometric modification.

Here is the actual wording of my technical summit proposal:

Proposal Abstract

This presentation demonstrates round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser. How can this be achieved? A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository. On the mobile device, the repository is queried and the data is rendered in a standard browser using JavaScript and SVG. The rendering supports modification, such as translation and rotation of the furniture and equipment, which is saved back to the cloud database. The Revit add-in picks up these changes and updates the Revit model.

Intended Audience and Prerequisites

Intended audience is programmers with interest in cloud-based and mobile computing, specifically interest in round-trip editing of a Revit model using a cloud-based data repository and editing a 2D model on an arbitrary mobile device with no additional software beyond a browser installed on it. 
Knowledge of .NET, JavaScript and REST programming is helpful but not required. Revit add-in experience is not a prerequisite.

Presentation Outline

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Pick up and display the modified model in Revit.

Two of the important components whose implementation I plan to explore next are the polygon generation and data model:

Plan View Polygon Determination

The generation of the room boundary polygons is obvious, since the room has a boundary property.

For the furniture and equipment family instance, the solution is a less immediate. My current idea is to explore making use of the ExtrusionAnalyzer class. It is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction. As far as I can tell, that should be exactly what I need.

Scott Conover mentioned this class in his session on the Geometry API, a continuation of his AU 2011 presentation CP4011 'Geometric Progression: Further Analysis of Geometry Using the Autodesk Revit 2012 API', enhanced for the Revit 2013 API.

As soon as I have the polygons determined, I want to implement functionality to render them easily. This will involve extent calculation, canvas definition, and coordinate system transformation. I will probably implement a simple .NET geometry viewer before moving on to the SVG rendering. I've been wanting to do that for a long time...

Cloud-based Data Repository

So far, my colleagues have been focusing on using the Amazon and Azure cloud hosting services, and many discussions on the cloud and mobile DevBlog deal with them.

I searched the Internet for other cloud-based database alternatives, and right now CouchDB looks pretty promising, so I might try a completely different approach using that instead.

There is a lot to do here as well: define the data model, set up the web service, define a format for saving the polygon data, etc. At the very least, I will need to manage:

• Model > metadata, rooms.
• Room > metadata, model, furniture, level, polygon.
• Furniture > metadata, room, polygon, transformation (initially identity).

Round tripping the information will be interesting, especially if I want the Revit model to update automatically when furniture positions are modified on the mobile device, which I certainly do, if only for the wow effect :-)

Stay tuned...

... Oh, and, yeah, wish me luck!

Extensible Storage Data Use in Schedules

Returning to the desktop again, here is a recent question from a developer on using estorage data in a schedule that leads to some general observations on that topic:

Question: I would like to display my extensible storage information in a schedule. I searched high and low, though, and was unable to find any samples or documentation on the subject. Can you help?

Answer: There is a good reason why you have not found anything: there is no such support.

The usage of extensible storage data is utterly and completely up to the add-in itself. The Revit API offers no support whatsoever for making use of estorage data in any way. The only support provided is for storage and retrieval, nothing else.

Well, one tiny little detail more: if an element id value is stored, and the element id is later modified by some worksharing operation, its value will be automatically updated.

On the other hand, there is currently no direct support for putting data into a schedule either.

I am no user interface expert, but I think that you can set up a schedule to be populated from certain parameter values via the user interface. You would have to talk with an application engineer or product support or explore this topic on the Internet to find out how that can be done.

Of course, there is nothing stopping you from extracting your data from extensible storage and transferring it into parameters set up to populate a schedule yourself.

I hope that answers your question and helps you get started successfully.

DevBlog, DevCamp, Element and Project Wide Data

Every once in a while, I like to start the week with a bang, so here goes, with a risk of information overload on the following topics:

• ADN AEC DevBlog
• Autodesk AEC DevCamp
• Goodbye Kailash Kute
• Project Wide Data Storage
• DataStorage Element
  • Simple DataStorage Sample
  • Identifying DataStorage Elements

ADN AEC DevBlog

I bet you are not half as confused as we always are internally about DevDays, DevLabs, DevNotes, and last but not least DevCamps.

I recently mentioned that we are raising the bar one further with the introduction of the Autodesk Developer Network ADN DevBlogs, for AutoCAD and Infrastructure, marking the advent of a whole series and a significant shift from material available to ADN members, like technical solutions known as DevNotes on the ADN extranet, to material publicly available to everyone. Following these two, we are now proud to present the AEC DevBlog!

The AEC DevBlog covers Revit, Navisworks and other Autodesk AEC and BIM technologies and their APIs.

Here are links to the three DevBlogs live so far:

• AutoCAD DevBlog
• Infrastructure Modelling DevBlog
• AEC DevBlog

ADN DevBlogs for Manufacturing, Media & Entertainment are also expected.

For more information, please refer to Stephen Preston's welcome post.

Only a month to go – Autodesk AEC DevCamp

I also recently mentioned the upcoming AEC DevCamp conference being held in Boston June 6-7, where customers, resellers and professional developers come together and learn about extending Autodesk technologies through software development.

The AEC DevCamp comprises several parallel tracks for

• Revit App Development for Beginners and Intermediates
• Revit App Development for Intermediates and Experts
• Infrastructure Technologies
• Cloud/Mobile Technologies
• Other Autodesk AEC Technologies
• Business

The classes are presented by a managers, core developers, ADN experts and others and cover all levels from people just beginning to do software development with our technologies to experts looking to build sophisticated cloud and mobile apps. You can also grab a chance to meet and talk with these interesting and influential people.

Besides welcoming new beginners to the Revit API, I would also like to bid farewell to an old-timer:

Goodbye Kailash Kute

I gratefully acknowledge this very sweet parting message from one of our most prolific commenters and autonomous Revit MPE API problem solvers, Kailash Kute:

Dear Jeremy, i would like to inform you that since i have changed my current company to another where there is no Revit, but till this whole time which i used to blog post on building coder, was very good and fantastic journey, your blog was most useful stuff for me, i liked the coding, the posts, the information provided on this. i will miss but i also like to appreciate the work you are doing for revit stuff. Really it was a wonderful journey till this day on BuildingCoder.

Very many thanks, Kailash, for your numerous contributions and great endurance in solving so many Revit MEP API issues!

I was always sorry not to be able to help you more, and very impressed that you struggled on and succeeded in solving every single issue in the end.

Funnily enough, I just last week published an updated pipe cap creation post superseding the original one on which you submitted all your comments :-)

I wish you much success and all the best in your new role!

So long, and thanks for all the fish!

Back to the nuts and bolts of the Revit API, here is a case brought up and eventually solved by Mario Guttman of Perkins+Will:

Project Wide Data Storage

Here is a simple question that has been asked repeatedly, so I guess it is worthwhile pointing out:

Question: Is it possible to save some data in the Revit model that has no relation to any specific Revit model building element?

For instance, in AutoCAD I can store data in the named objects dictionary, and I can store xdata or xrecord to be saved with an entity.

I know that it is possible to store extensible storage data on individual Revit elements, but I need a place to save data applying to the entire model.

How can I achieve this, please?

Answer: Although extensible storage is indeed associated with individual elements, you can easily store global data in certain singleton elements.

There are several such elements that are always guaranteed to exist, and to exist only once, so-called singleton instances. One such instance is the ProjectInformation element, whose category is OST_ProjectInformation.

It was commonly used to store global shared parameters in the past, and the same of course applies for extensible storage as well:

• Define a new parameter
• Store project data
• Add a category to a parameter binding

In another case, an arbitrary element was required to format a parameter value, and the ProjectInformation singleton was used for that also.

For complete background information on extensible storage in Revit 2012, I would suggest looking at my Autodesk University 2011 class and lab on this topic, which tell the complete story. I recently published the handouts and sample material for those here on the blog to provide more immediate access.

DataStorage Element

Better still for your case, one of the add-in integration features introduced by the Revit 2013 API is a new DataStorage element to enable add-ins to store extensible storage data completely independently of all BIM database elements.

The DataStorage element is only accessible through the API, not through the user interface. Here is the excerpt on it from the 'What's New' section of the Revit Quasar SDK help file RevitAPI.chm:

The new DataStorage class represents an element which API applications can create logically organize different sets of ExtensibleStorage entities into separate elements. This allows an application to update one set of data in a local workshared project without locking other elements.

To demonstrate the usage of the new DataStorage element, here is a very nice set of samples by Victor Chekalin, Виктор Чекалин.

Simple DataStorage Sample

Storing data in a DataStorage element is very easy.

You can follow these steps to write your own data to a DataStorage element:

1. Create a new DataStorage using static method Create of DataStorage class.
2. Create a Schema.
3. Create an Entity which contains data you want to save.
4. Set entity to the created DataStorage.

To read data from DataStorage you need to:

1. Find DataStorage in the project (using FilteredElementCollector).
2. Get the entity from the retrieved DataStorage.
3. Read data from the Entity.

For example, assume we need to store in each document when a document was created and by whom.

On DocumentCreated event write information about the creating user:

  using( Transaction t = new Transaction( 
    doc, "Create created info" ) )
  {
    t.Start();
 
    // Create data storage in new document
 
    DataStorage createdInfoStorage 
      = DataStorage.Create( doc );
 
    // Create entity which store created info
 
    Entity entity = new Entity( 
      CreatedInfoSchema.GetSchema() );
 
    entity.Set( "CreatedUser", 
      Environment.UserName );
 
    entity.Set( "CreatedDate", 
      DateTime.Now.ToString() );
 
    // Set entity to the data storage element
 
    createdInfoStorage.SetEntity( entity );
 
    t.Commit();
  }

And read information later:

  // Retrieve data storage
 
  FilteredElementCollector collector =
      new FilteredElementCollector( doc );
 
  var dataStorage =
      collector
      .OfClass( typeof( DataStorage ) )
      .FirstElement();
 
  if( dataStorage == null )
  {
    message = "No data storage found "
      + "in current project";
 
    return Result.Failed;
  }
 
  // Retrieve entity from the data storage
 
  Entity createdInfoEntity = dataStorage.GetEntity( 
    CreatedInfoSchema.GetSchema() );
 
  if( !createdInfoEntity.IsValid() )
  {
    message = "Data storage doesn't "
      + "have CreatedInfoSchema";
 
    return Result.Failed;
  }
 
  var createdUser = createdInfoEntity.Get<string>( 
    "CreatedUser" );
 
  var createdDate = createdInfoEntity.Get<string>( 
    "CreatedDate" );
 
  StringBuilder sb = new StringBuilder();
 
  sb.AppendFormat( "Created user: {0}\r\n", 
    createdUser );
 
  sb.AppendFormat( "Created date: {0}", 
    createdDate );
 
  TaskDialog.Show( "Project created info", 
    sb.ToString() );

Identifying DataStorage Elements

The simple DataStorage example above very simple indeed. It has one big disadvantage, though: In a project there could be a lot of DataStorage elements including elements created by other developers. So, we must implement a method to differentiate one DataStorage from another and retrieve only the DataStorage elements we really need.

The simplest way to achieve this is to search for a singleton DataStorage element of the expected Schema.

Let’s look at another example in which we store our own settings for the entire project which we could use in our add-in.

At first, create a Settings class

  public class MyProjectSettings
  {
    public int Parameter1 { get; set; }
    public string Parameter2 { get; set; }
  }

Next, create a schema for it:

  public static class MyProjectSettingsSchema
  {
    readonly static Guid schemaGuid = new Guid( 
      "{9DBE0174-AA01-4CDD-BA86-96DE1FDCE041}" );
 
    public static Schema GetSchema()
    {
      Schema schema = Schema.Lookup( schemaGuid );
 
      if( schema != null ) return schema;
 
      SchemaBuilder schemaBuilder =
          new SchemaBuilder( schemaGuid );
 
      schemaBuilder.SetSchemaName( 
        "MyProjectSettings" );
 
      schemaBuilder.AddSimpleField( 
        "Parameter1", typeof( int ) );
 
      schemaBuilder.AddSimpleField( 
        "Parameter2", typeof( string ) );
 
      return schemaBuilder.Finish();
    }
  }

For reading and writing settings to the DataStorage, we can implement a class like the following MyProjectSettingStorage:

class MyProjectSettingStorage
{
  readonly Guid settingDsId = new Guid(
    "{A71F620F-BD0D-46DD-AECD-AFDEF0DFFD74}" );
 
  public MyProjectSettings ReadSettings(
    Document doc )
  {
    var settingsEntity = GetSettingsEntity( doc );
 
    if( settingsEntity == null
      || !settingsEntity.IsValid() )
    {
      return null;
    }
 
    MyProjectSettings settings =
        new MyProjectSettings();
 
    settings.Parameter1 = settingsEntity.Get<int>(
      "Parameter1" );
 
    settings.Parameter2 = settingsEntity.Get<string>(
      "Parameter2" );
 
    return settings;
  }
 
  public void WriteSettings(
    Document doc,
    MyProjectSettings settings )
  {
    var settingDs = GetSettingsDataStorage(
      doc );
 
    if( settingDs == null )
    {
      settingDs = DataStorage.Create( doc );
    }
 
    Entity settingsEntity = new Entity(
      MyProjectSettingsSchema.GetSchema() );
 
    settingsEntity.Set( "Parameter1",
      settings.Parameter1 );
 
    settingsEntity.Set( "Parameter2",
      settings.Parameter2 );
 
    // Identify settings data storage
 
    Entity idEntity = new Entity(
      DataStorageUniqueIdSchema.GetSchema() );
 
    idEntity.Set( "Id", settingDsId );
 
    settingDs.SetEntity( idEntity );
    settingDs.SetEntity( settingsEntity );
  }
 
  private Entity GetSettingsEntity(
    Document doc )
  {
    FilteredElementCollector collector =
        new FilteredElementCollector( doc );
 
    var dataStorages =
        collector.OfClass( typeof( DataStorage ) );
 
    // Find setting data storage
 
    foreach( DataStorage dataStorage in dataStorages )
    {
      Entity settingEntity =
        dataStorage.GetEntity( MyProjectSettingsSchema.GetSchema() );
 
      // If a DataStorage contains 
      // setting entity, we found it
 
      if( !settingEntity.IsValid() ) continue;
 
      return settingEntity;
    }
 
    return null;
  }
}

Remember, the DataStorage element storing project-wide settings must be a singleton. So, before writing settings we look for an existing DataStorage and if it doesn’t exist, create it. For searching, we check each data storage element for the Setting entity.

Of course, you could also use another way to differentiate one DataStorage element from another. For example, by creating an auxiliary identification schema and attaching an entity instance of it to each DataStorage element. Using this entity, you can check whether a given DataStorage element is the one we need or not when retrieving it. You might also be able to make use of the built-in Revit API Element.UniqueId property, or other means of identification. It depends on your tasks.

Here is DataStorageSample.zip containing the full Visual Studio solution, project files, source code, and add-in manifests for Victor's two DataStorage samples.

Many thanks to Victor for providing and documenting this, providing such an easy entry point for everybody!

Extensible Storage Features

Here is a nice hot topic to start off the week. We already talked about the new Revit 2012 API EStorage or extensible storage functionality and presented example code to store a map or dictionary in it.

Here are a few other interesting notes and issues related to this which have cropped up, contributed and pointed out by Steven Mycynek:

1. Intended use of EStorage.
2. Handling large amounts of data in EStorage.
3. EStorage is self-documenting.
4. EStorage is object-oriented in two ways.
5. Read/Write permissions.
6. Modification of EStorage data on an element type.
7. Handling of ElementId data in EStorage.
8. Retrieving elements with a specific schema entity.
9. Checking for a valid entity on an element.
10. One entity per element.
11. Schemata remain in memory.

The automatic translation of element ids is one of the absolute highlights of this new technology that I was previously not aware of.

1. Intended Use of EStorage

Question: When should I use EStorage versus the existing technique of storing my data in text form in an XML-based hidden shared parameter?

Answer: EStorage is for storing a lot of complex bits of data that you want to organize into a class-like structure, complete with units, documentation, etc. If you already have an XML file that does all of that already, and you don't find using a single hidden shared parameter to be a burden, you might want to go ahead and keep using it. On the other hand, if you didn't already have an XML schema in place and had a huge variety of data you didn't want to convert to a text representation, I'd recommend starting out with EStorage.

2. Handling Large Amounts of Data in EStorage

Question: I am thinking of storing a large amount of data on a number of BIM elements. What approach would you recommend?

Answer: The intended and recommended use of EStorage does not include storing huge amounts of data in the model. For instance, we have seen issues with developers trying to store very heavy analysis data in hundreds of MB spread across thousands of elements, all loaded at start-up. Such usage will degrade performance. If you store large amounts of data across thousands of elements, do not expect an instant load time.

If you wish to store a large amount of data on individual elements, this should not be a problem. For instance, storing something like a .png file on a wall element is no issue at all, whereas it would be an issue to store a dozen .png files on every wall element and extract all of them at once, even if you only need the data for one at a given time.

One of the strengths of EStorage is its handling of arrays of objects or sub-entities and different schemas in general rather than one large segment of data that needs to be read in its entirety and deserialized all at once. I recommend taking advantage of this and only loading what you actually need for a given task. For small loads of data, this might not seem necessary, but when you get into many MB of data, it makes a difference.

3. EStorage is Self-documenting

When you create a schema, you are creating documentation. Be sure to fill out the documentation strings for each field – they will help you in your development process and others when they use your schema. What's more, since you can look up a schema by Guid, if you want to share a document with a schema with someone else, all they need is the Guid to look it up and read your structure and documentation comments. This might be a good opportunity to either use the SchemaWrapperTools included with the ExtensibleStorageManager SDK sample (or a simpler, similar tool) to print out a schema's field definitions and documentation strings from a single GUID input.

4. EStorage is Object-oriented in Two Ways

Not only is a given schema entity structured into named fields, but each entity is placed on elements relative to the data itself, as opposed to one large blob that you must read in its entirety to unpack. This goes along with what the recommendation above about not reading all storage at start-up. Since you can choose which elements to process, you have the opportunity to only load what you need an automatically have an association between data and a specific element – shared parameters can't do this.

5. Read/Write Permissions

This is another area that goes beyond shared parameters. While your schema definition is public, you can restrict who reads and writes schema data based to a specific vendor or a specific application from that vendor.

6. Modification of EStorage Data on an Element Type

Question: When transferring types from one project to another using Transfer Project Standards, it only copies across types that are different. If you change a parameter on a wall type that exists in both projects, then it gives you the option of copying over "new" types or overwriting existing types. However, if the parameters are unchanged but the schema data is different, it treats the wall types as identical, so does not give the option of copying over the wall type.

Are element types with different EStorage data attached to them treated as the same or not?

Answer: Any parameter based change, hidden or not, will trigger a new type to be recognized. EStorage, however, is not a parameter-based transaction, so those rules don't apply. Therefore, element types with differing EStorage attached to them are still treated as the same in this case.

7. Handling of ElementId Data in EStorage

Question: What happens to element ids stored in EStorage?

Answer: When you store an ElementId using EStorage and that ElementId gets remapped because the element is deleted or updated, e.g. because of a worksharing update, your stored ElementId is also automatically remapped to the new ElementId value. This is one strong advantage for using EStorage over text or raw numbers to store ElementIds – the tracking for element updates is handled automatically, so you can be sure that your ElementIds will remain valid. If the element is deleted, your ElementId will be set to ElementId.InvalidElementId.

8. Retrieving Elements with a Specific Schema Entity

Question: How can I retrieve all elements that have data from a certain schema attached to them? Optimally, I think that should be a filtered element collector option.

Answer: Right now, you must do a manual iteration of all elements. There may be a project to add a filter as you describe in the future, but we make no promises about any future features whatsoever.

9. Checking for a Valid Entity on an Element

Question: If I register a schema and then select an element that has no entity for that schema attached to it, I would expect the following call to return null:

  Entity ent = e.GetEntity( schema );

It does not. Instead, it returns a valid entity pointing to a null schema. To handle this, I expanded my check to this:

  if( null == ent || null == ent.Schema ) ...

Answer: Use the Entity.IsValid method to check to see if the entity you received from GetEntity actually has data of a given schema.

10. One Entity per Element

Question: Is only one entity per schema possible per Revit element?

Answer: Yes and no. There is no way to have more than one entity of a given schema per element via the GetEntity/SetEntity operations. However, you could always create another schema with more than one sub-entities of a given schema type, including array fields and map fields.

11. Schemata Remain in Memory

Question: Is it true that once a schema has been loaded into Revit memory, it never disappears again until the session ends?

Answer: That is true. A schema is available per use on the session level, even if a new document is created. Entities are associated with specific documents.

Many thanks to Steve for all of these tips!

Extensible Storage of a Map

I already discussed the important new and powerful extensible storage mechanism, and we also explained and demonstrated it in both the DevHelp Online and Revit 2012 API webcast presentations, both of which were recorded.

I updated the sample code for the latter webcast. Here is the mainline of the Execute method:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  try
  {
    // pick an element and define the XYZ 
    // data to store at the same time
 
    Reference r = uidoc.Selection.PickObject( 
      ObjectType.Face, 
      new WallFilter(), 
      "Please pick a wall at a point on one of its faces" );
 
    Wall wall = doc.get_Element( r.ElementId ) as Wall;
    XYZ dataToStore = r.GlobalPoint;
 
    Transaction t = new Transaction( doc,
      "Create Extensible Storage Schemata and Store Data" ); 
 
    t.Start();
 
    // store the data, and also 
    // demonstrate reading it back
 
    StoreDataInWall( wall, dataToStore );
 
    t.Commit();
 
    // list all schemas in memory across all documents
 
    ListSchemas();
 
    return Result.Succeeded;
  }
  catch( Exception ex )
  {
    message = ex.Message;
    return Result.Failed;
  }
}

It prompts you to select a wall at a specific point. The PickObject method can return both the selected wall and the picked point from one single user click. It also takes a WallFilter instance, an implementation of the ISelectionFilter interface, to restrict the user selection to walls only:

class WallFilter : ISelectionFilter
{
  public bool AllowElement( Element e )
  {
    return e is Wall;
  }
 
  public bool AllowReference( Reference r, XYZ p )
  {
    return true;
  }
}

The selected point is stored on the wall in a newly created extensible storage schema by the following helper method:

/// <summary>
/// Create an extensible storage schema, 
/// attach it to a wall, populate it with data, 
/// and retrieve the data back from the wall.
/// </summary>
void StoreDataInWall(
  Wall wall,
  XYZ dataToStore )
{
  SchemaBuilder schemaBuilder = new SchemaBuilder(
    new Guid( "720080CB-DA99-40DC-9415-E53F280AA1F0" ) );
 
  // allow anyone to read the object
 
  schemaBuilder.SetReadAccessLevel(
    AccessLevel.Public );
 
  // restrict writing to this vendor only
 
  schemaBuilder.SetWriteAccessLevel(
    AccessLevel.Vendor );
 
  // required because of restricted write-access
 
  schemaBuilder.SetVendorId( "ADNP" );
 
  // create a field to store an XYZ
 
  FieldBuilder fieldBuilder = schemaBuilder
    .AddSimpleField( "WireSpliceLocation",
    typeof( XYZ ) );
 
  fieldBuilder.SetUnitType( UnitType.UT_Length );
 
  fieldBuilder.SetDocumentation( "A stored "
    + "location value representing a wiring "
    + "splice in a wall." );
 
  schemaBuilder.SetSchemaName( "WireSpliceLocation" );
 
  // register the schema
 
  Schema schema = schemaBuilder.Finish(); 
 
  // create an entity (object) for this schema (class)
 
  Entity entity = new Entity( schema );
 
  // get the field from the schema
 
  Field fieldSpliceLocation = schema.GetField(
    "WireSpliceLocation" );
 
  // set the value for this entity
 
  entity.Set<XYZ>( fieldSpliceLocation, dataToStore,
    DisplayUnitType.DUT_METERS );
 
  // store the entity on the element
 
  wall.SetEntity( entity );
 
  // read back the data from the wall
 
  Entity retrievedEntity = wall.GetEntity( schema );
 
  XYZ retrievedData = retrievedEntity.Get<XYZ>(
    schema.GetField( "WireSpliceLocation" ),
    DisplayUnitType.DUT_METERS );
}

The mainline also calls another little method ListSchemas which shows how all schemas currently loaded into Revit memory can be accessed and listed:

/// <summary>
/// List all schemas in Revit memory across all documents.
/// </summary>
void ListSchemas()
{
  IList<Schema> schemas = Schema.ListSchemas();
 
  int n = schemas.Count;
 
  Debug.Print( 
    string.Format( "{0} schema{1} defined:", 
      n, PluralSuffix( n ) ) );
 
  foreach( Schema s in schemas )
  {
    IList<Field> fields = s.ListFields();
 
    n = fields.Count;
 
    Debug.Print( 
      string.Format( "Schema '{0}' has {1} field{2}:", 
        s.SchemaName, n, PluralSuffix( n ) ) );
 
    foreach( Field f in fields )
    {
      Debug.Print(
        string.Format( 
          "Field '{0}' has value type {1}"
          + " and unit type {2}", f.FieldName, 
          f.ValueType, f.UnitType ) );
    }
  }
}

Storing a Dictionary Mapping in Extensible Storage

In the sample so far, only a simple XYZ data field is added and stored.

Here is a new question on making use of extensible storage to store a more complex data type, a dictionary mapping keys to values, in this case both represented by strings.

Question: I have added simple data to Revit elements using Extensible Storage. Now I need a schema containing a field which is a map of strings. I added a field by using

  FieldBuilder.AddMapField( MyMappedField, 
    typeof( string ), typeof( string ) );

Now comes my problem: how can I set a mapped value to such a field by using Entity.Set<???>(???)?

Similarly, how can I retrieve a mapped value from such a field?

How can I remove a mapped value?

Please can you implement such a sample?

Answer: The key, no pun intended, is to use IDictionary<> as the type you pass to the Set<> method, even though your actual implementation concrete type is Dictionary<>.

This is document in the Revit API help file entry on the Entity.Set method, but I admit that it is tricky.

By the way, this is also demonstrated by the ExtensibleStorageManager SDK sample. For instance, it includes the following code snippet:

  // Note that we use IDictionary<> for 
  // map types and IList<> for array types
 
  mySchemaWrapper
    .AddField<IDictionary<string, string>>(
      map0Name, UnitType.UT_Undefined, null );
 
  mySchemaWrapper
    .AddField<IList<bool>>(
      array0Name, UnitType.UT_Undefined, null );

Here is a new method StoreStringMapInElement that I added to the sample above to demonstrate this:

/// <summary>
/// Create an extensible storage schema specifying 
/// a dictionary mapping keys to values, both using 
/// strings,  populate it with data, attach it to the 
/// given element, and retrieve the data back again.
/// </summary>
void StoreStringMapInElement( Element e )
{
  SchemaBuilder schemaBuilder = new SchemaBuilder(
    new Guid( "F1697E22-9338-4A5C-8317-5B6EE088ECB4" ) );
 
  // allow anyone to read or write the object
 
  schemaBuilder.SetReadAccessLevel(
    AccessLevel.Public );
 
  schemaBuilder.SetWriteAccessLevel(
    AccessLevel.Public );
 
  // create a field to store a string map
 
  FieldBuilder fieldBuilder
    = schemaBuilder.AddMapField( "StringMap",
      typeof( string ), typeof( string ) );
 
  fieldBuilder.SetDocumentation(
    "A string map for Tobias." );
 
  schemaBuilder.SetSchemaName(
    "TobiasStringMap" );
 
  // register the schema
 
  Schema schema = schemaBuilder.Finish();
 
  // create an entity (object) for this schema (class)
 
  Entity entity = new Entity( schema );
 
  // get the field from the schema
 
  Field field = schema.GetField(
    "StringMap" );
 
  // set the value for this entity
 
  IDictionary<string, string> stringMap
    = new Dictionary<string, string>();
 
  stringMap.Add( "key1", "value1" );
  stringMap.Add( "key2", "value2" );
 
  entity.Set<IDictionary<string, string>>(
    field, stringMap );
 
  // store the entity on the element
 
  e.SetEntity( entity );
 
  // read back the data from the wall
 
  Entity retrievedEntity = e.GetEntity( schema );
 
  IDictionary<string, string> stringMap2
    = retrievedEntity
    .Get<IDictionary<string, string>>(
      schema.GetField( "StringMap" ) );
}

Here is the full updated sample application ExtensibleStorage.zip including the Visual Studio solution and full source.

Many thanks to our local Revit extensible storage expert Steven Mycynek for help resolving this issue!

Extensible Storage

I mentioned the main new features of the Revit 2012 API and also pointed out that many important developer wishes have been resolved. Here is another very fundamental and longstanding wish that has been addressed, more completely than anyone might have expected:

Question: How can I store my custom application data inside the Revit file using the Revit API?

Answer: One possibility is to use a shared parameter. This is a slightly convoluted operation and involves setting up the shared parameter text file appropriately. You have the option of whether a shared parameter should or should not be visible to the user. The whole procedure is demonstrated by the FireRating SDK sample and discussed in numerous blog posts:

• Creating and using a shared parameter on various elements.
• Storing structured data in a Revit shared parameter.
• Storing project data.

In Revit 2012, one of the major API enhancements is the Extensible Storage mechanism. This offers a completely new storage facility for applications which is completely invisible to the user. It is the very first item described in the What's New section of the documentation on major enhancements:

Extensible Storage

The Revit API now allows you to create your own class-like Schema data structures and attach instances of them to any Element in a Revit model. This functionality can be used to replace the technique of storing data in hidden shared parameters. Schema-based data is saved with the Revit model and allows for higher-level, metadata-enhanced, object-oriented data structures. Schema data can be configured to be readable and/or writable to all users, just a specific application vendor, or just a specific application from a vendor. The extensible storage classes are all found in the Autodesk.Revit.DB.ExtensibleStorage namespace:

• Schema – contains a unique schema identifier, read/write permissions, and a collection of data Field objects.
• Entity – an object containing data corresponding to a Schema that can be inserted into a Revit Element.
• Field – contains data name, type, and unit information and is used as the key to access corresponding data in an Entity.
• SchemaBuilder – create Schema definitions.
• FieldBuilder – a helper class used with SchemaBuilder when creating a new field.

The following data types are currently supported:

• int
• short
• double
• float
• bool
• string
• Guid
• ElementId
• Autodesk.Revit.DB.UV
• Autodesk.Revit.DB.XYZ
• Array (as a System.Collections.Generic.IList<T>)
• Map (as a System.Collections.Generic.IDictionary<TKey, TValue> – all types are supported for keys except double, float, XYZ, and UV)
• Autodesk.Revit.DB.ExtensibleStorage.Entity (an instance of another Schema, also known as a SubSchema)

Simple usage of ExtensibleStorage:

/// <summary>
/// Create a data structure, attach it to a wall, 
/// populate it with data, and retrieve the data 
/// back from the wall
/// </summary>
public void StoreDataInWall( 
  Wall wall, 
  XYZ dataToStore )
{
  Transaction createSchemaAndStoreData
    = new Transaction( wall.Document, "tCreateAndStore" );
 
  createSchemaAndStoreData.Start();
  SchemaBuilder schemaBuilder = new SchemaBuilder(
    new Guid( "720080CB-DA99-40DC-9415-E53F280AA1F0" ) );
 
  // allow anyone to read the object
  schemaBuilder.SetReadAccessLevel( 
    AccessLevel.Public );
 
  // restrict writing to this vendor only
  schemaBuilder.SetWriteAccessLevel( 
    AccessLevel.Vendor );
 
  // required because of restricted write-access
  schemaBuilder.SetVendorId( "ADSK" );
 
  // create a field to store an XYZ
  FieldBuilder fieldBuilder = schemaBuilder
    .AddSimpleField( "WireSpliceLocation", 
    typeof( XYZ ) );
 
  fieldBuilder.SetUnitType( UnitType.UT_Length );
 
  fieldBuilder.SetDocumentation( "A stored "
    + "location value representing a wiring "
    + "splice in a wall." );
 
  schemaBuilder.SetSchemaName( "WireSpliceLocation" );
 
  Schema schema = schemaBuilder.Finish(); // register the Schema object
 
  // create an entity (object) for this schema (class)
  Entity entity = new Entity( schema );
 
  // get the field from the schema
  Field fieldSpliceLocation = schema.GetField(
    "WireSpliceLocation" );
 
  entity.Set<XYZ>( fieldSpliceLocation, dataToStore,
    DisplayUnitType.DUT_METERS ); // set the value for this entity
 
  wall.SetEntity( entity ); // store the entity in the element
 
  // get the data back from the wall
  Entity retrievedEntity = wall.GetEntity( schema );
 
  XYZ retrievedData = retrievedEntity.Get<XYZ>(
    schema.GetField( "WireSpliceLocation" ),
    DisplayUnitType.DUT_METERS );
 
  createSchemaAndStoreData.Commit();
}

The Revit 2012 SDK includes a much more full-fledged example of making use of this technology, the ExtensibleStorageManager sample.

As Arnošt Löbel kindly pointed out, the VendorId specified above is the same as the new required VendorId tag in the add-in manifest. ADSK is a vendor id used by Autodesk, and you should replace it by your own Autodesk Registered Developer Symbol RDS.

That should give you ample material to explore. Have fun!