Inserts a new instance of a family onto a face of an existing element, 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(
	Face face,
	Line position,
	FamilySymbol symbol
)
Visual Basic
Public Function NewFamilyInstance ( _
	face As Face, _
	position As Line, _
	symbol As FamilySymbol _
) As FamilyInstance
Visual C++
public:
FamilyInstance^ NewFamilyInstance(
	Face^ face, 
	Line^ position, 
	FamilySymbol^ symbol
)

Parameters

face
Type: Autodesk.Revit.DB..::..Face
A face of a geometry object.
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 PlaceStiffenerOnWallFace(Autodesk.Revit.DB.Document doc, Wall 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;

    // The only way to get a Face to use with this NewFamilyInstance overload
    // is from Element.Geometry with ComputeReferences turned on
    Face face = null;
    Options geomOptions = new Options();
    geomOptions.ComputeReferences = true;
    GeometryElement wallGeom = wall.get_Geometry(geomOptions);
    foreach (GeometryObject geomObj in wallGeom)
    {
        Solid geomSolid = geomObj as Solid;
        if (null != geomSolid)
        {
            foreach (Face geomFace in geomSolid.Faces)
            {
                face = geomFace;
                break;
            }
            break;
        }
    }

    // Generate line for path
    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.80; // 80% up the wall face

    UV firstPoint = lowerLeft + new UV(deltaU * 0.30, vOffset);
    UV lastPoint = lowerLeft + new UV(deltaU * 0.70, vOffset);

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

    doc.Create.NewFamilyInstance(face, line, stiffenerSymbol);     
}
CopyVB.NET
Public Sub PlaceStiffenerOnWallFace(doc As Autodesk.Revit.DB.Document, wall As 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)

    ' The only way to get a Face to use with this NewFamilyInstance overload
    ' is from Element.Geometry with ComputeReferences turned on
    Dim face As Face = Nothing
    Dim geomOptions As New Options()
    geomOptions.ComputeReferences = True
    Dim wallGeom As GeometryElement = wall.Geometry(geomOptions)
    For Each geomObj As GeometryObject In wallGeom
        Dim geomSolid As Solid = TryCast(geomObj, Solid)
        If geomSolid IsNot Nothing Then
            For Each geomFace As Face In geomSolid.Faces
                face = geomFace
                Exit For
            Next
            Exit For
        End If
    Next

    ' Generate line for path
    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.8
    ' 80% up the wall face
    Dim firstPoint As UV = lowerLeft + New UV(deltaU * 0.3, vOffset)
    Dim lastPoint As UV = lowerLeft + New UV(deltaU * 0.7, vOffset)

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

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

Exceptions

ExceptionCondition
Autodesk.Revit.Exceptions..::..ArgumentNullExceptionThrown when a non-optional argument was null.
Autodesk.Revit.Exceptions..::..ArgumentExceptionThrown when the function cannot get the Reference from the face, or, Family cannot be placed as line-based on an input face reference, because its FamilyPlacementType is not WorkPlaneBased or CurveBased
Autodesk.Revit.Exceptions..::..ArgumentsInconsistentExceptionThrown when the family cannot be placed on this line as it does not coincide with the input face.
Autodesk.Revit.Exceptions..::..InvalidOperationExceptionThrown when Revit is unable to place the family instance.
Autodesk.Revit.Exceptions..::..ArgumentExceptionThrown if The symbol is not active.

See Also