1496/2078

What's New in the Revit 2017.1 API

Originally Published in

I recently mentioned the updated Revit 2017.1 SDK and its API enhancements.

They are documented in full detail in the section Major additions to the 2017.1 Revit API of the Revit 2017.1 API help file RevitAPI.chm included with the SDK, which is also provided there in the separate stand-alone document Revit Platform API Changes and Additions.docx.

For convenient, easy and effective web searching, here is the online version of that information.

I am only including that specific section here.

The rest of the document contents are identical with the original information about What’s New in the Revit 2017 API provided with the initial release of the Revit 2017 API.

I made one small enhancement to that existing blog post as well, though:

Small Addendum to What’s New in the Revit 2017 API

I just made a small modification ↗, adding the following note to What’s New in the Revit 2017 API:

  • TextNote creation behaviour change – The various TextNote.Create methods now need to be followed by a call to Document.Regenerate before the newly created TextNote can be queried for data.

It was missing in the version I originally published. I don’t know when it slunk in there without me noticing.

More About What’s New

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 ports of call.

Here are links to the preceding ‘What’s New in the API’ discussions:

For more detailed information, please refer to the complete API documentation and samples collection in the SDK and the online Revit API Developers Guide ↗ provided as part of the Revit 2017 Help ↗.

Major Additions to the 2017.1 Revit API

API enabled in perspective views

Element modifications and contextual commands

Modification of many different object types is now allowed in perspective views. Most commands allowed in 3D orthographic views are now also allowed in perspective views. This includes contextual commands. Annotations are an exception and cannot be created in perspective views.

External commands and applications

External API commands and applications are now enabled by default in perspective views. The following behaviour applies:

  • Any external command that was automatically disabled by Revit when a perspective view is active will now be active. No code changes are necessary to make this happen.
  • Any external command that was explicitly disabled in perspective views will remain disabled. For example, if your command has an accessibility function limiting it to use in certain view types, the command will not be accessible in perspective views unless that function accepts ViewType.ThreeD as a view type that is allowed.
  • Macros, the Macro Manager tools, Dynamo scripts and the Dynamo editor are also newly enabled when a perspective view is active.

Geometry API additions

BRepBuilder API additions

Two new methods have been added to handle problematic faces:

  • BRepBuilder.AllowRemovalOfProblematicFaces() – Allows BRepBuilder to remove problematic faces (e.g., due to inaccurate edge geometry).
  • BRepBuilder.RemovedSomeFaces() – Returns true if BRepBuilder removed some problematic faces from the output geometry. One new method has been added to relax validation criteria on the input geometry:
  • BRepBuilder.SetAllowShortEdges() – Makes the BRepBuilder allow edges that it would normally disallow as being too short for Revit geometry.

BRepBuilderSurfaceGeometry API additions

A new overload of the method:

  • static BRepBuilderSurfaceGeometry.CreateNURBSSurface()

constructs a BRepBuilderSurfaceGeometry based on NURBS surface data, where the weights are not supplied.

Ellipse API additions

The new method:

  • static Ellipse.CreateCurve()

creates a new geometric ellipse or elliptical arc object.

RevolvedSurface API additions

The new method:

  • RevolvedSurface.GetProfileCurveInWorldCoordinates()

returns a copy of the profile curve expressed in the world coordinate system.

Dimension API additions

DimensionEqualityLabelFormating API

The new class:

  • DimensionEqualityLabelFormatting

allows users to set dimension equality formulas for continuous linear or angular dimensions.

New methods and properties include:

  • DimensionEqualityLabelFormatting.LeadingSpaces
  • DimensionEqualityLabelFormatting.LabelType
  • DimensionEqualityLabelFormatting.Prefix
  • DimensionEqualityLabelFormatting.Suffix
  • DimensionEqualityLabelFormatting.GetFormatOptions()
  • DimensionEqualityLabelFormatting.SetFormatOptions()

The following new methods in DimensionType allow access to equality formulas:

  • DimensionType.GetEqualityFormula()
  • DimensionType.SetEqualityFormula()

UnitsFormatOptions in DimensionType

The new functions:

  • DimensionType.GetUnitsFormatOptions()
  • DimensionType.SetUnitsFormatOptions()

allow users to get or set the FormatOptions for a DimensionType.

OrdinateDimensionSetting

The new class:

  • OrdinateDimensionSetting

allows users to customize ordinate dimensions.

The new enum:

  • OrdinateDimensionLineStyle

allows users to choose continuous or segmented line styles for their dimensions.

The new enums:

  • OrdinateTextOrientation
  • OrdinateTextPosition

allows users to orient text in relation to the dimension lines or witness lines.

The new enum:

  • OrdinateOriginVisibility

allows users to control visibility of their dimensions.

