The Building Coder: Revit 2021.1 SDK and What's New

Two weeks ago, we mentioned the Revit 2021.1 update release.

Now, the corresponding updated SDK (Software Developer's Kit) is also available.

Here are some notes on that, together with an online copy of the information from its What's New section:

The Revit 2021.1 SDK
What's New in Previous Versions
Deprecated versus obsolete
API changes
API additions
Random Selection of Issues Resolved

The Revit 2021.1 SDK

Please note that the updated SDK (Software Developer's Kit) for the Revit 2021.1 update release is now available for download from the Revit developer centre.

REVIT_2021_1_SDK.msi (378,425,344 bytes)

The information below is based on the contents of the Revit Platform API Changes and Additions.docx document included with the Revit 2021.1 SDK. It is also provided in the section on What's New in the Revit 2021.1 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.

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:

The Revit API help file RevitAPI.chm
The Visual Studio solution containing all the SDK samples, Samples\SDKSamples.sln

You will need both of these regularly 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 2021 online help.

What's New in Previous Versions

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

Deprecated versus Obsolete

Before we get deeper into the API changes and additions, a short clarification on the terminology used.

Question: What does the below statement “deprecation/replacement” mean?

We should keep the compatibility for API, right??

Is this just an update to the SDK/documentation?

Answer: Deprecated means 'it now has less value'.

Wikipedia explains Deprecation like this:

In several fields, deprecation is the discouragement of use of some terminology, feature, design, or practice, typically because it has been superseded or is no longer considered efficient or safe, without completely removing it or prohibiting its use.

It can also imply that a feature, design, or practice will be removed or discontinued entirely in the future.

It is not gone, not worthless.

Using it may produce a warning message during compilation, but it will still work.

Response: But note says 'replaced'. If so, the same code won’t work. Then, it’s a breaking change.

Answer: It does not say 'replaced', but 'replacement'.

There is a subtle and significant difference between these two terms.

The former 'replaced' means that is has been replaced and is hence no longer available.

In that case, the method would not be marked as deprecated, but as obsolete.

The latter, 'replacement', means that a replacement is available in case you wish to stop using the deprecated method, but nobody forces you to do so.

'Deprecated' and 'replaced' has always been the terminology used by the Revit API team to mean, 'We have deprecated some functions. Here are the new ones we would like you to use as replacements. The deprecated functions will be removed in the next release.'

With that potential misunderstanding out of the way, here is an overview of the major additions to the Revit 2021.1 API, split into separate sections on API changes and API additions:

API changes

ConnectorType API change

The following function has been deprecated and replaced:

ConnectorType.MasterSurface() → ConnectorType.MainSurface()

Export API change

The following property has been deprecated and replaced:

DGNExportOptions.MasterUnits → DGNExportOptions.WorkingUnits

Save As API change

The following properties have been deprecated and replaced:

DocumentSavingAsEventArgs.IsSavingAsMasterFile → DocumentSavingAsEventArgs.IsSavingAsCentralFile
DocumentSavedAsEventArgs.IsSavingAsMasterFile → DocumentSavedAsEventArgs.IsSavingAsCentralFile

API additions

Civil Alignments API

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:

Addins\CivilAlignments\Autodesk.CivilAlignments.DBApplication.dll

The new class:

Autodesk.Revit.DB.Infrastructure.Alignment

represents an alignment and can be used to find alignments in a document, and to query a particular alignment's properties and to analyse alignment geometry. This object is not an Element, but the underlying Element can be obtained from this object if needed.

The new class:

Autodesk.Revit.DB.Infrastructure.AlignmentStationLabel

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:

Autodesk.Revit.DB.Infrastructure.AlignmentStationLabelOptions
Autodesk.Revit.DB.Infrastructure.AlignmentStationLabelSetOptions

provide options for creating a single alignment label or for creating a set of alignment labels.

Dimension API additions

Several new properties allow access to positioning for various parts of a dimension:

Dimension.TextPosition
Dimension.LeaderEndPosition
Dimension.HasLeader
SpotDimension.LeaderElbowPosition
SpotDimension.LeaderHasElbow

Shared Coordinates API additions

Reset Shared Coordinates

The new method:

Document.ResetSharedCoordinates()

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:

GIS coordinate system will be erased
Shared coordinates relationships with other linked models will be eliminated.
The Survey Point will be moved back to the startup location, where it coincides with the Internal Origin.
The angle between Project North and True North will be reset to 0.

Note: There will be no changes to linked models.

Clipped state of BasePoint

The new property:

bool BasePoint.Clipped

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.

MEP API Additions

Building and Space Type additions

Several new properties have been added for Building and Space Types:

HVACLoadType.HeatingSetPoint – The heating temperature set point in unit Kelvin (K).
HVACLoadType.CoolingSetPoint – The cooling temperature set point in unit Kelvin (K).
HVACLoadType.HumidificationSetPoint – The humidification set point as a number between 0 and 1.
HVACLoadType.DehumidificationSetPoint – The dehumidification set point as a number between 0 and 1.

Zone additions

The new property:

GenericZone.LevelOffset

gets or sets the offset distance from this zone to the associated level.

Random Selection of Issues Resolved

The Revit 2021.1 update release resolves a number of reported issues.

This is mainly a note to self on the following microscopic and totally random selection of a handful of development tickets that I encountered myself:

Obfuscation problem – REVIT-160709 RVTPR-00662: AddinManager Error for Obfuscated Add-ins
Cyrillic characters in lookup tables – REVIT-153006 Encoding issue reading data from size lookup table with Cyrillic characters -- 15738224
Extensible storage schema with UT_Custom – REVIT-161725 R2021 Schema with UT_Custom causes internal error
Documentation errors and an invalid error reporting email address in the SDK itself – REVIT-163108 incorrect email and year in Revit API docs -- 16587872

The Building Coder

Jeremy Tammik blogging on the Revit API

August 04, 2020

Revit 2021.1 SDK and What's New