What's New in the Revit 2019.1 API

As I mentioned last week, the Revit 2019.1 update has been released.

It is equipped with an updated API that includes several exciting enhancements for add-in developers.

Many relate directly to explicit developer wishes and requests:

Information Sources

The information below is based on the contents of the Revit Platform API Changes and Additions.docx document included with the Revit 2019.1 SDK – software developers kit – available from the Revit Developer Centre (not posted yet, but coming soon).

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

Revit 2019.1 API help on What's New

For convenient, easy and effective web searching, this blog post provides an online version of that information.

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 2019 Help.

What's New in Previous Versions

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

What's New in the Revit 2019.1 API – Detailed ToC

Table of Contents:

API Changes

.NET 4.7

Revit's API assemblies are built using .NET 4.7. At a minimum, add-ons will need to target .NET 4.7 for Revit 2019.

View Filters support OR operators and nesting

ParameterFilterElement API changes

View filters now support multiple nested levels of combinations of criteria joined with either "AND" or "OR". In the API, an ElementFilter hierarchy is replacing the use of lists of FilterRules previously obtained from ParameterFilterElement. Several methods are deprecated and replaced. Note that the deprecated methods will still function as before when accessing the criteria contained within a filter joined by a single AND, but cannot function as expected when accessing more complicated sets of criteria. The new method:

can be used to check if a ParameterFilterElement uses a conjunction of filter rules (without any logical OR operations), as was always the case before Revit release 2019. This function is also deprecated, as are all functions related to the use of FilterRules in ParameterFilterElement.

The new function:

can be used to check if an ElementFilter is suitable to be used for a view filter (it consists only of logical filters joining ElementParameterFilters in combination).

ElementLogicalFilter API addition

The new function:

returns the set of ElementFilters that are combined by the given ElementLogicalFilter. This is useful to read the contents of an ElementFilter obtained from a ParameterFilterElement.

View.ViewName deprecated

The property

has been deprecated. It was a duplication of Element.Name and this property should be used in its place.

UI API changes

Main window handle access

Two new properties allow access to the handle of the Revit main window:

This handle should be used when displaying modal dialogs and message windows to ensure that they are properly parented. Use these properties instead of System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle, which is no longer a reliable method for retrieving the main window handle starting with Revit 2019.

Changes to PostableCommand enumeration

Some commands were renamed or removed as a result of changes to Revit's windowing system:

Existing APIs now support open from cloud paths (Collaboration for Revit)

Document Open APIs support cloud paths

The existing methods:

and the new methods:

now offer the ability to open a C4R model from its location on the cloud. Obtain a relevant ModelPath representing the document from:

by inputting the project Guid and model Guid (which could be obtained from various Forge APIs).

Callback for conflict cases when opening from a cloud path

The callback method:

can be passed to the document open methods to gain to handle conflict cases. The method is passed an OpenConflictScenario value identifying the reason for the conflict ( Rollback, Relinquished or OutOfDate) and should return an OpenConflictResult with the desired response (keep local changes, discard local changes and open the latest version or cancel). The new class:

provides a default way to handle conflicts: it always discards the local change and gets the latest version from the cloud.

BasicFileInfo changes

The structure of BasicFileInfo storage has been changed. As a result, calling:

from a version of Revit prior to Revit 2019 will result in an exception if it is called on a Revit 2019 or later file. The class and method documentation has been clarified to reflect this possibility that may occur again in the future.

The following BasicFileInfo property was deprecated and replaced:

Calling BasicFileInfo.Extract() from Revit 2019 on any Revit file version should work as expected. Both SavedInVersion and Format should be populated for old and new files.

Asset-related API members deprecated

As a part of the introduction of new Appearance Asset editing API's, some members were deprecated and replaced:

Double Pattern Support

Material API support for double patterns

With the introduction of double patterns in materials Revit now distinguishes between a background and a foreground pattern. The existing properties for the patterns and colors of the surface and cut faces have been deprecated. New properties have been introduced for the background and foreground patterns and colors for both surface and cut faces. (The deprecated properties will return the same values as the new foreground versions.)

Support for overriding double patterns

Several methods and properties in the OverrideGraphicSettings class have been replaced with versions specific to the foreground or background pattern:

Support for double patterns for FilledRegion

Three properties in the FilledRegionType class have been deprecated and replaced to support double patterns:

Document.Title consistency

In prior releases, the property:

honoured the Windows user setting requiring dlsplay of file extensions. The property has been changed to consistently return a title with no extension.

View printing & exporting – activation events behavioral change

Because of an improvement to Revit processing, views will no longer be activated prior to being printed or exported. This means that the ViewActivating and ViewActivated events are no longer triggered as each view is printed or exported from a set.

Structural API change

The following method has been deprecated:

Rebar API changes

The method:

now throws an exception if the rebar is a free-form which has multiple shapes (i.e., its WorkshopInstructions type is Bent).

