Revit API Intro Labs

Lab2 – DB Element
Created by M. Harada, July 2010
Updated by DevTech AEC WG
Last modified: 8/18/2023

<VB.NET>VB.NET Version</VB.NET>

Objective: In this lab, we will learn how an element is represented in Revit and how to retrieve
information about an element. We’ll learn how to:

 Identify an element
 Retrieve a set of properties of an element
 Retrieve a specific property of an element
 Retrieve location information
 Retrieve geometry information

Tasks: We’ll write a command that prompts the user to pick an element, identify the kind of element,
and displays its information about properties, location and geometry:

1. Pick an element.
2. Show basic information about the element and its family type (i.e., class name, category and
element Id).
3. Identify the element that you have picked. (e.g., is it a wall, window or door?)
4. Show the set of properties of the element and its family type.
5. Show specific properties of the element and its family type.
6. Show the location information of the element
7. Show the geometry information of the element (Optional)

Figure 1 and 2 shows the sample images of output after running the command that you will be defining
in this lab:
 Figure 1. Dialogs showing basic information and identity of an element.

Figure 2. Dialogs showing properties (or parameters) of an element and of its type
The following is the breakdown of step by step instructions in this lab:

1. Define A New External Command

2. Pick an Element
3. Basic Element Information
4. Identify Element
5. Parameters
6. Location Information
7. Geometry Information (Optional)
8. Summary

1. Define A New External Command

We’ll add another external command to the current project. Do not create a new project, but use the
existing one.

1.1 Add a new file and define another external command to your project. Let’s name them as follows:
 File name: 2_DbElement.vb (or .cs)
 Command class name: DBElement

(Once again, you may choose to use any names you want here. When you do so, just remember what
you are calling your own project, and substitute these names as needed while following the instruction
in this document.)

Required Namespaces:
Namespaces needed for this lab are:
 (System.Linq) (needed for Lab3)
 Autodesk.Revit.DB
 Autodesk.Revit.UI
 Autodesk.Revit.ApplicationServices
 Autodesk.Revit.Attributes
 Autodesk.Revit.UI.Selection (this is for selection)

