[Nice3point]

Summary of the Pull Request

What is this about:

Element lookups follow LINQ First and FirstOrDefault: ToElement and AsElement return the element or throw, and their OrDefault counterparts return the element or null.

Description:

What changed

Member	No element	Element of another type
ToElement, ToElement<T>	InvalidOperationException	InvalidCastException
AsElement, AsElement<T>	InvalidOperationException	InvalidCastException
ToElementOrDefault, ToElementOrDefault<T>	null	null
AsElementOrDefault, AsElementOrDefault<T>	null	null

• ToElementOrDefault, ToElementOrDefault<T>, AsElementOrDefault, and AsElementOrDefault<T> are new.
• ToElement, ToElement<T>, AsElement, and AsElement<T> return non-nullable types.
• The changelog lists the change under Breaking changes with the migration to the OrDefault counterpart.

Where to look

• A missing element throws InvalidOperationException, the exception collector.First() throws for an empty collector. ArgumentException was the alternative, with the id as the invalid argument.
• AsElement throws for a parameter that holds no element, such as an empty material parameter or a category id. Code that reads an optional parameter moves to AsElementOrDefault.
• The change is breaking at run time only: the return types lose nullability, and existing null checks still compile.

How verified

• Build: the library under Release.R19, R21, R23, R24, R25, and R27, zero errors.
• Tests in Revit 2027, against every family sample: ElementIdExtensionsTests 92 passed, ParameterExtensionsTests 30 passed, none skipped.
• Not covered: test runs on Revit 2026 and earlier.

Open questions

• The breaking change sits in the unreleased 2027.0.6 section of the changelog. A minor version is the alternative.
• ToElements<T> and ToOrderedElements<T> keep their behavior: a collection that mixes types throws InvalidCastException.

Quality Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.