ItemFactoryBaseNewFamilyInstance(Reference, Line, FamilySymbol) Method

Inserts a new instance of a family onto a face referenced by the input Reference instance, using a line on that face for its position, and a type/symbol.

Namespace: Autodesk.Revit.Creation
Assembly: RevitAPI (in RevitAPI.dll) Version: 26.0.4.0 (26.0.4.0)
Syntax
Copy
public FamilyInstance NewFamilyInstance(
	Reference reference,
	Line position,
	FamilySymbol symbol
)

Parameters

reference  Reference
A reference to a face.
position  Line
A line on the face defining where the symbol is to be placed.
symbol  FamilySymbol
A FamilySymbol object that represents the type of the instance that is to be inserted. Note that this symbol must represent a family whose FamilyPlacementType is WorkPlaneBased or CurveBased.

Return Value

FamilyInstance
An instance of the new object if creation was successful, otherwise .
Exceptions
ExceptionCondition
ArgumentNullExceptionThrown when a non-optional argument was null.
ArgumentExceptionThrown when the function cannot get a face from the reference, or, when the family cannot be placed as line-based on an input face reference, because its FamilyPlacementType is not WorkPlaneBased or CurveBased
ArgumentsInconsistentExceptionThrown when the family cannot be placed on this line as it does not coincide with the input face.
InvalidOperationExceptionThrown when Revit is unable to place the family instance.
ArgumentExceptionThrown if The symbol is not active.
Remarks
Use this method to insert one family instance on a face of another element, using a line on the face to define the position and direction of the new symbol.

The type/symbol that is used must be loaded into the document before this method is called. Families and their symbols can be loaded using the Document.LoadFamily or Document.LoadFamilySymbol methods.

The host object must support insertion of instances, otherwise this method will fail. If the instance fails to be created an exception may be thrown.

Note: if the created family instance includes nested instances, the API framework will automatically regenerate the document during this method call.

See Also