I wanted to publish the 'What's New' section of the Revit 2015 API help file right away after the release of Revit 2015 and was caught up in too many other things. Here it is, at last.
The information provided here is extracted from the document 'Revit Platform API Changes and Additions.docx' provided with the Revit SDK. It is also included in the 'What's New' section in the Revit API help file RevitAPI.chm.
I am putting it online to ensure that the valuable information provided here is picked up by web searches.
For more detailed information on the pointers provided below, please refer to the complete API documentation in the SDK and the online Revit API Developers Guide.
For an overview of the main highlights, please refer to the DevDays Online Recording, including the complete materials from the Revit 2015 DevDays presentations:
To look up the introduction of older features, here are the previous 'What's New in the API' sections:
This document consists of three main sections, on changes affecting existing add-ins, major new functionality, and minor enhancements.
For your and my own convenience, I added a table of contents providing an overview of and navigation to the sub-sections as well:
Revit's API is now built with and requires .NET 4.5 for compilation.
Revit is now built with and installs runtime libraries from VC11 update 4 (Visual Studio 2012). Third party applications which include native components may want to upgrade to the same VC runtime as there is no guarantee that Revit will install any other runtime on client machines.
A small set of units API functions introduced in Revit 2014 have been obsoleted. Their replacements already existed in Revit 2014, and are listed here:
The indexed property Element.Parameter[String] is obsolete. The recommended replacement is:
The collection returned from this property now includes more parameters. Previously, it returned only parameters that Revit showed in the Properties Palette, but now it also includes parameters available in schedules and tags but not shown in the Properties Palette. This can cause behavioral changes for existing applications because some of the newly visible parameters will have duplicate names, but different ids, with other parameters. To get a list of just the parameters available from the Properties Palette, use Element.GetOrderedParameters().
Revit now allows the assignment of two new properties to shared parameters:
The new method:
create a new shared parameter definition using an options class where any or all of the available options may be set (name and type are required, but GUID, user visible, user modifiable, and description are optional). This method replaces all other specific versions of Definitions.Create() which are now obsolete.
Note that for shared parameters IsReadOnly can return false for shared parameters whose UserModifiable property is also false, because the value of those parameters can be modified by the API. If a parameter is governed by a formula, IsReadOnly would return true, even if the flag for UserModifiable was set to true when the shared parameter was created.
The new properties:
provide information about whether the flag is set to the API.
The methods
have been obsoleted. Instead of using these methods after constructing the WorksetConfiguration, use the constructor for WorksetConfiguration accepting one of the following options:
The property
duplicated the property
but was not settable. It has been removed completely in Revit 2015.
Several pre-existing classes:
are now subclasses of Element. You can use limited Element related functionality on these members (for example, get their ids to check them out in a local workshared model, or add ExtensibleStorage to them). FilteredElementCollector will now return these types if they pass the associated filters.
The FamilyBase class has been completely removed as a base class of Family. Family now inherits directly from Element. The members which belonged to FamilyBase have moved to Family:
Code that accesses elements as Family and uses these members should not need to be changed, but must be recompiled due to the removal of the intermediate level.
Code that accesses elements as FamilyBase will need to be updated to use Family instead. In Revit, any FamilyBase element found will actually be a Family element and can be cast accordingly.
The property Family.Symbols has been obsoleted – use
as a replacement.
Access to these properties is now supported only from an owner family obtained from a curtain panel family document.
An exception will result attempting to access these properties from a family which is not the owner family of the document.
Code which previously tried to use these properties from a non-owner family will now need to edit the family in order to access this information.
The new class:
contains settings related to graphics display, such as transparency, silhouette settings, hidden lines, and smooth edges. Access these settings from:
This access replaces direct properties of View:
which have been marked obsolete.
Several ViewSheet methods related to Revisions have been replaced with new names. The original members have been obsoleted. This table lists the changes:
Several methods of AnalyticalModel have been marked obsolete:
Their replacements are more specialized additions in AnalyticalModelSurface and the new classes AnalyticalModelStick and AnalyticalModelColumn, described below.
To check if an analytical model is a surface type of element, try to downcast it to AnalyticalModelSurface.
The method
has been obsoleted – use
as a replacement.
A new overload has been introduced for
accepting ids for the type, bar type and hook type. The previous version has been obsoleted.
A new overload has been introduced for
accepting ids for the type, bar type and hook types. The previous version has been obsoleted.
The method
has been obsoleted – use
as a replacement.
A new overload has been introduced for
accepting ids for the type and sheet type. The previous version has been obsoleted.
The method
has been obsoleted. Use
as a replacement.
The following classes:
have been obsoleted. They did not have specific API access available in the first place.
The enumerated value BoundaryConditionsType.Nothing was removed from the enumerated type. This was a default value which could never be returned or set for any element.
The new method
supports setting of the selected elements in the active document.
The following items are now obsolete:
The properties
did not match properties available in the Revit user interface, and thus should not have been exposed in the API. They have been removed completely in Revit 2015.
The method NewWire() has been obsoleted and replaced by the new method
The new method supports creation of straight, arc, chamfer, and spline wires.
Several new methods have been introduced to edit the layout of an existing wire:
New properties on wire:
Several API routines that returned HashSet<IFCAnyHandle> now return an ICollection<IFCAnyHandle> instead.
IFCFile has a new Read() function that returns the number of errors and warnings reported by the toolkit during the read operation. This is in addition to the existing Read() function.
IFCAnyHandle now has SetAttribute() functions for each data type to reduce the use of the IFCData class.
IFCLegacyStairOrRamp has two new functions, GetBoundaryLines() and GetWalkLines(), that return the curve loops associated with the boundaries and walking lines of the legacy stair or ramp, respectively.
The properties:
have been obsoleted. Because the EnergyAnaysisDetailModel is intended to be generated at a single point in time, and is not persistently updated as changes are made to the original elements used to generate the energy analysis model, the model has been decoupled from direct relationships with the generating Revit elements. As replacements, the API now offers:
These properties offer the unique id of the related elements instead. In the case of potential relationships with linked model elements, two unique ids are available.
As a reminder, the EnergyAnaysisDetailModel is intended to be generated and used immediately – none of the data or relationships that it contains is updated as changes are made to the corresponding Revit model. Dispose of the generated EnergyAnaysisDetailModel using the Destroy() method as soon as you have extracted the needed information.
The property Material.MaterialCagtegory has been obsoleted and replaced by Material.MaterialCategory.
This method has been obsoleted – use
as a replacement.
This class has moved from namespace Autodesk.Revit.DB to Autodesk.Revit.DB.Structure.
This enumerated type value has been renamed to OST_MassGlazing.
Previously, the ElementIntersectsElementFilter would report the target element as an "intersection" with itself. This behavior has been changed; the filter will no longer pass the target element.
The ExtensibleStorageFilter class has moved from namespace Autodesk.Revit.DB to Autodesk.Revit.DB.ExtensibleStorage.
The MeshTriangle class no longer inherits from APIObject.
The method CurtainGridLine.Move() has been obsoleted. Use ElementTransformUtils.MoveElement() to accomplish the same result.
Previously, when this function couldn't create a compatible CurveLoop, it would return null. It now throws an exception in this situation.
The following obsolete APIs and classes have been removed:
The new property
allows you to read the currently active graphical view of the currently active document. Unlike UIDocument.ActiveView, this property will never return auxiliary views like the Project Browser or System Browser if the user has happened to make a selection in one of those views.
The new methods
allow full control over the Sketchy Lines settings for a given view.
Revit has a default type for different categories. This default type is shown in the Revit User Interface when the related tool is invoked to create an element of this category.
These members provide read and write access to the default type for a given family category id:
These members provide read and write access to the default type for a non-Family element type:
The new classes:
are used to define how objects of certain kind and scope are to be organized for the purpose of numbering/tagging them. Each NumberingSchema controls numbering of elements of one particular kind. Instances of NumberingSchema are also elements and there is always only one of each type in every Revit document. Available types of all built-in numbering schemas are enumerated in NumberingSchemaTypes class.
In this release NumberingSchema applies only to the built-in types matching elements of these categories:
Reinforcement and Rebar is now allowed to be hosted in Parts if those Parts come from a structural layer of a valid reinforcement host.
The methods:
accept compatible parts as host elements.
The new method:
identifies if a proposed host elements is valid for reinforcement.
The new presentation mode capabilities allow the user to specify how rebar sets are shown in a given view. Bar presentation schemes simplify the view while maintaining an identifiable footprint in which the rebar set is placed. In the API, the following members have been added to support this capability:
The default settings for bar presentation can be accessed from
The new members:
support the new Revit capability where single instances of fabric sheets can be placed precisely to reinforce sections of concrete walls or floors.
The new methods:
create a default element type for the given reinforcement class. This is useful if there is no existing type element of this kind in the document.
The new overloads:
create new reinforcement area elements automatically related to the host's boundary.
The property:
gets the rebar shape family id.
The type of host for rebars. This type matches the value returned by the new parameter BuiltInParameter.REBAR_HOST_CATEGORY.
The new method:
returns the local coordinate system from analytical model element.
The AnalyticalModelSurface class has been extended with several new members:
These new members support checking and manipulating alignment, projection and extension of AnalyticalModelSurface elements such floors, slabs and walls.
The new class:
represents a stick in the structural analytical model (A beam, brace or column). This class contains several members to check and manipulate the alignment, projection and extension properties:
The new class:
represents an analytical model of structural column. It is a subclass of AnalyticalModelStick. This class contains members to check and manipulate extension properties:
The new properties:
provide the ability to read and change how the load is oriented to the associated host or related work plane.
The new methods:
access the Boundary Conditions element orientation feature that allows orientation of boundary conditions to the local coordinate system of the associated analytical model.
The new method:
gets the definition of the coordinate system that is used by the element's translation and rotation parameters (e.g. X Translation or Z Rotation).
The new method:
accesses the Boundary Conditions type (Point, Line or Area).
Revit now supports defined data structures to represent standard structural section shapes. In support of this feature a hierarchy of classes were introduced to the API:
Only beams, braces and structural columns can have a structural section. At the level of the Family, these members:
identify if the family carries a structural section and its shape.
At the level of the FamilySymbol, these members:
provide access to the specific parameterized structural section for a given FamilySymbol.
The new method:
returns the user-visible name of structural section shape.
The methods:
support setting / getting / removing the end references for family instances of a structural framing type.
Family instances need to be non-concrete and joined at the given end. As the new end reference can be set appropriate face of the joined element at the given end. The setback value will be changed as a result of any reference change.
The methods:
support disallowing / allowing structural framing elements to join at the end to others.
Family instances need to be of a structural framing category. If the framing element is already joined at the end, and becomes disallowed to join, it will become disconnected. If the framing element end is allowed to join and if that end is near other elements it will become joined.
Revit 2015 introduces new API classes and members for accessing project Revisions, their settings and associated Revision Clouds.
The new RevisionSettings class allows an application to read and modify the project-wide settings that affect Revisions and Revision Clouds.
The new property
determines the characters used to populate the Revision Number parameter of alphabetic Revisions.
The new property
determines the sizing of the cloud graphics for Revision Clouds in the project.
The new property
determines whether revision numbers for the project are determined on a per sheet or a whole project basis.
The new Revision class allows an application to read and modify the existing revisions in a project and also to create new revisions. Revision is a subclass of element.
The new method
provides an ordered list of all of the Revisions in the document.
The new method
allows the ordering of the Revisions within the project to be changed.
The new method
creates a new Revision in the document.
The data associated with a Revision, and its associated settings within the project, can be read and modified through the following new properties:
The new methods
allow an application to combine a specified Revision with the next or previous Revision in the model. Combining the Revisions means that the RevisionClouds and revision tags associated with the specified Revision will be reassociated with the next Revision and the specified Revision will be deleted from the model. This method returns the ids of the RevisionClouds that were reassociated.
The new method
provides access to the Revision Number for a Revision when the numbering in the project is by sheet.
The new RevisionCloud class allows an application to access information about the revision clouds that are present within a model and to create new revision clouds.
The new method
allows an application to create a new RevisionCloud in a specified view based on a series of lines and curves.
The new property
allows an application to read an modify the Revision associated with the RevisionCloud.
The new method
allows an application to easily check whether a RevisionCloud is associated with a Revision that has already been issued.
The new method
allows an application to obtain the ids of the ViewSheets where the RevisionCloud may appear (either because the RevisionCloud is placed directly on the ViewSheet or because the RevisionCloud is visible in some View on the ViewSheet).
The new ViewSheet method
provides access to the Revision Number for a RevisionCloud when the numbering in the project is by sheet.
The property:
has been enhanced to return geometry from RevisionCloud elements. This will return the actual curved lines that make up the cloud.
The new method
allows an application to read the Curves that form the RevisionCloud's sketch. This will return the sketched curves that define the basic outline of the cloud and not the arcs that Revit attaches to these curves to create the cloud appearance.
Revit now allows users to reorder parameters within their groups for a given family, ensuring that the parameters are presented to the user in the most logical order. Several API changes have been introduced related to this.
The new methods
returns the parameters associated to family types or elements in the specified order. Note that for Element.GetOrderedParameters(), the returned collection only includes parameters that are shown in the Properties Palette (unlike Element.Parameters).
The new method
reorders the family parameters within the family according to the specified input.
The new method
sorts the family parameters according to the desired automatic sort order.
The new method:
sets the description for a family parameter.
The new property:
gets the stored tooltip description of the parameter definition.
Several new members added to the Wall class provide support for reading information about stacked wall and stacked wall members.
The new method
gets the sub walls which belong to a stacked wall, with the ids returned in order from bottom to top.
The new properties
identify if the wall is a stacked wall, a member of a stacked wall, and if the wall is a member of the stacked wall, the id of the stacked wall that owns this wall.
The new property
provides read/write access to the Function property of wall types.
As schedules now support up to 8 applied filters, the following methods now allow up to 8 filters to be applied:
The new property
provides the ability to customize the name of grand total title row for a schedule.
Images can now be added to schedules via parameters defined as type "Image". In schedule views, the image parameter will display the path of the ImageType, but the image itself displays in ScheduleSheetInstances placed on a sheet. The value of the "Image" parameters is an ElementId representing an ImageType element.
The new ImageType class is a subclass of ElementType representing a type containing an image. Instances of this type may also be displayed on 2D views or sheets directly.
The new method:
provides the ability to create a new ImageType element and loads a copy of the image into it.
The new members:
provide the ability to manage the contents of the image, and reload it from its original path location or a new location.
The new members
provide the ability to affect the size and display characteristics of schedules that contain images.
The new method:
creates a new linked IFC type representing an IFC model opened for reference. Once created, you can place instance(s) of this type using regular RevitLinkInstance methods.
The new method:
supports different options for import and create of a new document based on an IFC file:
ImporterIFC offers new members to assist with the implementation of custom IFC importers:
BuiltInParameter.IFC_*_GUID values (IFC_GUID, IFC_TYPE_GUID, IFC_PROJECT_GUID, IFC_BUILDING_GUID, and IFC_SITE_GUID) are no longer required to be unique, and are schedulable.
BuiltInParameter.IFC_TYPE_GUID has a default English value of "Type IfcGUID" to distinguish it from BuiltInParameter.IFC_GUID.
The new classes:
offer the ability to create imported geometry elements directly in the project document. The geometry can include closed solids or meshes. The geometry will be validated to ensure that it is valid for Revit use.
The created elements must be assigned to a category. This grants the elements a collection of available parameters and some limited behaviors.
The new classes:
can be used create solid, shell, or polymeshes bounded by a set of connected planar facets, created by adding TessellatedFace objects one by one. The utility includes some ability to heal imprecisions and discontinuities in the inputs, and offers some diagnostics regarding geometry that is too imprecise to be used.
This new framework allows add-ins to provide Revit with external content obtained from anywhere. Add-ins implementing a server for this type can obtain their external content from the web, an external database, or another application. The Revit user can browse the external content locally and select appropriate content to use in their models.
In this release, only some types of Revit external content are supported as External Resources:
The new interface:
allows developers to provide resources from an external source. Revit will call IExternalResourceServer.LoadResource(), and the server will provide the data for the requested resource.
The new interface:
gives Revit a list of the resources handled by the server. The resources will appear in Revit's UI when the Revit user browses for the appropriate link type. Servers can also provide custom error-handling UI. This allows servers to handle cases Revit could not know about. For example, if the network is down and the server cannot access its resources, the server can put up a detailed error message explaining the problem.
The new class:
contains identifying information for resources which come from external servers. Each external server link will contain an ExternalResourceReference. The ExternalResourceReference contains the id of the server which provided the resource. The class also contains a string-to-string map which contains the actual identity information for the reference. Servers can define their own conventions for naming and identifying resources.
Revit 2015 introduces a number of new classes to give applications access to the keynote and assembly code data used within a Revit model.
Because there are a number of similarities in the way the keynote data and the assembly code data are structured, many of the operations can be accessed through base classes that provide common functionality for key-based tree-structured data.
The new class:
represents a collection of key-based tree entries stored within the Revit model, such as the keynote or assembly code table. There are two subclasses – KeynoteTable for the keynote table, and AssemblyCodeTable for the assembly code table.
The methods:
are static methods which allow access to the current table.
The methods:
allow the user to reload the keynote or assembly code table. LoadFrom() allows the table to be reloaded from a new location.
The method:
allows access to the data in the table.
The class:
represents an individual entry within a key-based tree. It provides properties for the key and parent key. The subclasses, KeynoteEntry and ClassificationEntry, provide properites and methods specific to the keynote table and the assembly code table. Keynotes have access to the keynote text, while ClassificationEntries have access to the level, category Id, and description.
The new property:
determines the type of analysis used when producing the export gbXML file for the document. Options are:
The new class:
analyzes which elements are part of the building envelope (the building elements exposed to the outside). This class uses a combination of ray-casting and flood-fill algorithms in order to find the building elements that are exposed to the outside of the building. This method can also look for the bounding building elements for enclosed space volumes inside the building. Options for the analysis include:
The new class
contains settings for grouping, sorting, and filtering of items in the project browser.
New methods
New static Methods
New properties
The new class
contains data for each folder item in the organization settings of the project browser including folder parameter Id and folder name.
New properties
Three new properties have been added to Application to retrieve file paths from revit.ini:
The new property
identifies if a workshared document is opened as detached.
This event is raised when Revit has just enabled worksharing in the document. Handlers of this event are permitted to make modifications to any document (including the active document), except for documents that are currently in read-only mode.
The new method
requests to change the active view by posting a message asynchronously. Unlike setting the ActiveView property, this will not make the change in active view immediately. Instead the request will be posted to occur when control returns to Revit from the API context. This method is permitted to change the active view from the Idling event or an ExternalEvent callback.
The new methods
places a request on Revit's command queue for the user to place instances of the specified ElementType. The former is for general use, the latter is specifically for legend views. This does not execute immediately, but instead when control returns to Revit from the current API context. This method starts its own transaction. In a single invocation, the user can place multiple instances of the input element type until they finish the placement (with Cancel or ESC or a click elsewhere in the UI). This method invokes the UI when control returns from the current API context; because of this, the normal Revit UI options will be available to the user, but the API will not be notified when the user has completed this action. Because this request is queued to run at the end of the current API context, only one such request can be set (between this and the commands set by UIApplication.PostCommand()). This differs from UIDocument.PromptForFamilyInstancePlacement() as that method can be run within the current API context, but the user is not permitted full access to the user interface options during placement.
The new method
Prompts the user to place a specified view onto a sheet. Set allowReplaceExistingSheetViewport to true to allow the user to replace the existing viewport.
The new method
prompts the user to select instance elements to change them to the input type.
The Revit Link API has been updated – all methods which took a ModelPath argument now have new versions which take an ExternalResourceReference argument. These methods can also work with files from disk. ExternalResourceReference.CreateLocalResource() can be used to create an ExternalResourceReference corresponding to a local file.
The older Revit link methods have not been deprecated; they are still available for local links.
This property is now writable, and can be toggled between Attachment and Overlay.
The new property
determines if the category is shown in the Visibility/Graphics settings grouped with the model, annotation, or analytical model categories. Note that import categories are also "model" but will be shown separately in the dialog. Some categories not shown in the dialog and will return Internal for the category type.
The new property
contains the localized string describing the family in which this ElementType belongs. For family symbols, this will be the name of the associated Family. For system family types, this will be the name used to group related types, such as "Oval Duct" or "Curtain Wall".
The events:
allow you to subscribe to an event to be notified when Revit is just about to duplicate an element type, and after Revit has finished duplicating an element type.
The new static method
validates whether a proposed material name is unique in document. This will be used to confirm the validity of the name before creating a new material via Material.Create() or Material.Duplicate().
The new property
identifies if the view is an assembly view.
The new property
returns the view title. This consists of the view name plus other modifiers, such as the view type, sheet number, area scheme, and/or assembly type, depending on the specifics of the view.
The following properties are now settable:
Setting these properties allow an application to toggle Model Categories, Annotation Categories, Analytical Model Categories, or Import Categories visibility.
The new method
allows an application to create a new drafting view in the model with a specified ViewFamilyType.
The new method
supports reorienting the 3D view to align with the forward direction. This is an alternate method to reorient the view using typical Revit calculations for other related parameters in ViewOrientation3D.
The new class ReferenceableViewUtils provides utility methods that allow an application to manage reference views such as reference sections or reference callouts.
The new methods
allows an application to read and change the view referenced by a reference view (such as a reference section or reference callout).
The new method
provide the ability to identify the given built-in parameter group is user assignable for family parameter or not.
The property:
now returns the rotation angle in the plane of the view, for view-specific family instances such as detail components. Previously the angle was measured from an axis outside the plane of the view.
The new overload method
allows an application to prompt the user to place instances of a specified family symbol interactively. The options class supports a setting requiring the mode to be set to place an air terminal family instance directly on a duct (the option is either set to be on or off, the user cannot toggle this during placement).
The events:
allow you to subscribe to an event to be notified when Revit is just about to load a family into a document, and after Revit has just finished loading the family.
The new method:
creates a new curve that has the same shape, but has its orientation reversed.
The new method:
creates a new curve that is offset from the original curve by a certain distance. The offset direction is determined by the normal of the curve at any given point.
The new method:
creates a new closed curve loop by thickening the input open curve loop with respect to a given plane.
The new method:
creates a new CurveLoop that is an offset of the original CurveLoop. This is effectively done by offsetting each Curve in the CurveLoop and trimming the ends to form a new continuous CurveLoop.
The new method:
returns a list of closed curve loops that correspond to the edge loops of the face. Curves in each curve loop correspond to individual edges.
The new method:
explicitly sets the geometry of the curve element with the option to not affect the geometry of any currently joined curve elements. After the curve geometry is set, other curves may autojoin to the new curve geometry.
The new method:
sets the sketch plane and the curve for the CurveElement simultaneously (allowing the SketchPlane to be successfully modified in a way that would be incompatible if set separately). This method will not affect the geometry of any current joined curve elements.
The new method:
updates the geometry of the FreeFormElement to the given shape preserving References to the existing geometry where possible.
The new property:
determines if the material's appearance in a shaded view should be driven by the settings of the render appearance, or driven by the material's graphics properties.
The new property:
indicates whether to mask coincident lines when printing.
The new properties:
provide project level read access to connector properties which can be set in the family environment.
The method
identifies if the input is valid to be used as a name of an object in Revit.
This routine checks only for prohibited characters in the string. When setting the name for an object there are other specific considerations which are checked (for example, the same name cannot be used twice for different elements of the same type). This routine does not check those conditions.
The method
compares the input two names according to the comparison rules in Revit. The method returns a negative value if nameA comes before nameB, zero if nameA is equivalent to nameB,and a positive value if nameA comes after nameB. The method is similar to String.Compare(), but uses Revit rules for comparison. This involves breaking the names into alphabetic and numeric tokens and comparing tokens individually.
The new methods:
allow temporary enable and disable of Updaters. This allows an application to control whether an updater is triggered unnecessarily based on changes the application knows about.
The new method:
allows an application to test that libraries necessary to support rendering and 3D exports are installed and available.
The new interface
inherits from IDropHandler. This includes an extra interface to be executed when custom data is dragged and dropped onto the Revit user interface. This interface is different from IDropHandler in that it allows the handler to verify whether the drop event can be executed on the given view.
The new interface method
Implement this method to inform Revit whether the drop event can be executed onto the given view.