Note (VB.NET only): if you are writing in VB.NET and you import namespaces at the project level, (i.e., in
the project properties, there is no need to explicitly import in each file.

1.2 To make it easier to access the top level objects in our labs, we will define member variables to the
keep the top level object accessible throughout this document or the class. Revit has a concept of
separation between DB and UI objects. This applies to the Revit application and document objects.
 These top level objects are accessible as follows:

 UIApplication  commandData.Application
 Application UIApplication.Application
 UIDocument  UIApplication.ActiveUIDocument
 Document  UIDocument.Document

Define member variables, e.g., m_rvtApp and m_rvtDoc, to keep DB level application and document
respectively. The following is an example:

<VB.NET>
'' DB Element – learn about Revit element
<Transaction(TransactionMode.Manual)> _
Public Class DBElement
Implements IExternalCommand

'' Member variables

Dim m_rvtApp As Application
Dim m_rvtDoc As Document

Public Function Execute(ByVal commandData As ExternalCommandData, _

ByRef message As String, _
ByVal elements As ElementSet) _
As Result _
Implements IExternalCommand.Execute

'' Get the access to the top most objects.

Dim rvtUIApp As UIApplication = commandData.Application
Dim rvtUIDoc As UIDocument = rvtUIApp.ActiveUIDocument
m_rvtApp = rvtUIApp.Application
m_rvtDoc = rvtUIDoc.Document

'' ...

Return Result.Succeeded

End Function

End Class
</VB.NET>

Note: about VB.NET vs. C# behavior difference

There is a behavior difference between VB.NET and C#; VB.NET automatically adds the root namespace,
while C# does not.

For C# developer: To make the code easier to read in this instruction, we are omitting the namespace
from now on. Please insert the code between the namespace as need.

<C#>
namespace IntroCs
{
}
</C#>

Note: Using the member variable this way is just to make our life slightly easier during our exercises. You
may find other approaches more suitable depending on the context of your program.

2. Pick an Element
Autodesk.Revit.DB.Element is a base class for objects in the Revit project database. We are going to
pick an arbitrary element on the UI screen and examine it to learn more about elements in Revit.

We can use one of overloaded PickObject() method to pick an object on the screen:
 UIDocument.Selection.PickObject(ObjectType.Element, promptString)

(We’ll come to the topic of UI and selection when we get into the UI portion of the training. For now,
this should be enough for the purpose of this lab.)

The following code demonstrates the usage:

<VB.NET>
'' (1) pick an object on a screen.

Dim ref As Reference = _

rvtUIDoc.Selection.PickObject(ObjectType.Element, "Pick an element")

'' we have picked something.

Dim elem As Element = m_rvtDoc.GetElement(ref)

</VB.NET>

PickObject() returns Reference object. You can retrieve the Element from the reference object
returned.

3. Basic Element Information

In typical programming or usage of APIs, we identify the given object by checking its class names. Does
the same apply to Revit API? The exercise in this section will answer this question.

3.1 Write a function which takes Element as an argument, and display the following properties of the
given element:
 Class name (or Type in .NET)
  Category name
 Id (Element Id)

Then do the same with the family type of the given element. To get to the family type of the given
element, you can use Element.GetTypeId() to obtain its Id first, then use
Document.GetElement(elementId).
Let’s name this function, for example, ShowBasicElementInfo(). The following shows a sample code to
do this:

<VB.NET>
Public Sub ShowBasicElementInfo(ByVal elem As Element)

'' let's see what kind of element we got.

Dim s As String = "You picked:" + vbCr
s = s + " Class name = " + elem.GetType.Name + vbCr
s = s + " Category = " + elem.Category.Name + vbCr
s = s + " Element id = " + elem.Id.ToString + vbCr + vbCr

'' and check its type info.

Dim elemTypeId As ElementId = elem.GetTypeId
Dim elemType As ElementType = m_rvtDoc.GetElement(elemTypeId)
s = s + "Its ElementType:" + vbCr
s = s + " Class name = " + elemType.GetType.Name + vbCr
s = s + " Category = " + elemType.Category.Name + vbCr
s = s + " Element type id = " + elemType.Id.ToString + vbCr

'' show what we got.

TaskDialog.Show("Basic Element Info", s)

End Sub
</VB.NET>

Then, call this function from your main Execute() method right after you have picked an element:

<VB.NET>
'' we have picked something.
Dim elem As Element = ref.Element

'' (2) let's see what kind of element we got.

ShowBasicElementInfo(elem)
</VB.NET>

3.2 Build the project. Add manifest file, e.g.:

<AddIn Type="Command">
<Text>DB Element</Text>
<FullClassName>IntroVb.DBElement</FullClassName>
<Assembly>C:\...\IntroVB.dll</Assembly>
<AddInId>827AC040-6F44-4c03-82FE-292705580800</AddInId>
<VendorId>ADNP</VendorId>
<VendorDescription>Autodesk, Inc. www.autodesk.com</VendorDescription>
 </AddIn>

Run the command, “DB Element”. Pick an element. You will see a dialog like following showing the
class, category and id of the element that you just picked (Figure 3). Try picking a few other element and
observe the output.

Figure3. Dialog showing the a few properties from a door.

Discussion:

 Compare the class names and categories among different elements, such as walls, doors and
windows. What do you observe?
 Could you identify the element from the class name?
 Could you identify the element from the category?

Discuss these with your colleagues and instructor.

4. Identify Element
As you have found out by now, a class name is not enough to identify an element in Revit. Depending on
an element you have, you will need to check the following:
 Class name
 Category
 If an element is Element Type (Symbol) or not

Table 1 shows the examples of a few elements with their class names and categories used to identify the
element. They are divided into four areas: System Family vs. Component Family, and Family Type vs.
Instance. This probably gives you slightly clear view of why you can identity some element by the class
name and some requires category.
 A system family are a built-in object in Revit. There is a designated class for it. You can use it to
identify the element.
 A component family has a generic form as FamilyInstance/FamilySymbol. Category is the way to
further identify the kind of object it is representing in Revit.
 System Family Component Family
FamilySymbol
WallType &
Family Type
FloorType Category - Doors,
Windows
FamilyInstance
Wall &
Instance
Floor Category - Doors,
Windows

Table 1. class names and categories that you can use to identify
an element for walls, floors, doors and windows.

Now that we have understood how an element is represented in Revit database, let’s add a code to
identify an element. Here is an example:

<VB.NET>
'' identify the type of the element known to the UI.
Public Sub IdentifyElement(ByVal elem As Element)

'' An instance of a system family has a designated class.

'' You can use it identify the type of element.
'' e.g., walls, floors, roofs.
''
Dim s As String = ""

If TypeOf elem Is Wall Then

s = "Wall"
ElseIf TypeOf elem Is Floor Then
s = "Floor"
ElseIf TypeOf elem Is RoofBase Then
s = "Roof"
ElseIf TypeOf elem Is FamilyInstance Then
'' An instance of a component family is all FamilyInstance.
'' We'll need to further check its category.
'' e.g., Doors, Windows, Furnitures.
If elem.Category.Id.IntegerValue = _
BuiltInCategory.OST_Doors Then
s = "Door"
ElseIf elem.Category.Id.IntegerValue = _
BuiltInCategory.OST_Windows Then
s = "Window"
 ElseIf elem.Category.Id.IntegerValue = _
BuiltInCategory.OST_Furniture Then
s = "Furniture"
Else
s = "Component family instance" '' e.g. Plant
End If

'' check the base class. e.g., CeilingAndFloor.

ElseIf TypeOf elem Is HostObject Then
s = "System family instance"
Else
s = "Other"
End If

s = "You have picked: " + s

'' show it.
TaskDialog.Show("Identify Element", s)

End Sub
</VB.NET>

Call this function from your main Execute() method right after ShowBasicElementInfo():

<VB.NET>
'' (2) let's see what kind of element we got.
ShowBasicElementInfo(elem)

'' (3) identify each major types of element.

IdentifyElement(elem)
</VB.NET>

Build and run the command “DB Element” once again to see if you can identify an element you have
picked. Figure 4 shows a sample image of running the command.

Figure 4. Identifying an element

5. Parameters
Parameters property of an Element class largely corresponds to an element or family “properties” that
you see in the UI. In the Revit API, there are two ways to access those properties or parameters:

 Element.Parameter– takes an argument that can identify the kind of parameter and returns the
single parameter.
 Element.LookupParameter – returns a single parameter given the name.
 Element. GetOrderedParameters – returns a set of parameters applicable to the given element.
 Element.GetParameters – returns all parameters with the given name.

5.1 Retrieving a Set of Parameters through Parameters()

Let’s first look at the Parameters(). The code below demonstrates the usage. Parameters() return a set
of parameters. You can simply loop through it to access each parameter. The main part that you will
need to pay attention is that that you will need to parse each parameter by the StorageType; a
parameter can be Integer, Double, String and ElementId. Depending on the StorageType, you will need
to choose the method to get the actual value.

<VB.NET>
'' show all the parameter values of the element
Public Sub ShowParameters(ByVal elem As Element, ByVal header As String)

Dim s As String = String.Empty

Dim params As ParameterSet = elem. GetOrderedParameters()

For Each param As Parameter In params

Dim name As String = param.Definition.Name
'' see the helper function below
Dim val As String = ParameterToString(param)
s += name + " = " + val + vbCr
Next

TaskDialog.Show(header, s)

End Sub

''
'' Helper function: return a string from of a given parameter.
''
Public Shared Function ParameterToString(ByVal param As Parameter) _
As String

Dim val As String = "none"

If param Is Nothing Then

Return val
End If

'' to get to the parameter value, we need to pause it depending on

'' its strage type
 Select Case param.StorageType
Case StorageType.Double
Dim dVal As Double = param.AsDouble
val = dVal.ToString

Case StorageType.Integer
Dim iVal As Integer = param.AsInteger
val = iVal.ToString()

Case StorageType.String
Dim sVal As String = param.AsString
val = sVal

Case StorageType.ElementId
Dim idVal As ElementId = param.AsElementId
val = idVal.IntegerValue.ToString

Case StorageType.None
Case Else

End Select

Return val

End Function
</VB.NET>

Call this function from your main Execute() method after IdentifyElement(). You may also use the same
function to display its family type information.

<VB.NET>
'' (3) identify each major types of element.
IdentifyElement(elem)

'' (4) first parameters.

ShowParameters(elem, "Element Parameters")

'' check to see its type parameter as well

''
Dim elemTypeId As ElementId = elem.GetTypeId
Dim elemType As ElementType = m_rvtDoc.GetElement(elemTypeId)
ShowParameters(elemType, "Type Parameters")
</VB.NET>

Build and run the command “DB Element” once again. You should be a list of parameters displayed in
dialogs. Figure 2 (on page 2) shows a sample image of running the command.

5.2 Retrieving an Individual Parameter Using BuiltInParameter

There are four ways to access individual parameters:

  Parameter(BuiltInParameter) – retrieve a parameter using a parameter Id.
 LookupParameter(String) – retrieve using the name.
 Parameter(Definition) – retrieve from its definition.
 Parameter(GUID) – retrieve shared parameter using GUID for a shared parameter.

Here we will take a look at the first and second. Calling LookupParameter(Xxx) method itself using the
name is straightforward. However, using name has a disadvantage of depending on a language version
of Revit you are running. Therefore, using BuiltInParameter is more ideal. The trick here is to find out
which parameter Id or BuiltInParameter to use. If you look at the RevitAPI.chm documentation, under
BuiltInParameter Enum section, you will see hundreds of BuiltinParameters defined there. Among those
BuiltInParameters, only fraction of enum are applicable to a given element. How can we find out which
BuiltInParameter to use to retrieve a specific parameter?

RevitLookup tool comes handy to explore and find out which BuiltInParameter corresponds to which
parameter name. When you want to find out a parameter for a specific type of element, simple click on
the same type of object in the project >> [Snoop Current Selection …] >> [Parameters]. When you click
on each parameter name, you can check its [Definition] to find out the corresponding BuiltInParameter
(Figure 5).

Figure 5. Use RevitLookup to check the definition of parameter.

Another thing that may worth mentioning is that if you look at the list of BuiltInParameters, using [Built-
in Enums Snoop…] or [Built-in Enumes Map…] button, you will see more parameters than you see in
parameters list. Occasionally, you may find some useful properties there. Such a sample will be:

 BuiltInParameter.SYMBOL_FAMILY_AND_TYPE_NAMES_PARAM – family and type name

 BuiltInParameter.SYMBOL_FAMILY_NAME_PARAM – family name

You can use these to retrieve family and type names of the given element. Figure 6 shows a sample
enum mapping.
 Figure 6. you can use RevitLookup to explore which BuiltInParameter to use.

Below is a sampler that shows how to retrieve some of commonly used properties. Explore the
BuiltInParameters in RevitLookup and try writing a function to retrieve a few parameters of your
interests using the code below as an example.

<VB.NET>
'' examples of retrieving a specific parameter indivisually.
'' (hard coding for simplicity. This function works best
'' with walls and doors.)
''
Public Sub RetrieveParameter(ByVal elem As Element, ByVal header As
String)
 Dim s As String = String.Empty

'' as an experiment, let's pick up some arbitrary parameters.

'' comments - most of instance has this parameter

'' (1) by BuiltInParameter.

Dim param As Parameter = _
elem.Parameter(BuiltInParameter.ALL_MODEL_INSTANCE_COMMENTS)
If param IsNot Nothing Then
s += "Comments (by BuiltInParameter) = " _
+ ParameterToString(param) + vbCr
End If

'' (2) by name. (Mark - most of instance has this parameter.)

'' if you use this method, it will language specific.

param = elem. LookupParameter("Mark")

If param IsNot Nothing Then
s += "Mark (by Name) = " + ParameterToString(param) + vbCr
End If

'' the following should be in most of type parameter

param = elem.Parameter(BuiltInParameter.ALL_MODEL_TYPE_COMMENTS)
If param IsNot Nothing Then
s += "Type Comments (by BuiltInParameter) = " _
+ ParameterToString(param) + vbCr
End If

param = elem. LookupParameter("Fire Rating")

If param IsNot Nothing Then
s += "Fire Rating (by Name) = " + ParameterToString(param) + vbCr
End If

'' using the BuiltInParameter, you can sometimes access one that is
'' not in the parameters set.
'' Note: this works only for element type.

param = elem.Parameter( _
BuiltInParameter.SYMBOL_FAMILY_AND_TYPE_NAMES_PARAM)
If param IsNot Nothing Then
s += "SYMBOL_FAMILY_AND_TYPE_NAMES_PARAM (only by
BuiltInParameter) = " + _
ParameterToString(param) + vbCr
End If