New properties in OrdinateDimensionSetting include:

  • OrdinateDimensionSetting.DimLineLength
  • OrdinateDimensionSetting.DimLineStyle
  • OrdinateDimensionSetting.TextOrientation
  • OrdinateDimensionSetting.TextPosition
  • OrdinateDimensionSetting.OriginVisibility
  • OrdinateDimensionSetting.OriginTickMarkId

The following new methods in DimensionType allow access to the OrdinateDimensionSetting:

  • DimensionType.GetOrdinateDimensionSetting()
  • DimensionType.SetOrdinateDimensionSetting()

FabricationPart detailing API

Split Parts API

The following methods have been added to support splitting fabrication parts:

  • FabricationPart.SplitStraight() – Splits the straight into two at the passed in point.
  • FabricationPart.IsStraightSegment() – Validates if the part is a straight.
  • FabricationPart.CanSplitStraight() – Validates if the straight can be split into two at the passed in point.

Detailed Fabrication additions

Several methods, properties classes and enumerations have been added to allow the user to access detailed fabrication information defined in the fabrication configuration and in use on the fabrication parts.

The following methods allow access fabrication data defined by the currently loaded fabrication configuration. These can be used to query what fabrication data is available for fabrication parts to use:

  • FabricationConfiguration.GetAllDampers() – Lists all damper identifiers.
  • FabricationConfiguration.GetDamperName() – Gets damper name from its identifier.
  • FabricationConfiguration.GetAncillaries() – Lists all ancillary identifiers (by enumerated type).
  • FabricationConfiguration.GetAncillaryName() – Gets ancillary name from its identifier.
  • FabricationConfiguration.GetAllPartStatuses() – Lists all part status identifiers.
  • FabricationConfiguration.GetPartStatusDescription() – Gets part status description from its identifier.
  • FabricationConfiguration.GetAllPartCustomData() – Lists all part custom data identifiers.
  • FabricationConfiguration.GetPartCustomDataName() – Gets part custom data name from its identifier.
  • FabricationConfiguration.GetPartCustomDataType() – Gets part custom data type enumeration from its identifier.

The following methods allow access to Fabrication Part custom data defined per part (for querying and changing values):

  • FabricationPart.HasCustomData() – Queries if a part has a certain optional custom data.
  • FabricationPart.Get/SetPartCustomDataText/Integer/Real() – Gets or sets fabrication part’s custom data.
  • FabricationPart.Add/RemovePartCustomData() – Adds or removes optional custom data on fabrication parts.

Added a new API to override routing exclusions

  • FabricationService.IsGroupExcluded() – Gets whether a service group is excluded from routing.
  • FabricationService.SetServiceGroupExclusions() – Sets the service group exclusions.
  • FabricationService.ResetServiceExclusionOverrides() – Resets the overridden service group and button exclusions back to default.
  • FabricationService.OverrideServiceButtonExclusion() – Overrides the default service button exclusions.
  • FabricationServiceButton.IsExcluded() – Gets if the service button is excluded from routing.

Ancillary usage additions

A method was added to query fabrication part ancillary usage. This method can be used to populate cut lists and procure ancillaries needed to fabricate and install the fabrication part:

  • FabricationPart.GetPartAncillaryUsage() – Gets a list of FabricationAncillaryUsage structures that lists the ancillaries that the fabrication part uses.

The ancillary usage is held in a new class:

  • FabricationAncillaryUsage

It has the following read-only properties:

  • FabricationAncillaryUsage.Type – A new enumerated type FabricationAncillaryType which describes what kind of ancillary it is (e.g., a fixing, airturn vane or support material).
  • FabricationAncillaryUsage.UsageType – A new enumerated type FabricationAncillaryUsageType describing the usage of the ancillary (e.g., in a support, connector or airturn).
  • FabricationAncillaryUsage.AncillaryId – The ancillary database identifier as listed by FabricationConfiguration.GetAncillaries().
  • FabricationAncillaryUsage.AncillaryWidthOrDiameter – The width / diameter of the ancillary (e.g., rod thickness).
  • FabricationAncillaryUsage.AncillaryDepth – The depth/height of the ancillary.
  • FabricationAncillaryUsage.Quantity – The quantity of the ancillary in this part.
  • FabricationAncillaryUsage.Length – The total length of the ancillary, if applicable, in this part.
  • FabricationAncillaryUsage.ProductCode – The product code identifier used to procure the ancillary.

Part status

Two properties were added to fabrication part to allow the user to query and set the part fabrication status field:

  • FabricationPart.PartStatus – Query and change the part fabrication status field current value. Setting the value will track when it was changed.
  • FabricationPart.PartGuid – Query the part’s fabrication globally unique identifier, as used in applications such as Tracker.