MEP API changes

The following members have been deprecated:

ProjectLocation changes

The original version of ProjectLocation.IsProjectLocationNameUnique checked for name uniqueness across the entire document. The replacement version only enforces uniqueness among the ProjectLocations belonging to a given SiteLocation.

Building Site export removed

The following method and class were removed:

corresponding to the removal of this capability from Revit itself.

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:

Classes

Methods

Properties

API Additions

Material API additions

Editing the properties of an Appearance Asset

New Revit API capabilities have been introduced to edit the properties contained in an appearance asset of a material. These properties appear in the Appearance tab of the Materials dialog and govern the appearance of the material in realistic views and rendering.

Editing the properties in an appearance Asset requires establishment of an edit scope. The new class

allows an application to create and maintain an editing session for an appearance asset. The scope provides access to an editable Asset object whose properties may be changed. Once all of the desired changes have been made to the asset's properties, the edit scope should be committed, which causes the changes to be sent back into the document. (This is the only part of the process when a transaction must be opened).

The new class has the following methods:

Editing AssetProperty values

The following properties are now writeable from within an AppearanceAssetEditScope, to support modification of an asset property's stored value:

In addition, the following new methods have been added to support modification of property values:

AssetPropertyList now has new methods to allow changes to the members of the list:

Connected Assets

Connected assets are associated to properties in appearance assets, and represent subordinate objects encapsulating a collection of related properties. One example of a connected asset is the "Unified Bitmap" representing an image and its mapping parameters and values. AssetProperty offers new methods to provide the ability to modify, add or delete the asset connected to a property:

Validation

Inputs to change the value of asset properties are validated against the requirements of the associated schema.

The new methods:

identify if the input value is a valid value that can be set to the given asset property.

The new method:

identifies the the AssetProperty can currently be edited.

Schemas and Property names

Appearance asset properties are aligned with specific schemas. Each schema contains necessary properties which define how the appearance of the material will be generated. There are 14 standard material schemas:

In addition, there are 5 schemas representing "advanced" materials – these may be encountered as a result of import from other Autodesk products:

Finally, there are 10 schemas used for the aspects of the connected assets:

The new method:

identifies if the input name is a valid name for a supported schema.

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. These predefined property names are available in static classes named similar to the schema names, above, e.g. Autodesk.Revit.DB.Visual.Ceramic.

Utilities

The new method:

returns a list of assets available to the session.

The new method:

creates a copy of an appearance asset element and the asset contained by it.

The new operator:

accesses a particular AssetProperty associated to the given asset.

Railing API additions

Non-Continuous Rail Structure

The new property:

provides access to a collection of the information about non-continuous rails that are part of a RailingType. The Autodesk.Revit.DB.Architecture.NonContinuousRailStructure object returns contains a collection of Autodesk.Revit.DB.Architecture.NonContinuousRailInfo objects, each of which represents the properties needed to define a single non-continuous rail.

Baluster Placement

The new property:

provides access to the baluster and post placement information for a given railing type. The Autodesk.Revit.DB.Architecture.BalusterPlacement object returned may contain instances of:

Find Element Dependencies

The new method:

returns a list of ids of elements which are "children" of this element; that is, those elements which will be deleted along with this element. The method optionally takes an ElementFilter which can be used to reduce the output list to the collection of elements matching specific criteria.

Dimension API additions

The dimension API now supports adding linear dimensions to cut geometry which is view-specific.

The new property:

always returns true for dimensions which are not view-specific. It can return false for view-specific dimensions that can lose their references in certain situations. For example, the host element references may not be available when the view containing the dimension is closed. In general, if the host element view-specific geometry is not available, dimensions that reference that geometry will not be able to resolve their references.

The new property:

always returns true for dimensions which are not view-specific. It can return false for view-specific dimensions that are hidden because they are in an invalid state. An example of an invalid state is having misaligned references for generation of an aligned dimension.

Set vertical alignment for text

The new property:

allows you to specify the vertical alignment for a new text note created by TextNote.Create().

BrowserOrganization API additions

The new enumerated value:

corresponds to the type of the browser organization definition for schedules.

The new method:

gets the BrowserOrganization that applies to the Schedules section of the project browser.

Rebar API additions

BarTypeDiameterOptions

The new options class:

allows creation of a new set of diameter values for a RebarBarType. It can be used when copying the diameter information as a bulk of data from one RebarBarType to another.

The diameter options can be set for a RebarBarType with the new method:

which sets all input diameters from the input BarTypeDiameterOptions in the current RebarBarType.

GetDistributionPath()

The new method:

gets the distribution path currently stored in the rebar.

For a free form rebar set the distance between two consecutive bars may be different if it is calculated between different points on bars. The distribution path is an array of curves with the property that based on these curves the set was calculated to respect the layout rule and number of bars or spacing.

RebarUpdateCurvesData

Several new properties have been added to RebarUpdateCurvesData:

RebarShapes

Two new methods in the Rebar class check or get associated RebarShape objects:

Workshop Instructions

Several new properties identify the workshop instructions of a Rebar:

RebarFreeFormAccessor Additions

Several new methods have been added to determine information about the bar at a specific index of the set:

Steel Fabrication API additions

SteelElementProperties – linking between Revit elements and steel fabrication elements

The new class:

is used to attach steel fabrication information to various Revit elements. Elements which can have fabrication information include:

Use the static method:

to obtain the properties if they exist.

The properties contain:

which is the id of the object in fabrication terms, and can be used to determine the Steel Core element corresponding to this Revit element, for use with the Advance Steel API.

You can also look up the id about a Revit element using the static method:

For Revit elements which do not currently have a fabrication link, it can be added using:

If you have a fabrication id, you can look up the corresponding Revit element using:

This may return a reference to an element or a sub-element.

Custom steel connections – API additions

The new method:

creates a custom StructuralConnectionHandler along with its associated StructuralConnectionHandlerType. Input elements should include structural members and steel connection members, and at least one StructuralConnectionHandler representing the generic connection to replace with the new detailed custom connection.

The methods:

provide support for adding or removing steel connection elements in a custom connection.

The new properties:

provide read access to information about the structural connection handler elements.

MEP API additions

MEPCurveType Shape

The new property:

returns the shape of the profile for the MEP curve type.

Mechanical Equipment Set API

Two new classes allow creation and manipulation of a mechanical equipment set, which is a set of interrelated mechanical equipment in a MEP system that may operate in parallel. This release is limited to supporting one or more pump sets that are part of a piping system. The mechanical equipment set settings will be used for the MEP flow and pressure drop calculations.

The Element subclass Autodesk.Revit.DB.Mechanical.MechanicalEquipmentSet represents an instance of a set associated to a MEP system. It includes:

The new members:

The ElementType subclass Autodesk.Revit.DB.Mechanical.MechanicalEquipmentSetType represents a type for a set of mechanical equipment in a MEP system. It includes:

used to create a uniquely named type of mechanical equipment set.

For pump sets, the new method:

gets the set of element ids of pump sets associated with this system.

Hydraulic Separation API

New methods implemented in the PipingSystem class support hydraulic separation. Hydraulically separated systems allow independent flow and pressure analysis for each hydraulic loop. For example, each hydraulic loop has its own critical path. The calculated pressure drop on the primary pump consists of all pressure drop on the primary critical path. Any pressure drop on the secondary loop would only contribute to the calculated pressure drop of the secondary pump.

The new methods:

support creation, deletion, and validation of members of a hydraulically separated system. Separated systems will have their own associated system elements from which you can read and modify the members after creation.

MEP Fabrication API additions

Exporting fabrication job files

The new method:

writes a fabrication job to disk in the MAJ file format. The exported file will contain the fabrication parts included in the input. It takes an options class, FabricationSaveJobOptions, allowing for the possibility of including holes branches meet the main straight.

API for load and unload of one-off fabrication parts from loose item files

The new class:

contains information about one-off items that can be loaded into a fabrication configuration.

The new class:

may contain nested FabricationItemFolders and a list of FabricationItemFiles.

The new members:

allow control over the loading and unloading of item files into the configuration.

The new method:

creates a FabricationPart from an item file.

API for version history of parts

The new class:

gives the information about different versions of fabrication data, including the reason why the data was changed.

The new method:

returns a list of FabricationVersionInfo classes that describe the history of the changes made to the part. The most recent changes are first in the list.

API for part swap out information

The new class:

gives information about a part that was swapped out during reload.

The new members:

identify the parts that had newer versions found during a reload and which Revit attempted to swap out.

Centerline length API

The new property:

returns the length of the fabrication part's centerline.

Analysis Visualization Framework API addition

The new property:

allows for the use of transparency in the display of the coloured surface.

IFC additions

The new functions:

allow for passing in arbitrary options for custom IFC importers. Users can pass in a string to string map specifying extra data they wish to pass for IFC import.

Revit Link Additions

The new function:

allows users to read the Phase Map parameter for the link. The phase map is a correspondence between phases in the host document and phases in the linked document, and is used by room calculations. Note that the link must be loaded to read the phase map.

Export Additions

The new property:

indicates that only the specified view should be exported when creating a DWF export.

Access to add-in data paths

The new properties:

provide access to the data folder and add-in data folder for the current Revit version and current user.

Site API additions

The new property:

identifies whether the points of this TopographySurface can be edited independently. This property is used to check validity for several TopographySurface editing methods.

UI API additions

BeforeExecutedEventArgs Cancellation

The property:

is now permitted to be set to true. This allows the callback to cancel the execution of the impending command. This can be useful if an add-in wishes to selectively allow the command to proceed based on interactions which take place in this callback. The property should also report the cancellation status if it has been cancelled by a different subscriber.