The Revit 2022 API includes an exceptional list of exciting enhancements for add-in developers, including numerous developer wishes and requests that have now been explicitly addressed:
Table of contents top level:
The information below is based on the contents of the Revit Platform API Changes and Additions.docx document included with the Revit 2022 SDK, the software developers kit available from the Revit Developer Centre.
It is also provided in the section on What's New in the Revit 2022 API help file RevitAPI.chm included with the SDK:
For convenient, easy, and effective web searching, this blog post provides a cleaned-up online HTML version of that information with numbering and table of contents added, as well as the following PDF printout of the original document included in the SDK:
The What's New section and the Changes and Additions document provide important information, both for discovering and exploring the newly added API functionality and for later reference.
If you encounter any issues migrating your existing add-ins between different versions, this is one of the first places to look.
For detailed information on all other aspects of the Revit API, please refer to the rest of the API documentation and samples provided in the SDK.
The most important things to install and always keep at hand are:
RevitAPI.chmSamples\SDKSamples.slnYou will regularly need both for research on how to solve specific Revit API programming tasks.
More in-depth official explanations and background information is provided by the online Revit API Developers Guide included in the Revit 2022 online help.
Here are links to previous discussions of What's New in the Revit API:
In Revit 2021, Revit API functionality for units of measurement migrated from enumerated identifiers to extensible identifiers represented by the ForgeTypeId class. ForgeTypeId is now used as the identifier type for more data structures in the Revit API.
A ForgeTypeId instance holds a string, called a "typeid", that uniquely identifies a Forge schema. A Forge schema is a JSON document describing a data structure, supporting data interchange between applications. A typeid string includes a namespace and version number and may look something like "autodesk.spec.aec:length-1.0.0" or "autodesk.unit.unit:meters-1.0.0". By default, comparison of ForgeTypeId values in the Revit API ignores the version number.
The new classes:
contain properties of type ForgeTypeId, following the pattern established in Revit 2021 with the UnitTypeId, SymbolTypeId, and SpecTypeId classes. Values from the DisciplineTypeId class can be used in code to replace values of the deprecated UnitGroup enumeration. For example, where you previously used UnitGroup.Structural, you would now use DisciplineTypeId.Structural. Values from the GroupTypeId and ParameterTypeId classes can be used to replace values of the BuiltInParameter and BuiltInParameterGroup enumerations, respectively, which have not yet been deprecated.
The SpecTypeId class contains several new nested classes containing ForgeTypeId properties identifying non-floating-point data types, such as integers and strings. ForgeTypeId properties in SpecTypeId and its nested classes can be used to replace values of the deprecated ParameterType enumeration. This table lists the deprecated types and their replacements:
Here are some further migrated types where the original enumeration is not yet fully deprecated:
The mapping of enumerations to different ForgeTypeId members has implications for previously existing APIs related to parameter access, parameter definitions, shared parameter creation and binding, global parameters and other utilities.
In the Definition class, the ParameterType property and the GetSpecTypeId() method are both deprecated in favor of the new method GetDataType(). GetDataType() is more general than the functions it replaces, providing a data type identifier for any parameter.
Use Parameter.IsValidDataType(ForgeTypeId) to detect any parameter data type identifier – i.e., any measurable or non-measurable spec or category.
Preferred replacements for non-deprecated members:
In the ExternalDefinitionCreationOptions class, used to create shared parameters, the implementation now offers better input validation and new capabilities.
The deprecated class constructor and Type property setter taking ParameterType values now throw an exception for input values ParameterType.Invalid or ParameterType.FamilyType. It was not possible to use this interface to create Family Type shared parameters.
However, it is now possible to create Family Type shared parameters using the replacement functions based on ForgeTypeId. The class constructor taking ForgeTypeId and the SetDataType(ForgeTypeId) method accept any spec or category identifier. Using a category identifier produces a Family Type shared parameter of the given category. Use Category.GetBuiltInCategoryTypeId(BuiltInCategory) to obtain the ForgeTypeId identifier for a given category.
Use Parameter.IsValidDataType(ForgeTypeId) to detect any parameter data type identifier – i.e., any measurable or non-measurable spec or category.
Preferred replacements for non-deprecated members:
Shared parameters can also be created and leveraged in families using members of the FamilyManager class.
Preferred replacements for non-deprecated members:
The LabelUtils class, used to obtain user-visible names for enumerations, has several changes according to the mapping from enumerations to ForgeTypeId. In addition to the replacements listed below, a new method:
returns the user visible name corresponding to a Revit discipline in the current Revit language. The implementation of the method:
has been expanded to accept a ForgeTypeId argument identifying any parameter data type. For a category identifier input, GetLabelForSpec(ForgeTypeId) returns the label of the Family Type spec for that category, e.g. "Family Type: Wall Tags".
Preferred replacements for non-deprecated members:
ParameterUtils is a new class with static utility functions related to ForgeTypeId parameter identifiers:
The ParameterUtils class contains several methods that are new in this release but also deprecated. They are offered only to assist clients in migrating code from the BuiltInParameter and BuiltInParameterGroup enumerations to the ForgeTypeId class.
Introduced for porting assistance but deprecated
SpecUtils is a new class with static utility functions related to ForgeTypeId spec identifiers:
The SpecUtils class contains two methods that are new in this release but also deprecated. They are offered only to assist clients in migrating code from the ParameterType enumeration to the ForgeTypeId class.
Introduced for porting assistance but deprecated
Changes were made to UnitUtils to clarify the meaning of some operations and to offer functions related to disciplines.
The methods GetAllSpecs() and IsSpec(ForgeTypeId) are renamed to GetAllMeasurableSpecs() and IsMeasurableSpec(ForgeTypeId) to clarify that they apply only to measurable specs, describing floating-point values associated with units of measurement, and to avoid confusion with the new Parameter class static methods GetAllSpecs() and IsSpec(ForgeTypeId), which apply to specs of all value types.
The new method:
provides a list of all available Revit disciplines, suitable for iteration. Previously iteration would have used the members of the UnitGroup enumeration.
As a part of changes made to support externalized parameter groups, three BuiltInParameterGroup enumeration values were renamed:
Note that because the name PG_ELECTRICAL now identifies a different group, client applications which do not adjust will find parameters they create now in "Electrical" instead of "Electrical Engineering".
The method:
has been enhanced to support upload of local workshared file into BIM 360 Design as a Revit Cloud Worksharing central model.
In addition, the exception UnauthenticatedUserException is removed from the documented exceptions for this method.
The methods:
have been enhanced to support creation of new cloud model Revit links. You may use ModelPathUtils. ConvertCloudGUIDsToCloudPath() to create a cloud path to use as an argument to these methods.
These other link methods:
will work with any cloud Revit link created by a Revit user or through the APIs above.
Several exceptions have changed from existing worksharing API. For the method Document.SaveAsCloudModel():
In addition, the function will now throw RevitServerModelNameBreaksConventionException when the model name breaks the project naming convention.
For the method ModelPathUtils.ConvertCloudGUIDsToCloudPath():
Some properties have been removed and replaced in this release. Because these were an immediate replacement, applications referencing the replaced properties will need to be updated immediately for this release.
The following members have been replaced:
The new property
can be used to get or set the rotation of the tag relative to its view.
IndependentTag now supports multiple references to various elements or sub-elements.
A number of properties were deprecated. The users can now access the desired leader or tagged element using their References.
All deprecated members still work in multi leader scenario by using only the first tagged reference.
The new members:
are used to bulk add or remove references from a tag, and to query if the tag references multiple elements.
RevisionSettings API replacements
The following methods have been deprecated and replaced due to terminology changes in the Revisions user interface:
Reinforcement bars now uses two diameter values instead of just one:
The following members were deprecated and replaced. Note that the deprecated members always reference the bar's "model diameter".
The methods:
that take a View as an argument have been updated to accept null for that argument. This applies to all overloads of these methods except those that work with DWF. This View argument used to be required, but now null will be used to take an appropriate default action for the import operations.
The following property has been removed and replaced in this release. Because these were an immediate replacement, applications referencing the replaced property will need to be updated immediately for this release.
The following method and property have been deprecated; the old methods referred to temperature in terms on "long", which did not match the capabilities in the UI, and had an error when referring to non-Fahrenheit temperature values.
In a terminology change, the fabrication service "group" was renamed as a "palette" in order to align with changes made in the Revit user interface. This affected the following members:
The following properties have been deprecated. Because they are not currently used and relate to not yet available capabilities, there is no replacement for these members.
Many updates have been made to the PostableCommand enumeration to match the current set of Revit commands.
A good number of commands were newly added to the enumeration:
Some enumeration values were renamed to match the current naming of the commands in the Revit UI. There is no way to preserve the old name as obsoleted so code referring to these values will need to be updated:
Finally, some commands have been removed from the Revit UI. These commands can no longer be posted, so the values have been removed from the enumeration:
Some changes have been made to existing BuiltInFailure definitions. Code that looks for or handles specific failures may need updating, as it is not possible to obsolete the replaced members, so they have been removed in this release.
The constructor for the class FilterStringRule has been obsoleted and replaced. The previous constructor has a Boolean argument for case sensitivity that was not used in View Filters and could not be used properly from the API, as all string comparisons in filters are case-insensitive:
The method FilterStringRuleEvaluator.Evaluate() still has an argument "caseSensitive", but it's never called by filter code with this argument set to true.
Due to technology limitations, the Macro Manager no longer supports Ruby language in Revit Macros. The option to create new Ruby macros has been removed from the UI and API, and existing Ruby Macros in previous version documents will be deleted during upgrade.
Autodesk.Revit.DB.TransmissionData.UserData is now used to store the systems analysis reports path, if any report exists in the document. This is to allow eTransmit to include external reports. The API method itself is not changed.
The following previously obsoleted APIs have been removed:
The new methods:
create a new instance of a ceiling in a Revit project, with one overload supporting a sloped ceiling.fac
In addition to the replacement Floor creation methods described above, the new method:
returns the id of the default floor or foundation type for a document.
The new methods:
provide access to add and remove profile sketches to wall elements that support them. Once a sketch is added, the profile sketch can be edited using SketchEditScope.
The new members:
allow assignment of a cross section type to a given wall, and determine if that type can be assigned.
The new enumerations:
enumerate the values for options related to alternate wall cross section values, especially the options available for Tapered walls.
The new methods:
return the id of the element's sketch.
The method:
returns the id of the element that owns this sketch.
The new method:
returns the ids of all the elements owned by the sketch, including elements of type:
This method works for any Sketch you can obtain from a Sketch-based element (Ceiling, Extrusion, etc.). It is available both in and outside of a SketchEditScope.
Using the new class:
allows an application to edit sketch based elements while preserving the unchanged elements that are already present in the sketch. While a Sketch editing session is active, you can add, delete or modify Sketch elements (curves, dimensions, reference planes). When you finish the session, the edited Sketch-based element will be updated. Only certain sketches are currently supported for editing:
using the new members:
The new method:
validates input curves form a valid horizontal boundary for Ceiling or Floor creation.
The new method:
checks whether split and merge regions operations can be used for this compound structure. This validator is associated with the use of the existing MergeRegionsAdjacentToSegment() and SplitRegion() methods.
Multiple new classes provide access to color fills. These classes expose color fill schemes, entries and color fill legends. You can also also a ccess the color fill scheme applied to a particular view.
The new class:
represents a color scheme that can be applied to plan and section views. Key new members of this class include:
The new class:
represents an entry in a color scheme. Key new members of this class include:
The new members:
provide access to read and apply the color fill scheme associated with a particular category in the view.
The new class:
offers the ability to create, read and modify properties of color fill legend annotation elements in a particular owner view. Key new members of this class include:
The new method:
exports one or more views and sheets in PDF format.
The options provided, in the new class:
include graphical options, paper and output format options, and the option to combine output views and sheets into a single PDF or to produce a different PDF for each view and sheet with a specific naming convention.
The new element class:
represents a named stored PDF export option available in a document. You can use this class to extract the options from this element to use for exporting to PDF, or modify or create new stored settings with different options.
Revit now provides support for Civil Alignments and their associated annotations. Alignments are imported from InfraWorks as a part of the workflow to transfer Civil Structures. The API supports read of alignment properties and geometric information, along with read/write and create of associated annotations. All new classes for the Alignments API are exposed through a different assembly in the Revit installation, located at
The new class:
represents an alignment and can be used to find alignments in a document, and to query a particular alignment's properties and to analyze alignment geometry. This object is not an Element, but the underlying Element can be obtained from this object if needed.
The new class:
represents an alignment station label annotation and can be used to find such labels in a document as well as to create and modify such labels. This object is not an Element, but the underlying Element (which is a SpotDimension instance) can be obtained from this object if needed.
The new classes:
provide options for creating a single alignment label or for creating a set of alignment labels.
The new methods:
enable the creation of reference curves, planes and points inside DirectShape elements. Explicit bounds can be provided for direct shape reference curves and planes. Revit tools that can use named references within families will also be able to select the references inside the DirectShape elements.
The overloads for these methods include an optional DirectShapeReferenceOptions input. Use:
to set the assigned name for the reference. If the name is specified, it is visible when picking the reference's geometry. Otherwise, the default DirectShape element name is displayed.
The new validator:
validates the name assigned to DirectShapeReferenceOptions.Name.
The new validators:
validates the inputs needed for specifying a plane or curve explicit reference in the DirectShape.
The new class:
represents an identifier for geometry from external sources.
The new members:
provide validation of an identifier and a means to access the identifier as a String.
The new class:
serves as a base class for externally tagged geometry.
The new members:
provides the ExternalGeometryId associated with the geometry.
The new class:
represents non-BRep geometry with an external identifier.
The new class:
represents BRep (Solid) geometry with external identifiers for the BRep itself and any subset of Faces or Edges.
The new class:
Provides a mechanism to associate external identifiers with geometry created by a BRepBuilder.
The new members:
provide an ability to associate “tags” with Faces and Edges created by BRepBuilder.
A new member:
accepting a BRepBuilderPersistentIds has been added which returns an ExternallyTaggedBRep.
The new class:
provides validators
to help determine validity of a GeometryObject for use with the new externally tagged geometry.
The new members:
provide a means to add, remove, update, or retrieve an ExternallyTaggedGeometryObject to/from a DirectShape or DirectShapeType.
The new member:
provides the ability to set a custom Family name for a DirectShapeType.
The new validator:
provides the ability to check if a DirectShapeType supports a custom Family name. Certain categories do not support custom Family names.
Four new methods allow access to identifying forge IDs for Cloud Models:
These methods all return strings, which will be empty for a document which is not a cloud model.
The new property:
allows your application to ignore a schema conflict error on open. The default is false. Setting this to true will ignore the exception of schema conflict while opening the model. Data in the existing schema with the conflicting ID will be erased from the model.
The new property:
controls the two-dimensional label offset from left bottom corner of the viewport (as established with Rotation set to None) to the left end of the viewport label line.
The new property:
controls the length of the viewport label line in sheet space.
The new method:
returns the ID of a view which this callout references, or InvalidElementId if there is not parent.
The new property:
identifies if the view is a callout view.
Several new methods in View3D control grid visibility in 3D Views:
The new class:
allows the creation of temporary graphics in the canvas and can be used to create in-canvas controls.
It has the following members:
The new class:
stores a reference to the image used in the temporary graphics. It has the following properties:
The new methods:
return the id of the Level which is closest to the specified elevation. The level can be at, above or below the target elevation. If there is more than one Level at the same distance from the elevation, the Level with the lowest id will be returned.
The new class:
allows access to the custom value for used in instances of the Properties Palette, Tags and Schedules when multiple elements are referenced and the value of the parameter is different.
The new members:
provide access to the settings in the document, the option for the custom value, and read-only access to the value that will be used (either the custom value or the default).
Several new properties allow access to positioning for various parts of a dimension:
The new properties:
allow access to the corresponding values in the dimension type.
The new methods:
allow access to BuiltInCategories.
The new method:
resets the shared coordinates for the host model. It provides the same functionality as the UI Command "Reset Shared Coordinates".
After resetting coordinates, the following changes will take place:
Note: There will be no changes to linked models.
The new property:
will get or set the clipped state of the survey point BasePoint based on the active ProjectLocation of its Document. For the project base point, the get method will always return false, and the set method will throw an exception.
Revision sequences and API additions
The new class:
defines the sequences by which numbers are assigned to Revisions. Revision numbering is either numeric or alphanumeric. Revision numbering is assigned to Revisions to control the numbering scheme of that Revision. Alphanumeric from the API corresponds to the UI concept of "Custom".
The new members:
provide the ability to create, read and modify the settings related to Revision numbering sequences.
The new methods:
provide access to the id of the revision numbering sequence which controls this revision's numbering:
The new methods:
provide access to the setting controlling the minimum number of digits for a revision number.
The new methods:
validate the order of phases on a given element with respect to the input phase id, ensuring that an object is not assigned a phase where it is demolished before it was created.
The new property:
checks if each edge in the mesh belongs to at least two faces.
The new method:
provides a direct entry point to get access to an object from the ReCap SDK (ReCapWrapper.RCProject) from Revit. This object represents the point cloud from the RC file path stored in PointCloudType. The ReCap assembly ReCapWrapper.dll will need to be included into code using this method.
The coordinate system in RCProject is defined by the Point Cloud. Please refer to ReCap SDK documentation for RCProject.getCoordinateSystem(). If you need points converted to the modeling coordinate system in Revit, you can obtain the transformation matrix from PointCloudInstance.GetTransform().
The existing class:
has several new properties which allow customization of the multiple value indication per field:
The new Enum:
defines how the schedule field's multiple value indication is displayed (using the project setting, a custom text or a predefined text "
The new methods:
import or link a 3DM file into the document.
The new methods:
allow an application to move an individual bar, and to read and reset the transform of the individual bar in a Rebar Set.
The new function:
allows you to designate a particular bar at a given index to be included or not.
The existing properties:
continue to function as before, and setting these to true are equivalent to removing the bar at the first or last position index.
The existing function:
now supports returning false for any bar position index and not just the first or last bar.
The new methods:
provide access to move, include or remove individual bars only for RebarInSystem elements that are owned by PathReinforcement. (This is not supported for RebarInSystem owned by AreaReinforcement).
The new methods:
provide access to the layers of Area Reinforcement elements, and to manipulate (move and remove) the individual lines exposed through those layers.
The new methods:
convert all of the RebarInSystem elements owned by the input element into equivalent Rebar elements.
The new methods:
return the centerline curves for a given bar, where the geometry of the curves are in the actual transformed position. The BarPositionTransform (representing the relative position of any individual bar in the set – a translation along the distribution path) and MovedBarTransform (representing the movement of the bar relative to its default position along the distribution path) will be applied to the returned curves.
The new properties:
provides read and write access to the corresponding properties of freeform rebar elements.
The new method:
changes the rebar shape of a freeform rebar that is currently using the RebarWorkInstructions.Straight option to the provided rebar shape.
Several new properties have been added for Building and Space Types:
The new property:
gets or sets the offset distance from this zone to the associated level.
The new properties:
provide access to the heating temperature, cooling temperature, humidification and dehumidifcation set point values. Temperature set points are in Kelvin, while humidity set points are percentages ranging from 0 to 1.
The new property:
accesses the report style used in a particular analysis report view.
The new class:
represents the settings of the mechanical hidden line display (e.g. ducts and pipes). It can be obtained from the static method:
It offers the following properties:
The new property:
indicates if a panel schedule will display shading for Load cells automatically.
The new method to the DesignToFabricationConverter class:
The method will set a map used when the design to fabrication tool is running. The map relationships will be used to replace any family instance that is based upon the family symbols found in the map with the corresponding fabrication part for the fabrication part type set in the mapping.
The options used to produce an energy model or export to gbXML have been unified.
The new enumeration value:
indicates that the energy analysis model should be based on volumes from rooms or spaces defined in the building model.
The new enumeration values:
allow specification of the energy model production based on the given analysis type.