What's New in the Revit 2020 API

The Revit 2020 API includes exciting enhancements for add-in developers, including numerous developer wishes and requests that have now been explicitly addressed:

Short overview – abbreviated table of contents:

Information Sources

The highlights were pointed out in the DevDays Online Revit API news video recording.

The information below is based on the contents of the Revit Platform API Changes and Additions.docx document included with the Revit 2020 SDK, the software developers kit available from the Revit installation package and the Revit Developer Centre.

It is also provided in the section on What's New in the Revit 2020 API help file RevitAPI.chm included with the SDK:

Revit 2020 API help on What's New

For convenient, easy and effective web searching, this blog post provides an online version of that information, both in pure HTML (below) and as a PDF document:

The What's New section always provides very 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:

You will need both of these constantly 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 2020 Help.

Installation and Migration From Previous Versions

Here are the steps I performed so far setting up the Revit 2020 SDK and samples:

What's New in Previous Versions

Here are links to previous discussions of What's New in the Revit API:

Detailed TOC of Major Changes and Renovations

Detailed Table of Contents:

API Changes

1.1. Revit automatically initializes CEFsharp

Revit and Autodesk add-ins use the CEFsharp library internally for several features. Some third-party add-ins do so as well. Occasionally, when different versions of the library are used, it leads to instability issues for Revit. In order to avoid version conflicts, we are clarifying what CEFsharp version is being used, and loading it prior to all add-in initialization.

1.2. MEP Fabrication API deprecation

The following member has been deprecated and replaced:

1.3. Structural API deprecation

The following member has been deprecated:

The subpart functionality was previously removed, so there is no replacement method.

1.4. Export API changes

The following member has been deprecated and replaced:

See the API additions section for more details on the new 2D view support for the custom exporter.

1.5. Image API changes

With changes made to support PDF import and extensions to the image API, the following members and classes have been deprecated and replaced:

1.6. Obsolete API removal

The following API members and classes which had previously been marked Obsolete have been removed in this release. Consult the API documentation from prior releases for information on the replacements to use:

1.6.1. Classes

1.6.2. Methods

1.6.3. Properties

API Additions

2.1. Attached detail group API additions

The Group and GroupType API now includes API related to attached detail groups.

The new methods:

control visibility for an element group's attached detail groups as seen in a given view.

The new methods:

return the attached detail groups available for this group or group type.

The new method:

checks if the orientation of the input attached detail group matches the input view's orientation. Note that detail groups in perpendicular elevation views (for example, North and East views) are considered compatible. When showing these detail groups, an error (FailureMessage) based on id can be generated if the orientation of the annotations do not match the orientation of the target view (for example, the failure definition DimensionPerpendicularToView). To prevent displaying detail groups in the wrong view, you can check the OwnerViewId of a detail group to make sure it matches the view in which you are trying to display it.

The new properties:

provide information about whether a group is attached and if so, to what group it is associated.

2.2. PDF and Image API additions

2.2.1. ImageType API

The new members:

add support to loading of specific pages from PDFs as images, loading of images from external resource locations other than paths, and storage of paths as relative or absolute. The API has also been revamped to allow loading of an ImageType in one operation, and placement in a view in a separate operation.

Some of these members reference the new class

that contains the options that are used when creating or reloading an image, including:

Resolution is measured in dpi and relates the number of pixels in raster images to their size.

2.2.2. ImageInstance API

The new class

represents an image placed in a view. It includes:

Snapping capability can be enabled only for PDF-based instances.

2.3. ElementLogicalFilter API additions

2.3.1. Setting filters

The new function:

allows setting ElementFilters that are combined by the given ElementLogicalFilter. This allows an easier method to modify the filter criteria stored in a View filter.

2.4. Application API additions

2.4.1. Journal playback

The new function:

determines if Revit is currently in journal playback mode or not.

2.5. UI API additions

2.5.1. Add Animated Progress Bar to a TaskDialog

The new property:

allows the TaskDialog to include a progress bar that has an indeterminate start and stop. The animation continues until the TaskDialog is closed.

2.5.2. Specify minimum width and height for a DockablePane

Minimum width and height can now be set for a DockablePane:

These are specified as part of the InitialState for the registered pane. The default for both properties is 200 pixels.

2.6. Document additions

2.6.1. Returning cloud model information for cloud workshared models

The new property:

indicates if the current document is located in cloud.

