Transcript About the Presenter

Extensible Storage in the Autodesk Revit 2012 API
Jeremy Tammik
Principal Developer Consultant
© 2011 Autodesk
About the Presenter
Jeremy Tammik
Principal Developer Consultant
Developer Technical Services
EMEA, Autodesk SARL
Jeremy is a member of the AEC workgroup of the Autodesk Developer Network ADN team,
providing developer support, training, conference presentations, and blogging on the Revit API.
He joined Autodesk in 1988 as the technology evangelist responsible for European developer
support to lecture, consult, and support AutoCAD application developers in Europe, the U.S.,
Australia, and Africa. He was a co-founder of ADGE, the AutoCAD Developer Group Europe, and
a prolific author on AutoCAD application development. He left Autodesk in 1994 to work as an
HVAC application developer, and then rejoined the company in 2005.
Jeremy graduated in mathematics and physics in Germany, worked as a teacher and translator,
then as a C++ programmer on early GUI and multitasking projects. He is fluent in six European
languages, vegetarian, has four kids, plays the flute, likes reading, travelling, theatre
improvisation, yoga, carpentry, loves mountains, oceans, sports, dancing, and especially climbing.
Revit Extensible Storage
© 2011 Autodesk
2
Class Summary

Overview of the Revit API Extensible Storage functionality
 Creating an extensible storage schema
 Storing simple and complex data in a schema entity
 Attaching a schema entity to a Revit database element
 Listing and deleting schemata
 Available sample applications
 Prerequisites: we assume prior knowledge of

Basic .NET programming skills
 Basic Revit API knowledge
Revit Extensible Storage
© 2011 Autodesk
3
Learning Objectives
At the end of this class, you will be able to:





Understand the underlying estorage concepts and real-world techniques
Programmatically create and populate a schema
Read, write, update and delete extensible storage data on elements
Handle versioning issues when upgrading and extending schemata
Extract and display estorage data and serialize and de-serialize
schemata to XML
Revit Extensible Storage
© 2011 Autodesk
4
Agenda

Introduction and basics
 Examples









Create a schema
Store a simple data item
List all schemata
Store complex data
Delete estorage data
Store a file
Additional observations
Sample applications
Learning more
Revit Extensible Storage
© 2011 Autodesk
5
Introduction and Basics
© 2011 Autodesk
Autodesk Developer Network

Access to almost all Autodesk software and SDK’s





Members-only website with thousands of technical articles
Product direction through conferences
Unlimited technical support
API training classes


Includes early access to beta software
One to three free for professional members
Marketing benefits

Exposure on autodesk.com
 Promotional opportunities
www.autodesk.com/joinadn
Revit Extensible Storage
© 2011 Autodesk
7
Acronyms












ADN
AEC
API
BIM
GUI
HVAC
MEP
RAC
RME
RST
SDK
UI
Autodesk Developer Network
Architecture, Engineering, Construction
Application Programming Interface
Building Information Model
Graphical User Interface
Heating, Ventilation, and Air Conditioning
Mechanical, Electrical, and Plumbing
Revit Architecture
Revit MEP
Revit Structure
Software Development Kit
User Interface
Revit Extensible Storage
© 2011 Autodesk
8
What is Extensible Storage?

Programmatically store arbitrary, auxiliary data in a Revit document
 Simple data types such as integer, double, string, element id
 Complex structures such as lists and dictionaries
 Can replace the old technique using shared parameters
 Read and write access can be restricted
Revit Extensible Storage
© 2011 Autodesk
9
Revit Storage Option Evolution

OLE Structured Storage used internally
 Shared parameters
 Estorage
Revit Extensible Storage
© 2011 Autodesk
10
Estorage

Easy to use
 Class-like structure
 Metadata enhanced
 Read and write permissions integrated into Vendor and App ID
 Natively supports element id, UV, and XYZ points and vectors
 Store data on any element
 Schema defines data structure through a list of fields
 Entity hold actual data, attached to Revit element
Revit Extensible Storage
© 2011 Autodesk
11
Shared Parameters versus Estorage

Units
 High-level objects
 Track elements on deletion or work share remapping
 Selectively hide or expose data
Revit Extensible Storage
© 2011 Autodesk
12
Estorage Basics

Autodesk.Revit.DB.ExtensibleStorage namespace classes
 Schema
 SchemaBuilder
 Field
 FieldBuilder
 Entity
Revit Extensible Storage
© 2011 Autodesk
13
Data Types

