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:
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:
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:
RevitAPI.chmSamples\SDKSamples.slnYou 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.
Here are the steps I performed so far setting up the Revit 2020 SDK and samples:
Here are links to previous discussions of What's New in the Revit API:
Detailed Table of Contents:
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.
CefSharpSettings.LegacyJavascriptBindingEnabled = true
The following member has been deprecated and replaced:
The following member has been deprecated:
The subpart functionality was previously removed, so there is no replacement method.
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.
With changes made to support PDF import and extensions to the image API, the following members and classes have been deprecated and replaced:
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:
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.
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.
The new class
represents an image placed in a view. It includes:
Snapping capability can be enabled only for PDF-based instances.
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.
The new function:
determines if Revit is currently in journal playback mode or not.
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.
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.
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.
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.
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:
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).
The new method:
returns the string name of the given BuiltInCategory in the current Revit language.
The new method:
returns the localized string name representing the built-in parameter in the input language.
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).
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.
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.
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".
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.
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.
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.
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.
The new method:
sets the Geo coordinate system for the current document.
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.
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.
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.
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.
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.
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.
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:
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.
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".
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:
The new method:
checks if the reference provided can be used in creating Rebar constraints.
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.
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.
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.
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.
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.