param = elem.Parameter(BuiltInParameter.SYMBOL_FAMILY_NAME_PARAM)
If param IsNot Nothing Then
s += "SYMBOL_FAMILY_NAME_PARAM (only by BuiltInParameter) = " + _
ParameterToString(param) + vbCr
End If

'' show it.

TaskDialog.Show(header, s)

End Sub
</VB.NET>

Call your function from your main Execute() method at the end. You may also use the same function
to display its family type information.

<VB.NET>
'' (4) first parameters.
ShowParameters(elem, "Element Parameters: ")

'' check to see its type parameter as well

''
Dim elemTypeId As ElementId = elem.GetTypeId
Dim elemType As ElementType = m_rvtDoc.GetElement(elemTypeId)
ShowParameters(elemType, "Type Parameters: ")

'' access to each parameters.

RetrieveParameter( _
elem, "Element Parameter (by Name and BuiltInParameter)")
'' the same logic applies to the type parameter.
RetrieveParameter( _
elemType, "Type Parameter (by Name and BuiltInParameter)")

</VB.NET>

Build and run the command “DB Element” once again. You should see a list of parameters of your
choice displayed in dialogs (Figure7).

Figure 7. You can use BuiltInParameters to access parameters individually.

6. Location Information
Location of each element is stored under Location property. A location can be point-based
(LocationPoint) or curve/line-based (LocationCurve). You will need to cast to LocationPoint or
LocationCurve in order to access more properties. The following demonstrates the usage:

<VB.NET>
'' show the location information of the given element.
'' location can be LocationPoint (e.g., furniture), and LocationCurve
'' (e.g., wall).
Public Sub ShowLocation(ByVal elem As Element)

Dim s As String = "Location Information: " + vbCr + vbCr

Dim loc As Location = elem.Location

If TypeOf loc Is LocationPoint Then

'' (1) we have a location point

''
Dim locPoint As LocationPoint = loc
Dim pt As XYZ = locPoint.Point
Dim r As Double = locPoint.Rotation

s += "LocationPoint" + vbCr
s += "Point = " + PointToString(pt) + vbCr
s += "Rotation = " + r.ToString + vbCr

ElseIf TypeOf loc Is LocationCurve Then

'' (2) we have a location curve

''
Dim locCurve As LocationCurve = loc
Dim crv As Curve = locCurve.Curve

s += "LocationCurve" + vbCr
s += "EndPoint(0)/Start Point = " + _
PointToString(crv.GetEndPoint(0)) + vbCr
s += "EndPoint(1)/End point = " + _
PointToString(crv.GetEndPoint(1)) + vbCr
s += "Length = " + crv.Length.ToString + vbCr

'' Location Curve also has property JoinType at the end

s += "JoinType(0) = " + locCurve.JoinType(0).ToString + vbCr

