Inserts a new instance of a family into the document, using a location, type/symbol and a base level.

Namespace: Autodesk.Revit.Creation
Assembly: RevitAPI (in RevitAPI.dll) Version: 23.0.0.0 (23.1.0.0)

Syntax

C#
public FamilyInstance NewFamilyInstance( XYZ location, FamilySymbol symbol, Level level, StructuralType structuralType )

Visual Basic
Public Function NewFamilyInstance ( _ location As XYZ, _ symbol As FamilySymbol, _ level As Level, _ structuralType As StructuralType _ ) As FamilyInstance

Visual C++
public: FamilyInstance^ NewFamilyInstance( XYZ^ location, FamilySymbol^ symbol, Level^ level, StructuralType structuralType )

Parameters

location: Type: Autodesk.Revit.DB..::..XYZ
The physical location where the instance 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.

level: Type: Autodesk.Revit.DB..::..Level
A Level object that is used as the base level for the object.

structuralType: Type: Autodesk.Revit.DB.Structure..::..StructuralType
If structural then specify the type of the component.

Return Value

If creation was successful then an instance to the new object is returned, otherwise nullNothingnullptra null reference (Nothing in Visual Basic).

Remarks

This method is used to add a family instance that doesn't require a host element, but that can be associated to a level. If the instance fails to be created an exception may be thrown.

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.

All levels within the document can be found by iterating over the entire document and searching for objects of type Autodesk.Revit.Elements.Level.

Some families, such as Beams, have more than one endpoint and are inserted in the same manner as single point instances. Once inserted these linear family instances can have their endpoints changed by using the instance's Element.Location property.

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

Examples

CopyC#

FamilyInstance CreateColumn(Autodesk.Revit.DB.Document document, Level level)
{
    // Get a Column type from Revit
    FilteredElementCollector collector = new FilteredElementCollector(document);
    collector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralColumns);
    FamilySymbol columnType = collector.FirstElement() as FamilySymbol;

    FamilyInstance instance = null;
    if (null != columnType)
    {
        // Create a column at the origin
        XYZ origin = new XYZ(0, 0, 0);

        instance = document.Create.NewFamilyInstance(origin, columnType, level, StructuralType.Column);
    }

    return instance;
}

CopyVB.NET

Private Function CreateColumn(document As Autodesk.Revit.DB.Document, level As Level) As FamilyInstance
    ' Get a Column type from Revit
    Dim collector As New FilteredElementCollector(document)
    collector.OfClass(GetType(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralColumns)
    Dim columnType As FamilySymbol = TryCast(collector.FirstElement(), FamilySymbol)

    Dim instance As FamilyInstance = Nothing
    If columnType IsNot Nothing Then
        ' Create a column at the origin
        Dim origin As New XYZ(0, 0, 0)

        instance = document.Create.NewFamilyInstance(origin, columnType, level, StructuralType.Column)
    End If

    Return instance
End Function

Exceptions

Exception	Condition
Autodesk.Revit.Exceptions..::..ArgumentException	Thrown if the family symbol does not exist in the given document.
Autodesk.Revit.Exceptions..::..ArgumentException	Thrown if the level does not exist in the given document.
Autodesk.Revit.Exceptions..::..ArgumentException	Thrown if The symbol is not active.