Revit 2025 API

ItemFactoryBaseNewFamilyInstance(Face, Line, FamilySymbol) Method

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: 25.0.0.0 (25.0.0.0)

Syntax

C++

public FamilyInstance NewFamilyInstance(
	Face face,
	Line position,
	FamilySymbol symbol
)

Public Function NewFamilyInstance ( 
	face As Face,
	position As Line,
	symbol As FamilySymbol
) As FamilyInstance

public:
FamilyInstance^ NewFamilyInstance(
	Face^ face, 
	Line^ position, 
	FamilySymbol^ symbol
)

member NewFamilyInstance : 
        face : Face * 
        position : Line * 
        symbol : FamilySymbol -> FamilyInstance

Parameters

face Face: A face of a geometry object.
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

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

Example

C++

Copy

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);     
}

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

No code example is currently available or this language may not be supported.

Reference

ItemFactoryBase Class

NewFamilyInstance Overload

Autodesk.Revit.Creation Namespace

Send comments on this topic to Autodesk