Building Coder（Revit 二次開發） - 可擴充存儲

原文連結： Extensible Storage

我們之前讨論過 Revit 2012 API 中一些主要的特性，其中不少是開發者期望的功能。這裡我想談談另外一個熱點功能，實際上 Revit 2012 API 做得比我們期望的還要好。

提問：

我如何用 Revit API 将定制的業務資料存儲到 Revit 檔案中？

回答：

使用共享參數是一種選擇。這個方案有些複雜，包括正确地建立共享參數文本檔案。你可以選擇是否将共享參數共享參數設定為使用者可見。整個過程可以參考SDK例程FireRating和我其它幾篇博文：

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

Revit 2012 中，一個主要的API增強就是“可擴充存儲”機制。它提供了一個全新的存儲方案，而且對使用者是不可見的。其實可擴充存儲也是Revit 2012 API新特性中被重點介紹的。

可擴充存儲

現在 Revit API 允許開發者定制一個像類一樣的樣式(Schema)結構，并且可以将該結構的執行個體附着到Revit模型中的任意元素。這個功能可以完全替代不可見的共享參數。基于樣式的資料儲存在 Revit 模型中，并且允許高層的、中繼資料增強的和面向對象的資料結構。樣式資料可以被設定為對不同的使用者可讀或者可寫。目前Revit API支援的使用者類别有“所有使用者”、“指定應用程式供應商”和“一個供應商提供的指定應用程式”。

和可擴充存儲相關的類都被定義在命名空間 Autodesk.Revit.DB.ExtensibleStorage 中：

• Schema – 包含一個唯一的樣式編号，讀寫權限和一個資料字段集合。
• Entity – 包含Schema資料的對象，可被插入 Revit 元素。
• Field – 包含資料名稱、類型和機關資訊。是通路 Entity 中資料的鍵
• SchemaBuilder – 用于建立樣式定義。
• FieldBuilder – 幫助類。配合SchemaBuilder使用來建立一個新字段。

目前 Revit API 支援的資料類型有：

• 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> – TKey 不能為 double, float, XYZ, and UV 類型)
• Autodesk.Revit.DB.ExtensibleStorage.Entity (Schema 執行個體，也稱為 SubSchema)

下面是使用可擴充存儲的一個簡單例子：

/// <summary>
/// 建立一個資料結構，将其附着到一面牆。為資料結構填充資料，并從牆體取回這些資料
/// </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();
}
           

Revit 2012 SDK 包含了一個更加完整的例程：ExtensibleStorageManager。

上面提到的 VendorId 和 add-in manifest 檔案中新增的 VendorId ( new required VendorId tag in the add-in manifest) 是同一個值。ADSK 是 Autodesk 使用的 VendorId，第三方開發者應該使用自己的 Autodesk 注冊開發者 Symbol RDS ( Autodesk Registered Developer Symbol RDS)。