1. CP231-2: Putting the “I” in BIM Revit API Parameters In-Depth
Image courtesy of Hobart, Yañez, Ramos, Maguey, and Martínez
CP231-2: Putting the “I” in BIM Revit API Parameters In-Depth
Matt Mason
Director, Software Development, IMAGINiT Technologies

2. Agenda Introductions & Goals Parameter Fundamentals
Parameter API Fundamentals
The Parameter API in depth:
Reading, Setting, Creating, Hiding
Parameters and Families
Things to Do With Parameters
Importing and Exporting Data
Reporting
Validation and Cleaning Up

3. Introduction Matt Mason
Director, Software Development, IMAGINiT Technologies (merged with Avatech Solutions)
Veteran of 80 Small/Medium Revit API projects and 9 large API projects over 6 years.
Packaged Software Developer:
Avatech Utilities for Revit
BIMreview – now Autodesk Revit Model Review
Scan to BIM for Revit
Occasional Revit API Blogger at:

4. Audience Survey What Type of Company Do You Work For?
Architecture Firm
A/E/C Firm
Software Firm
Educational Institution
Other?

5. Which flavor(s) of Revit are you interested in?
Audience Survey
Which flavor(s) of Revit are you interested in?
Architecture
Structure
MEP

6. Amount of Revit Experience?
Audience Survey
Amount of Revit Experience?
None?
A little?
A lot?
Expert?

7. Amount of Revit API Experience?
Audience Survey
Amount of Revit API Experience?
None?
A little?
A lot?
Expert?

8. The “Revit API Track” And More!!! Id Title Speaker CP220-2
Introduction to the Revit API
Rod Howarth
CP228-2
Optimal Use of New Revit 2011 Programming Features
Jeremy Tammik
CP231-2
Putting the “I” in “BIM”: Parameters in the Revit API
Matt Mason
CP234-2
Exactly What You Want, and Faster: 2011 Programming Optimization
CP316-1
Presenting Your Analysis Data in Revit 2011
Harry Mattison
CP319-1
Analyze the Geometry of Buildings using the Revit API
Scott Conover
CP327-1
Applied Dynamics: Using Dynamic Model Update in the Revit API
CP316-3U
All Systems Go: The Revit MEP API
And More!!!

9. Goals and Housekeeping
60-minute class
In depth coverage of Parameters and the Parameter API
Examples to inspire what’s possible
Housekeeping
All samples are in C#
Samples are posted online
Use to convert to VB.NET if desired

10. Why Parameters? Parameters were the first API
Parameters are STILL the most powerful API
Parameters are a big part of the “I” in “BIM”

11. Quick Parameter Fundamentals
Where do parameters come from?
Where do they live?
Which parameters will be on a certain kind of element?

12. Quick Parameter Fundamentals: Shared
Shared Parameter: Guaranteed to be recognizable and unique across all Revit families and projects.
# This is a Revit shared parameter file. # Do not edit manually. *META VERSION MINVERSION META 2 1 *GROUP ID NAME GROUP 1 test *PARAM GUID NAME DATATYPE DATACATEGORY GROUP VISIBLE PARAM ebe91ef6-0ec6-4e1a-aec0-5344a0556bbc SurfaceArea AREA 1 1

13. Parameter API Fundamentals

14. Parameter API Fundamentals
From Elements to Parameters:
// get our active document
Document doc = commandData.Application.ActiveUIDocument.Document;
// get the element we care about. In this case, the project info:
Element projInfo = doc.ProjectInformation;
// go through all of the parameters and show them individually:
foreach (Parameter p in projInfo.Parameters) {
TaskDialog.Show("Parameters", p.Definition.Name + ": " + p.AsString()); }

15. Parameter API In Depth: Values
Parameter Storage Types:
String (Text)
Double (Number)
Integer (Whole Number)
ElementId (Revit Element)
None/Invalid
Reading Methods:
AsString()
AsDouble()
AsInteger()
AsElementId()
AsValueString()
NOTE:
Units are Revit internal
Blank ElementId = -1

