Transcript Corporate Overview—4x3 PPT Version

Extensible Storage
Jeremy Tammik
Principal Developer Consultant
© 2012 Autodesk
Extensible Storage
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.
© 2012 Autodesk
Extensible Storage
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
Revit 2013 DataStorage element
Available sample applications
Prerequisites: we assume prior knowledge of

Basic .NET programming skills
 Basic Revit API knowledge
© 2012 Autodesk
Extensible Storage
Learning Objectives






Understand estorage concepts and real-world techniques
Programmatically create and populate a schema
Read, write, update and delete extensible storage data
Make use of the Revit 2013 DataStorage Element
Handle versioning issues upgrading and extending schemata
Extract and display estorage data and serialize and de-serialize
schemata to XML
© 2012 Autodesk
Extensible Storage
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
Use a DataStorage element
Additional observations
Sample applications
Learning more
© 2012 Autodesk
Extensible Storage
Introduction and Basics
© 2012 Autodesk
Extensible Storage
What is Extensible Storage?





Programmatically store arbitrary auxiliary data in Revit document
Simple data types such as integer, double, string, element id
Complex structures such as lists and dictionaries
Can replace old technique using shared parameters
Read and write access can be restricted
© 2012 Autodesk
Extensible Storage
Revit Storage Option Evolution



OLE Structured Storage used internally
Shared parameters
Estorage
© 2012 Autodesk
Extensible Storage
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, incl. dedicated DataStorage
Schema defines data structure through a list of fields
Entity holds actual data, attached to Revit element
© 2012 Autodesk
Extensible Storage
Shared Parameters versus Estorage




Units
High-level objects
Track elements on deletion or work share remapping
Selectively hide or expose data
© 2012 Autodesk
Extensible Storage
Estorage Basics

Data structure definition

Schema and its fields
 Object oriented class definition, or database table

Data instance container

Entity
 Object oriented class instance, or database row

Autodesk.Revit.DB.ExtensibleStorage namespace classes





Schema
SchemaBuilder
Field
FieldBuilder
Entity
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
Examples
Learning by doing
© 2012 Autodesk
Extensible Storage
Estorage of a Simple XYZ Point




Create data structure definition, i.e. the schema and its fields
Create data instance container, the entity
Populate the entity with data
Attach it to an element
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
Determine Estorage Use in Document




Check whether any elements 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
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
Estorage Deletion

Individual entity: Element.DeleteEntity




Example usage in UpgradeSchema
Entire schema in all documents:
Schema.EraseSchemaAndAllEntities
Arguments schema and overrideWriteAccessWithUserPermission
Demo and examine the code

Command 4 Delete
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
Revit 2013 DataStorage Element



Dedicated data storage element
Logically organise sets of estorage entities on separate elements
Update one set of data in a local workshared project without
locking other elements
© 2012 Autodesk
Extensible Storage
Write to DataStorage Element

Create data storage element




Static Create method
Create entity to store data
Populate entity with data
Set entity on data storage element
DataStorage myElement = DataStorage.Create( doc );
Entity entity = new Entity( mySchema );
entity.Set( ... );
myElement.SetEntity( entity );
© 2012 Autodesk
Extensible Storage
Read from DataStorage Element



Retrieve DataStorage element from database
Retrieve entity from data storage element
Extract data from entity
Element myElement =
new FilteredElementCollector( doc )
.OfClass( typeof( DataStorage ) )
.FirstElement();
Entity ent = myElement.GetEntity( mySchema );
var x = ent.Get<...>( "..." );
© 2012 Autodesk
Extensible Storage
Identifying DataStorage Element





You might use a singleton DataStorage element
Data storage elements from other add-ins
Use the DataStorage element UniqueId property?
Use the schema GUID property?
Create auxiliary identification schema?
http://thebuildingcoder.typepad.com/blog/2012/05/devblog-devcamp-element-and-project-wide-data.html#6
© 2012 Autodesk
Extensible Storage
Additional Observations
© 2012 Autodesk
Extensible Storage
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





Estorage does not flag types as different for Transfer Project Standards
Worksharing updates ElementId in estorage
Retrieving elements with specific schema data
Checking for a valid schema entity on an element
One entity per schema per element
Schemata remain in memory
http://thebuildingcoder.typepad.com/blog/2011/06/extensible-storage-features.html
© 2012 Autodesk
Extensible Storage
Sample Applications
© 2012 Autodesk
Extensible Storage
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 entity to the family
Family documentFamily = doc.OwnerFamily;
Entity newEntity = MakeEntity( new XYZ( 1, 2, 3 ) );
documentFamily.SetEntity( newEntity );

GetFamilyData retrieves stored data from family via the instance
Family family = familyInstance.Symbol.Family;
Entity entity = family.GetEntity( schema );

Demo and examine the code

Create new family, run AddDataToFamily, save
 Create new project, insert instance, run GetFamilyData
© 2012 Autodesk
Extensible Storage
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 event
Detect, read data and delete all schema v1 entities
Create and populate v2 entities for them instead
Demo and examine the code
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
Schema Wrapper Tools



C# library included ExtensibleStorageManager SDK sample
Define wrappers for Schema, SchemaBuilder, Field, FieldBuilder
Provides easy serialization of schema data to XML
Displays data of a schema entity
© 2012 Autodesk
Extensible Storage
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
© 2012 Autodesk
Extensible Storage
Summary and
Further Reading
© 2012 Autodesk
Extensible Storage
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
Revit 2013 DataStorage element
Available sample applications





FamilyStorage
UpgradeSchema
Dynamic Section View
Schema Wrapper Tools
Extensible Storage Manager
© 2012 Autodesk
Extensible Storage
Materials

Blog posts


http://thebuildingcoder.typepad.com/storage
Autodesk University 2011 class and hands-on lab





Presentations, hand-outs, sample code and lab exercises
CP4451_tammik_estorage.pdf – handout document
CP4451_tammik_estorage.zip – samples mentioned above
CP6760-L_tammik_estorage.pdf – handout document
CP6760-L_tammik_estorage_lab.zip – hands-on lab exercises
© 2012 Autodesk
Extensible Storage
Learning More

Revit Developer Center: DevTV introduction, SDK, Samples, API Help


Developer Guide and Online Help




http://adndevblog.typepad.com/AEC
http://thebuildingcoder.typepad.com
ADN, The Autodesk Developer Network


http://www.autodesk.com/apitraining
ADN AEC DevBlog and The Building Coder 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
http://www.adskconsulting.com/adn/cs/api_course_webcast_archive.php > Revit API
Discussion Group


http://www.autodesk.com/revitapi-wikihelp
Public ADN Revit and Revit MEP API Webcasts, Trainings and Archives


http://www.autodesk.com/developrevit
http://www.autodesk.com/joinadn
DevHelp Online for ADN members

http://adn.autodesk.com
© 2012 Autodesk
Extensible Storage
Autodesk, AutoCAD, Civil 3D, DWG, Green Building Studio, Navisworks, and Revit 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.
© 2012 Autodesk, Inc. All rights reserved.
© 2012 Autodesk
Extensible Storage