bool, short, int, float, double
 string
 Guid
 ElementId
 Autodesk.Revit.DB.UV
 Autodesk.Revit.DB.XYZ
 Array – System.Collections.Generic.IList<T>)
 Map – System.Collections.Generic.IDictionary<TKey, TValue>, no real-valued key
 Autodesk.Revit.DB.ExtensibleStorage.Entity – a Schema instance or SubSchema
Revit Extensible Storage
© 2011 Autodesk
14
Schema Definition

Use three SchemaBuilder methods





AddSimpleField( string name, Type )
AddArrayField( string name, Type )
AddMapField( string name, Type keyType, Type valueType )
Each returns a FieldBuilder instance
FieldBuilder provides access to set further properties

Documentation
 Units
Revit Extensible Storage
© 2011 Autodesk
15
Units

Floating-point fields require a unit type




float, double, XYZ, UV and containers of these values
length, temperature, etc.
Unit conversions are handled internally
Example:

Specify UT_Length in FieldBuilder.SetUnitType
 Specify DUT_DECIMAL_FEET when calling Entity.Set and Entity.Get
Revit Extensible Storage
© 2011 Autodesk
16
Examples
Learning by doing
© 2011 Autodesk
Estorage of a Simple XYZ Point

Create data structure: Schema
 Create data holder: Entity
 Populate it with data
 Attach it to a wall
Revit Extensible Storage
© 2011 Autodesk
18
Detailed Steps for Estorage of a Simple XYZ Point

Instantiate a new SchemaBuilder with the given schema GUID
 Define the read and write access levels and the vendor id
 Add a simple XYZ data field
 Set its unit type and documentation string
 Register the schema
 Create an entity to hold an instance of the schema data
 Access and populate the data field
 Store the entity on the Revit element
 Demo and examine the code

Command 1 StoreSimple
Revit Extensible Storage
© 2011 Autodesk
19
List Loaded Schemata

Static Schema class method ListSchemas
 All schemata in memory are returned
 May include schemata used in previous documents, now closed
 No information on schema use in individual document
Revit Extensible Storage
© 2011 Autodesk
20
Determine Estorage Use in Document

Check whether any elements in the document actually use a schema
 Iterate through all elements and check each individually
 Does it contain a schema entity?
 Demo and examine the code

Command 2 List
Revit Extensible Storage
© 2011 Autodesk
21
Estorage of Complex Data

Use SchemaBuilder AddArrayField and AddMapField methods
 Use generic .NET collection classes

Array IList<T>
 Map IDictionary<TKey, TValue>


Populate using concrete instance, e.g. List or Dictionary
Demo and examine the code

Command 3 StoreMap
Revit Extensible Storage
© 2011 Autodesk
22
Estorage Deletion

Individual entity: Element.DeleteEntity
 Entire schema in all documents: Schema.EraseSchemaAndAllEntities
 Arguments schema and overrideWriteAccessWithUserPermission
 Demo and examine the code

Command 4 Delete
Revit Extensible Storage
© 2011 Autodesk
23
Storing a File on a Revit Element

Define a schema storing an array of bytes
fieldBuilder = schemaBuilder.AddArrayField(
"Data", typeof( byte ) );

Convert file data to a byte stream
byte[] data = File.ReadAllBytes( filename );
entity.Set<IList<byte>>( schema.GetField( "Data" ), data );

Demo and examine the code

Command 5 StoreFile
Revit Extensible Storage
© 2011 Autodesk
24
Restoring a File from a Revit Element

Read byte array from schema entity
 Store byte stream into file
Entity ent = e.GetEntity( schema );
string filepath = Path.Combine(
ent.Get<string>( schema.GetField( "Folder" ) ),
ent.Get<string>( schema.GetField( "Filename" ) ) );
byte[] data = ent.Get<IList<byte>>( schema.GetField( "Data" ) ).ToArray<byte>();
File.WriteAllBytes( filepath, data );

Demo and examine the code

Command 6 RestoreFile
Revit Extensible Storage
© 2011 Autodesk
25
Additional Observations
© 2011 Autodesk
Additional Observations

Intended use
 Handling large amounts of data
 Self-documenting data
 Object-oriented
 Read/write permissions
 Modification of estorage data on an element type
 Handling of ElementId data
 Retrieving elements with specific schema data
 Checking for a valid schema entity on an element
 One entity per element
 Schemata remain in memory
Revit Extensible Storage
© 2011 Autodesk
27
Sample Applications
© 2011 Autodesk
FamilyStorage