16. Quick Note: Schedule Keys are Elements!
Parameter API in Depth
private string getParameterText(Parameter p) {
switch (p.StorageType)
case StorageType.String:
return p.AsString();
case StorageType.Integer:
return p.AsInteger().ToString();
case StorageType.Double:
// check to see if there's a value string first!
if (p.AsValueString() != null) return p.AsValueString();
return p.AsDouble().ToString();
case StorageType.ElementId: ElementId eid = p.AsElementId(); if (eid.IntegerValue < 0) return "(none)"; // blank // get the element, return the name Element eObj = p.Element.Document.get_Element(eid); return eObj.Name; default: return "N/A"; }
Quick Note: Schedule Keys are Elements!

17. Parameter API in Depth: Shorthand
// get right to reading the value: String number = myRoom.Parameters[“Number”].AsString();

18. Parameter API in Depth: Type vs. Instance
ElementId wallTypeId = myWall.GetTypeId(); Element myWallType = doc.get_Element( wallTypeId ); Double width = myWallType.Parameters[“Width”].AsDouble();
Wall
(Instance
Parameters)
WallType
(Type
Parameters)

19. Parameter API in Depth BuiltIn Parameters Currently about 3000 of them
All contained in the BuiltInParameter enum
May or may not be “visible”
// get our active document
Document doc = commandData.Application.ActiveUIDocument.Document;
// get the element we care about. In this case, the project info:
Element projInfo = doc.ProjectInformation;
// get the builtin parameter
Parameter p = projInfo.get_Parameter(BuiltInParameter.PROJECT_NAME);
TaskDialog.Show("Project", "The project name: " + p.AsString());
Other advantage: no language issue

20. Parameter API in Depth: RevitLookup
Key part of the development process
Now part of the SDK

21. Parameter API in Depth: Setting
Based on the parameter storage type:
Set (String): Text
Set (Double): Number – usually in Revit’s internal units
Set (Integer)
Set (ElementId): The ElementId (or -1 for blank)
SetValueString( string ): A dimension value in user units (i.e. 5’ 7”)

22. Parameter API in Depth: Setting
Parameter param = myWall.get_Parameter( BuiltInParameter.WALL_USER_HEIGHT_PARAM); // setting the parameter by internal value (decimal feet) param.Set( 20.5 ); // setting the parameter by the Display Value param.SetValueString( "20' 6\"" );

23. Parameter API in Depth: What Can We Change?
Nothing is documented
Everything is experimental/investigative
The “IsReadOnly” is the key
Typical Wall:
* These may be writable depending on other parameters/situations
Read-Only Parameters
Writable Parameters
Area, Base Extension Distance*, Base is Attached *, Length, Related To Mass, Top Extension Distance *, Top is Attached *, Unconnected Height *, Volume
Base Constraint, Base Offset, Comments, Location Line, Mark, Phase Created, Phase Demolished, Room Bounding, Structural Usage, Top Constraint, Top Offset,

24. Parameter API in Depth: Creating Parameters
Create Shared Parameters
Created via the DefinitionFile class

25. Parameter API in Depth: Creating Parameters
// get the shared parameter file
DefinitionFile file = app.OpenSharedParameterFile();
// if our group is not there, create it
DefinitionGroup group = file.Groups.get_Item("Room");
if (group == null) group = file.Groups.Create("Room");
// add our parameter to the group
Definition def =
group.Definitions.Create("Target Area", ParameterType.Area, true);
// now if we want it in the project, we need to bind it to categories
CategorySet cats = app.Create.NewCategorySet();
cats.Insert( doc.Settings.Categories.get_Item(BuiltInCategory.OST_Rooms));
// create a binding - instance or type:
InstanceBinding bind = app.Create.NewInstanceBinding(cats);
doc.ParameterBindings.Insert(def, bind, BuiltInParameterGroup.PG_AREA);

26. Parameter API in Depth: Hiding Parameters
Shared Parameters can be marked as HIDDEN
Visible to the API but not to the end-user
The parameter stays hidden forever!

27. Parameter API in Depth: Hiding
// get the shared parameter file DefinitionFile file = app.OpenSharedParameterFile(); // if our group is not there, create it DefinitionGroup group = file.Groups.get_Item("ID"); if (group == null) group = file.Groups.Create("ID"); // add our parameter to the group Definition def = group.Definitions.Create("Copyright", ParameterType.Text, false); CategorySet cats = app.Create.NewCategorySet(); cats.Insert(doc.Settings.Categories.get_Item(BuiltInCategory.OST_SpecialtyEquipment)); InstanceBinding bind = app.Create.NewInstanceBinding(cats); doc.ParameterBindings.Insert(def, bind);

28. Parameters and Families
Family API works differently with parameters
Everything done via the FamilyManager class
if (doc.IsFamilyDocument) {
FamilyManager manager = doc.FamilyManager;
TaskDialog.Show("Family", "There are " + manager.Types.Size.ToString() + " sizes"); }

29. Parameters and Families
Use the FamilyManager to:
Add Parameter (add a family parameter or a shared parameter)
Swap Instance/Type parameter definition
Set
SetValueString
SetFormula
MakeReporting / MakeNonReporting

30. Parameters and Families
private void setFamilyParams(Document doc) { FamilyManager manager = doc.FamilyManager; // lookup the family parameters FamilyParameter manufacturer = lookupFamParam(manager, "Manufacturer"); FamilyParameter partNumber = lookupFamParam(manager, "Model"); // set them manager.Set(partNumber, "BR "); manager.SetFormula(manufacturer, "\"VIKING\""); }

31. Parameters and Families
private FamilyParameter lookupFamParam(FamilyManager fm, string name) { // lookup the family parameter foreach (FamilyParameter fp in fm.Parameters) if (fp.Definition.Name.ToUpper() == name.ToUpper()) return fp; } throw new ApplicationException("Unable to find parameter: " + name);

32. Things to do with Parameters
Update Parameters
Door Mark Update
MEP Parameter Tool
Translation (Revit Translation)
Validation
Fire Ratings
Model Review
Family Parameter Update
Import/Export Data
Room Manager
Export Keynotes
Revit DB Link

33. Questions?

34. Next Steps…
Miroslav Schonauer’s “Storing Complex Per-Document and Per-Instance Data in Revit”

35. Matt Mason mmason@rand.com
Autodesk [and other] 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. © 2010 Autodesk, Inc. All rights reserved.