Hanger rod additions

To give the user better control over hanger rod thicknesses a new property was added to fabrication part to get and set the ancillary kit used:

  • FabricationPart.HangerRodKit – get/set support rod kit override.

Import API additions

ShapeImporter additions

Two new methods:

  • ShapeImporter.GetDefaultLengthUnit()
  • ShapeImporter.SetDefaultLengthUnit()

get or set the length unit to be used, if not specified in the input SAT file.

Worksharing events addition

Subscribe to the Autodesk.Revit.DB.Events.WorksharedOperationProgressChanged event to be notified when progress has changed during Collaboration for Revit’s synchronizing with central operation.

This event consists of several phases. Different event arguments are used during each phase.

WorksharedOperationProgressChangedEventArgs

The new class:

  • Autodesk.Revit.DB.Events.WorksharedOperationProgressChangedEventArgs

provides a base class for event arguments for worksharing-based progress events.

DocumentSaveToLocalProgessChangedEventArgs

The new class:

  • Autodesk.Revit.DB.Events.DocumentSaveToLocalProgessChangedEventArgs provides information during the save to local phase of the DocumentSynchronizingWithCentralProgessChanged event.

It has the following properties:

  • DocumentSaveToLocalProgessChangedEventArgs.Location – Full path of the central model which is to be synchronized.
  • DocumentSaveToLocalProgessChangedEventArgs.Status – Gets the API event status, which reflects the current operation execution status.
  • DocumentSaveToLocalProgessChangedEventArgs.BeforeSaveToCentral – True if the “save to local” operation is occurring before “save to central”; false if after.
  • DocumentSaveToLocalProgessChangedEventArgs.FinishedStreams – The number of streams finished since the last time this event was raised.
  • DocumentSaveToLocalProgessChangedEventArgs.TotalStreams – The total expected number of streams to save to local.
  • DocumentSaveToLocalProgessChangedEventArgs.SaveToLocalFinished – Indicates if the current “save to local” operation has finished.

DocumentReloadLatestProgressChangedEventArgs

The new class:

  • Autodesk.Revit.DB.Events.DocumentReloadLatestProgessChangedEventArgs provides information during the reload latest phase of the DocumentSynchronizingWithCentralProgessChanged event.

It has the following properties:

  • DocumentReloadLatestProgessChangedEventArgs.Location – The full path of the central model which is to be synchronized.
  • DocumentReloadLatestProgessChangedEventArgs.Status – Gets API event status, reflecting the current operation execution status.
  • DocumentReloadLatestProgessChangedEventArgs.RetryTimes – The number of times Revit has tried to Reload Latest. Its value is ‘0’ at the first time.
  • DocumentReloadLatestProgessChangedEventArgs.DownloadSpeed – Download speed(bytes/second) in this event.
  • DocumentReloadLatestProgessChangedEventArgs.FinishedSize – The downloaded data size, in bytes, since the last time this event was raised.
  • DocumentReloadLatestProgessChangedEventArgs.TotalSize – Total expected data size to download, in bytes.
  • DocumentReloadLatestProgessChangedEventArgs.IsMerging – Indicates if Revit is merging downloaded data.
  • DocumentReloadLatestProgessChangedEventArgs.ReloadLatestFinished – Indicates if current ‘reload latest’ progress is finished or not.

DocumentSaveToCentralProgessChangedEventArgs

The new class:

  • Autodesk.Revit.DB.Events.DocumentSaveToCentralProgessChangedEventArgs provides information during the save to central phase of the DocumentSynchronizingWithCentralProgessChanged event.

It has the following properties:

  • DocumentSaveToCentralProgessChangedEventArgs.Location – Full path of the central model which is to be synchronized.
  • DocumentSaveToCentralProgessChangedEventArgs.Status – Gets API event status, reflecting the current operation execution status.
  • DocumentSaveToCentralProgessChangedEventArgs.RetryTimes – The number of times Revit has tried to Save to Central.” Its value is ‘0’ at the first time.
  • DocumentSaveToCentralProgessChangedEventArgs.UploadSpeed – Upload speed(bytes/second) of saving to central.
  • DocumentSaveToCentralProgessChangedEventArgs.FinishedSize – The uploaded data size, in bytes, since the last time this event was raised.
  • DocumentSaveToCentralProgessChangedEventArgs.TotalSize – Total expected uploaded data size to save to central, in bytes.
  • DocumentSaveToCentralProgessChangedEventArgs.SaveToCentralFinished – Indicates if current ‘save to central’ is finished or not.
  • DocumentSaveToCentralProgessChangedEventArgs.FailureDueToConflicts – Indicates the ‘save to central’ failure is caused by submission, that is because another user finished saving to central first.

The rest of the document continues with the Revit 2017 API changes.