Create estorage in a family document
 Retrieve its data in a project containing a family instance
 Two external commands AddDataToFamily and GetFamilyData
 AddDataToFamily defines schema and adds an entity to the family
Family documentFamily = doc.OwnerFamily;
Entity newEntity = MakeEntity( new XYZ( 1, 2, 3 ) );
documentFamily.SetEntity( newEntity );

GetFamilyData retrieves the stored data from the family via the instance
Family family = familyInstance.Symbol.Family;
Entity entity = family.GetEntity( schema );

Demo and examine the code
Revit Extensible Storage
© 2011 Autodesk
29
UpgradeSchema

Automatically upgrade from schema v1 to v2 on document open
 External command manually adds schema v1 data to all walls
 External application subscribes to DocumentOpened with an event handler
 Detect, read data and delete all schema v1 entities
 Create and populate v2 entities for them instead
 Demo and examine the code
Revit Extensible Storage
© 2011 Autodesk
30
Dynamic Section View

Revit SDK DynamicModelUpdate sample
 Modify Revit model as a reaction to changes
 Implement an updater, add a trigger, define scope and type

Scope defined by specific element ids or element filter
 Type can be element addition, deletion, modification of geometry, parameters, property



Sample works in AssociativeSection.rvt
Maintains section view positioned to display a cut through a window and the
host wall
Window position stored in estorage schema with two XYZ fields for location
point and facing orientation
Revit Extensible Storage
© 2011 Autodesk
31
Schema Wrapper Tools

C# library included Revit ExtensibleStorageManager SDK sample
 Defines wrappers for Schema, SchemaBuilder, Field, and FieldBuilder classes
 Provides easy serialization of schema data to XML
 Displays data of a schema entity
Revit Extensible Storage
© 2011 Autodesk
32
Extensible Storage Manager

Advanced Revit SDK sample
 Uses SchemaWrapperTools library
 Create complex schemas
 Framework for saving and loading schemas to a file
 Easy sharing and communicating of schemata
Revit Extensible Storage
© 2011 Autodesk
33
Summary and Further Reading
© 2011 Autodesk
Class Summary

Overview of the Revit API Extensible Storage functionality
 Creating an extensible storage schema
 Storing simple and complex data in a schema entity
 Attaching a schema entity to a Revit database element
 Listing and deleting schemata
 Available sample applications





FamilyStorage
UpgradeSchema
Dynamic Section View
Schema Wrapper Tools
Extensible Storage Manager
Revit Extensible Storage
© 2011 Autodesk
35
Materials

Presentation


Handout document


CP6760-L_tammik_estorage.pptx
CP6760-L_tammik_estorage.pdf
Sample code

CP4451_tammik_estorage.zip
Estorage – C# sample code
 EstorageVb – VB sample code
 FamilyStorage
 UpgradeSchema


Hands-on lab exercises

CP6760-L_tammik_estorage_lab.zip
Revit Extensible Storage
© 2011 Autodesk
36
Learning More

Revit Developer Center


Revit SDK, Samples, API Help File , Developer's Guide and Online Help



http://thebuildingcoder.typepad.com
ADN, The Autodesk Developer Network


http://www.autodesk.com/apitraining
The Building Coder, Jeremy Tammik's Revit API Blog


http://discussion.autodesk.com > Revit Architecture > Revit API
API Training Classes


http://www.adskconsulting.com/adn/cs/api_course_sched.php > Revit API
Discussion Group


http://www.autodesk.com/revitapi-wikihelp
DevTV Introduction to Revit Programming
Revit API Webcasts and Trainings


http://www.autodesk.com/developrevit
http://www.autodesk.com/joinadn
DevHelp Online for ADN members

http://adn.autodesk.com
Revit Extensible Storage
© 2011 Autodesk
37
Autodesk University Session Feedback
Your feedback is very important to Autodesk
 Complete the session survey on your
mobile device, PC or at a survey station
 Each session survey completed is entered
for a daily drawing for a free AU 2012 pass
 You can help make AU 2012 better!
Complete the AU Conference Survey at a survey station and receive an AU 2011 T-Shirt
Revit Extensible Storage
© 2011 Autodesk
38
Autodesk, AutoCAD* [*if/when mentioned in the pertinent material, followed by an alphabetical list of all other trademarks mentioned in the material] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to their respective holders. Autodesk reserves the right to alter product and
services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may appear in this document. © 2011 Autodesk, Inc. All rights reserved.
© 2011 Autodesk