returns the GUID of the model, if it is stored in the cloud.

The new method:

returns the cloud model path.

2.6.2. Open/Save/Modify cloud models on BIM 360

The new method:

saves the current model as a cloud model in BIM 360. Only non-workshared models can be saved via this method.

The new method:

saves the current cloud model.

The new method:

converts a cloud model into a workshared cloud model. The method Document.CanEnableCloudWorksharing() can be used to check whether this operation is valid on a given model.

Revit's existing model open functions (Application.OpenDocumentFile and UIApplication.OpenAndActivateDocument) will now throw RevitServerUnauthorizedException if the user tries to open a cloud model without the right entitlements.

2.6.3. Identifying if background calculations are underway

The new method:

identifies if there are any background calculations in progress for this document. When a document has background calculations in progress, users cannot perform the following operations:

2.7. Category API additions

2.7.1. Category visibility

The new property:

returns true if the category should be visible to the user in lists of categories in the Revit user interface (dialogs such as Visibility Graphics or View Filters).

2.7.2. Get string names of categories

The new method:

returns the string name of the given BuiltInCategory in the current Revit language.

2.8. Parameter API additions

2.8.1. Getting localized parameter names

The new method:

returns the localized string name representing the built-in parameter in the input language.

2.8.2. Hiding empty parameters

The new property

Indicates if the shared parameter should be hidden from the property palette and Element.GetOrderedParameters() when it has no value.

Similar functionality has been added to other classes:

The new method:

can reset the value of a shared parameter which has the HideWhenNoValue flag set back to a cleared state. (This method is not applicable to clear the value of any other parameter type).

2.8.3. Filtering by presence or absence of parameter value

The new filter classes:

define filter rules evaluating whether or not a parameter has a value for a specific element.

Use the static methods:

to create an instance of these rules for use in a parameter filter.

In schedules, use the new enumerated values:

along with the method:

to filter based on the presence or absence of a value assigned to that parameter.

2.9. Geometry API additions

2.9.1. CurveLoop API

The new property:

returns the number of curves in the curve loop.

The new method:

creates a new curve loop that is an offset of the existing curve loop. This method differs from the previously exposed API in that it takes as input a double array of offset distances instead of one double offset distance. The size of this array must match the size of the curve loop. The curve at position i will be offset with the double at position i in the array.

2.10. View API additions

2.10.1. View Template API additions

The new methods:

allow you to turn an existing view into a view template. The created view template has an automatically generated unique name.

The Revit API, for a few releases, has featured a fairly fully-featured capability to set up and modify view templates and their properties. These capabilities are now demonstrated in the new sample "ViewTemplateCreation".

2.10.2. View Filter API additions

Validation restrictions for the ElementFilter stored by a ParameterFilterElement (the class that represents a View Filter) has been relaxed to enable more flexible creation of OR filters where criteria can reference parameters only associated to specific categories. Currently the ElementFilter must be either an ElementParameterFilter or an ElementLogicalFilter representing a Boolean combination of ElementParameterFilters. In addition, we check that each ElementParameterFilter satisfies the following conditions:

Note that cases in the second and third bullet are currently allowed only if the parent node of ElementParameterFilter is LogicalOrFilter.

In addition to the change in validation, the new method:

retrieves a list of the parameters associated with all rules in the filter that are combined (using logical AND) with a FilterCategoryRule corresponding to single categoryId.

2.11. Schedule API additions

The new property:

indicates if the schedule grid lines will be visible on a sheet.

The new property:

allows the user to set the zoom level of a schedule in a tabular view. This setting will not change the size of text, rows, or columns in a sheet view. Additionally, the setting is temporary and only applies to the current session.

2.12. Site API additions

2.12.1. TopographySurface additions

The new method:

creates a topography surface from a given list of triangulation facets.

The new method:

checks whether the given set of triangulation data is valid.

2.12.2. TopographyLinkType additions

The new class:

represents a site file brought into the current Revit model as a link.

The new method:

reloads the TopographyLinkType from its current location.

2.13. Shared Coordinates API additions

2.13.1. SiteLocation addition

The new method:

sets the Geo coordinate system for the current document.

2.13.2. BasePoint additions

The new read-only property:

gets the XYZ value corresponding to the base point's position in Revit's internal coordinates.

The new read-only property:

gets the XYZ value corresponding to the base point's position in the transformed (shared) coordinates.

2.14. Part API additions