s += "JoinType(1) = " + locCurve.JoinType(1).ToString + vbCr

End If

'' show it

TaskDialog.Show("Show Location", s)

End Sub
 '' Helper Function: returns XYZ in a string form.
''
Public Shared Function PointToString(ByVal pt As XYZ) As String

If pt Is Nothing Then
Return ""
End If

Return "(" + pt.X.ToString("F2") + ", " + pt.Y.ToString("F2") + _

", " + pt.Z.ToString("F2") + ")"

End Function
</VB.NET>

Call your function from your main Execute() method at the end.

<VB.NET>
'' (4) first parameters.
...
'' the same logic applies to the type parameter.
RetrieveParameter(elemType, "Type Parameter (by Name and
BuiltInParameter): ")

'' (5) location

ShowLocation(elem)

</VB.NET>

Build and run the command “DB Element” once again. You should see location information displayed in
dialogs. Figure 8 shows an example of location information when you pick an element based on
Location Point, such as a door. When you pick a wall, it will be Location Line. Note, not all elements
allow accessing location information this way.

Figure 8. Sample location info.

7. Geometry Information (Optional)
The last piece of element properties that we would like to take a look is Geometry. Writing a code for
retrieving Geometry information can get a little involved and beyond the scope of this training. We‘ll
only describe a big picture here.
 Geometry Options – you can specify the detail level (Fine, Medium and Fine) when you retrieve
