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: 21.0.0.0 (21.1.1.109)

Syntax

C#
public FamilyInstance NewFamilyInstance( Reference reference, Line position, FamilySymbol symbol )

Visual Basic
Public Function NewFamilyInstance ( _ reference As Reference, _ position As Line, _ symbol As FamilySymbol _ ) As FamilyInstance

Visual C++
public: FamilyInstance^ NewFamilyInstance( Reference^ reference, Line^ position, FamilySymbol^ symbol )

Parameters

reference: Type: Autodesk.Revit.DB..::..Reference
A reference to a face.

position: Type: Autodesk.Revit.DB..::..Line
A line on the face defining where the symbol is to be placed.

symbol: Type: Autodesk.Revit.DB..::..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

An instance of the new object if creation was successful, otherwise nullNothingnullptra null reference (Nothing in Visual Basic).

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.

Examples

CopyC#

public void PlaceStiffenerOnWallFaceRef(Autodesk.Revit.DB.Document doc)
{
    FilteredElementCollector wallCollector = new FilteredElementCollector(doc);
    wallCollector.OfClass(typeof(Wall));
    Wall wall = wallCollector.FirstElement() as Wall;

    // The structural stiffeners family type is compatible with line-based face placement
    FilteredElementCollector fsCollector = new FilteredElementCollector(doc);
    fsCollector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralStiffener);
    FamilySymbol stiffenerSymbol = fsCollector.FirstElement() as FamilySymbol;

    // Get side face of wall
    IList<Reference> sideFaces = HostObjectUtils.GetSideFaces(wall, ShellLayerType.Exterior);
    Reference sideFaceRef = sideFaces[0];

    // Generate line for path
    Face face = wall.GetGeometryObjectFromReference(sideFaceRef) as Face;
    BoundingBoxUV bbox = face.GetBoundingBox();
    UV lowerLeft = bbox.Min;
    UV upperRight = bbox.Max;
    double deltaU = upperRight.U - lowerLeft.U;
    double deltaV = upperRight.V - lowerLeft.V;
    double vOffset = deltaV * 0.60; // 60% up the wall face

    UV firstPoint = lowerLeft + new UV(deltaU * 0.20, vOffset);
    UV lastPoint = lowerLeft + new UV(deltaU * 0.80, vOffset);

    Line line = Line.CreateBound(face.Evaluate(firstPoint), face.Evaluate(lastPoint));

    doc.Create.NewFamilyInstance(sideFaceRef, line, stiffenerSymbol);
}

CopyVB.NET

Public Sub PlaceStiffenerOnWallFaceRef(doc As Autodesk.Revit.DB.Document)
    Dim wallCollector As New FilteredElementCollector(doc)
    wallCollector.OfClass(GetType(Wall))
    Dim wall As Wall = TryCast(wallCollector.FirstElement(), Wall)

    ' The structural stiffeners family type is compatible with line-based face placement
    Dim fsCollector As New FilteredElementCollector(doc)
    fsCollector.OfClass(GetType(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralStiffener)
    Dim stiffenerSymbol As FamilySymbol = TryCast(fsCollector.FirstElement(), FamilySymbol)

    ' Get side face of wall
    Dim sideFaces As IList(Of Reference) = HostObjectUtils.GetSideFaces(wall, ShellLayerType.Exterior)
    Dim sideFaceRef As Reference = sideFaces(0)

    ' Generate line for path
    Dim face As Face = TryCast(wall.GetGeometryObjectFromReference(sideFaceRef), Face)
    Dim bbox As BoundingBoxUV = face.GetBoundingBox()
    Dim lowerLeft As UV = bbox.Min
    Dim upperRight As UV = bbox.Max
    Dim deltaU As Double = upperRight.U - lowerLeft.U
    Dim deltaV As Double = upperRight.V - lowerLeft.V
    Dim vOffset As Double = deltaV * 0.6
    ' 60% up the wall face
    Dim firstPoint As UV = lowerLeft + New UV(deltaU * 0.2, vOffset)
    Dim lastPoint As UV = lowerLeft + New UV(deltaU * 0.8, vOffset)

    Dim line__1 As Line = Line.CreateBound(face.Evaluate(firstPoint), face.Evaluate(lastPoint))

    doc.Create.NewFamilyInstance(sideFaceRef, line__1, stiffenerSymbol)
End Sub

Exceptions

Exception	Condition
Autodesk.Revit.Exceptions..::..ArgumentNullException	Thrown when a non-optional argument was null.
Autodesk.Revit.Exceptions..::..ArgumentException	Thrown 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
Autodesk.Revit.Exceptions..::..ArgumentsInconsistentException	Thrown when the family cannot be placed on this line as it does not coincide with the input face.
Autodesk.Revit.Exceptions..::..InvalidOperationException	Thrown when Revit is unable to place the family instance.
Autodesk.Revit.Exceptions..::..ArgumentException	Thrown if The symbol is not active.