2.14.1. Part creation from DirectShapes

Parts can now be created from DirectShape instances, either in the same host document or in a link. Since various reasons might prevent parts from being created from an element, the new methods

indicate whether it is possible to create parts from an instance of one of those classes.

2.14.2. Returning the entities that create a divided Part

The new methods:

identify and return the curves that were sketched to create the part division and, optionally, also outputs also the sketch plane for those curve(s).

The new method:

identifies and returns the elements ( ReferencePlane, Level or Grid ) that were used to create the division.

2.15. Railing API additions

2.15.1. BalusterInfo reference name

The new functions:

allow access to the name string to be used as a reference to either the Host or Top Rail in the current Revit language.

2.16. Export API additions

2.16.1. CustomExporter now supports some 2D views

The class CustomExporter can now export 2D views. The only 2D view types supported at this time are plans, sections and elevations. The new method:

accepts either a 3D or 2D view.

The method:

can now accept either 3D or 2D views, with the limitation that views in the collection must be either all 3D or all 2D.

For both Export() calls, the exporter context must correspond to the views' type; use IModelExportContext or IPhotoRenderContext for 3D views and IExportContext2D for 2D views.

Several new properties expand the options for the CustomExporter to support 2D objects:

The new interface:

should be used for exporting 2D views. It has the following methods in addition to the method inherited from IExportContext:

The new classes:

contain data for various 2D exported objects.

Some notes on 2D export in DisplayStyle.Wireframe:

And in DisplayStyle.HDR:

For an example of the use of the API for custom export of 2D views, see the new sample CustomExporter/Custom2DExporter.

2.16.2. New Navisworks export options

Three new options have been added to the class NavisworksExportOptions:

Note that you will need to get an updated Navisworks Exporter to successfully use these options.

2.17. Multi-Reference Annotation additions

2.17.1. Additional References

MultiReferenceAnnotations can now pick additional references from the model. The following new methods support this:

Note that the additional references to dimension cannot come from the same category as the MultiReferenceAnnotationType's reference category. The following function can be used to verify this:

2.17.2. 3D view placement restrictions

The new method:

is used by MultiReferenceAnnotation.Create() to verify that the dimension is valid for the view. LinearFixed dimensions cannot be created in 3D views. Linear dimensions can only be created in 3D views if the view direction is perpendicular to the current work plane normal.

2.18. Material API additions

2.18.1. Glazing schema API

To assist in creating code accessing and manipulating the properties of a given schema, predefined properties have been introduced to allow a compile-time reference to a property name without requiring you to transcribe it as a string in your code. New predefined properties are available in the new class:

whose contents represent the appearance asset of type "advanced glazing".

2.19. Analysis API additions

2.19.1. Path of Travel API

The new class:

represents the element that calculates the shortest navigable path between two points in a plan view.

Some of the new members of this class include:

The new class:

represents a new settings element which contains project-wide settings for route calculations in plan views. Currently, these settings are only used by the Autodesk.Revit.DB.Analysis.PathOfTravel element, but in the future they can be used by any other functionalities which do route calculations.

Some of the new members include:

2.20. Structural API additions

2.20.1. RebarConstraint additions

The new method:

checks if the reference provided can be used in creating Rebar constraints.

2.20.2. Updating free-form rebar based on shared parameters

Free-form rebar can now regenerate based on one or more shared parameters. Several methods have been added to support this behaviour:

Note that the shared parameter(s) must already be bound to the Rebar category before setting up the dependency.

2.20.3. StructuralConnectionHandler additions

The new property:

allows or disallows overriding the parameters for a connection type.

When set to true, a set of instance parameters is created for this connection by copying the type parameter set. The user can change these instance parameters in order to make this connection different from the others of the same type. Any further modification on type parameters will not affect this instance (until the "override" is turned back off).

When set to false, the connection instance parameters are discarded and the type parameters are used again.

2.21. MEP API additions

2.21.1. FabricationPart additions

The new method:

returns any insulation or liner geometry for a fabrication part. If there is no insulation or liner applied the return value will be null.

2.21.2. FabricationNetworkChangeService

The new method:

changes the service of a selection of element identifiers to the passed in service, group identifiers, and the option to restrict the placement of parts that only exist in the group identifier.

2.21.3. ElectricalSystem API additions

The new properties:

provide access to the circuit connection type of the electrical system, and information about whether or not the feed through lugs of the base panel is already occupied.