geometry information from an element.
 A Geometry object can be Solid, Geometry Instance, Curve or Mesh. Geometry Instance is an
instance of another element (symbol), such as a window and a door.
The code below shows the access to the high level geometry representation. For further drill down of
Solids/Faces/Edges, please use RevitLookup. RevitCommands sample has a simple example. The
following SDK samples show other geometry access with a little viewer:

 ElementViewer
 RoomViewer
 AnalyticalViewer

<VB.NET>
'' show the geometry information of the given element.
Public Sub ShowGeometry(ByVal elem As Element)

' First, set a geometry option

Dim opt As Options = m_rvtApp.Create.NewGeometryOptions
opt.DetailLevel = ViewDetailLevel.Fine

' Get the geometry from the element

Dim geomElem As GeometryElement = elem.Geometry(opt)

' If there is a geometry data, retrieve it as a string to show it.

Dim s As String
If geomElem Is Nothing Then
s = "no data"
Else
s = GeometryElementToString(geomElem)
End If

' Show it.

TaskDialog.Show("Show Geometry", s)

End Sub

'' Helper Function: parse the geometry element by geometry type.

'' see ReviCommands in the SDK sample for complete implementation.
''
Public Shared Function GeometryElementToString( _
ByVal geomElem As GeometryElement) As String

Dim str As String = String.Empty

For Each geomObj As GeometryObject In geomElem

If TypeOf geomObj Is Solid Then ' ex. wall

 Dim solid As Solid = geomObj
'str += GeometrySolidToString(solid)
str += "Solid" + vbCr

ElseIf TypeOf geomObj Is GeometryInstance Then ' ex. door/window

str += " -- Geometry.Instance -- " & vbCr

Dim geomInstance As GeometryInstance = geomObj
Dim geoElem As GeometryElement = _
geomInstance.SymbolGeometry()
str += GeometryElementToString(geoElem)

ElseIf TypeOf geomObj Is Curve Then ' ex.

Dim curv As Curve = geomObj

'str += GeometryCurveToString(curv)
str += "Curve" + vbCr

ElseIf TypeOf geomObj Is Mesh Then ' ex.

Dim mesh As Mesh = geomObj

'str += GeometryMeshToString(mesh)
str += "Mesh" + vbCr

Else
str += " *** unkown geometry type" & _
geomObj.GetType.ToString

End If

Next

Return str

End Function

</VB.NET>

Call your function from the end of your main Execute() method.

<VB.NET>
'' (5) location
ShowLocation(elem)

'' (6) geometry - the last piece. (Optional)

ShowGeometry(elem)

</VB.NET>

Build and run the command “DB Element” once again. You should be seeing the geometry information
displayed in dialogs. (Figure 9).
 Figure 9. an example of high level geometry information

8. Summary
In this lab, we have learned how an element is represented in Revit and how to retrieve information
about an element. We have learned how to:

 Identify an element using class name, category, and symbol or not.

 Retrieve a set of properties of an element using Parameters()
 Retrieve a specific property of an element using BuiltInParameter
 Retrieve location information
 Retrieve graphic information

In the next lab, we will take a look at a group of elements in the Revit database and learn how to
selectively retrieve elements of our interests, which is called element filtering.

Autodesk Developer Network