Inserts a new instance of a family into the document, using a location, type/symbol, the host element and a reference direction.

Namespace: Autodesk.Revit.Creation
Assembly: RevitAPI (in RevitAPI.dll) Version: 22.0.0.0 (22.1.0.0)

Syntax

C#
public FamilyInstance NewFamilyInstance( XYZ location, FamilySymbol symbol, XYZ referenceDirection, Element host, StructuralType structuralType )

Visual Basic
Public Function NewFamilyInstance ( _ location As XYZ, _ symbol As FamilySymbol, _ referenceDirection As XYZ, _ host As Element, _ structuralType As StructuralType _ ) As FamilyInstance

Visual C++
public: FamilyInstance^ NewFamilyInstance( XYZ^ location, FamilySymbol^ symbol, XYZ^ referenceDirection, Element^ host, 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.

referenceDirection: Type: Autodesk.Revit.DB..::..XYZ
A vector that dictates the direction of certain family instances.

host: Type: Autodesk.Revit.DB..::..Element
A host object into which the instance will be embedded

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 allows you to create FamilyInstance objects that require both a location and direction. 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.

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#

// Get a floor to place the beds
 FilteredElementCollector collector = new FilteredElementCollector(document);
 Floor floor = collector.OfClass(typeof(Floor)).FirstElement() as Floor;
 if (floor != null)
 {
     // Find a Bed-Box family
     Family family = null;
     FilteredElementCollector famCollector = new FilteredElementCollector(document);
     famCollector.OfClass(typeof(Family));
     ICollection<Element> collection = famCollector.ToElements();
     foreach (Element element in collection)
     {

         if (element.Name.CompareTo("Bed-Box") == 0)
         {
             family = element as Family;
             break;
         }
     }

     if (family != null)
     {
         // Enumerate the beds in the Bed-Box family
         FilteredElementCollector fsCollector = new FilteredElementCollector(document);
         ICollection<Element> fsCollection = fsCollector.WherePasses(new FamilySymbolFilter(family.Id)).ToElements();
         IEnumerator<Element> symbolItor = fsCollection.GetEnumerator();

         int x = 0, y = 0;
         int i = 0;
         while (symbolItor.MoveNext())
         {
             FamilySymbol symbol = symbolItor.Current as FamilySymbol;
             XYZ location = new XYZ(x, y, 0);
             XYZ direction = new XYZ();
             switch (i % 3)
             {
                 case 0:
                     direction = new XYZ(1, 1, 0);
                     break;
                 case 1:
                     direction = new XYZ(0, 1, 1);
                     break;
                 case 2:
                     direction = new XYZ(1, 0, 1);
                     break;
             }
             FamilyInstance instance = document.Create.NewFamilyInstance(location, symbol, direction, floor, StructuralType.NonStructural);
             x += 10;
             i++;
         }
     }
 }

CopyVB.NET

' Get a floor to place the beds
Dim collector As New FilteredElementCollector(document)
Dim floor As Floor = TryCast(collector.OfClass(GetType(Floor)).FirstElement(), Floor)
If floor IsNot Nothing Then
    ' Find a Bed-Box family
    Dim family As Family = Nothing
    Dim famCollector As New FilteredElementCollector(document)
    famCollector.OfClass(GetType(Family))
    Dim collection As ICollection(Of Element) = famCollector.ToElements()
    For Each element As Element In collection

        If element.Name.CompareTo("Bed-Box") = 0 Then
            family = TryCast(element, Family)
            Exit For
        End If
    Next

    If family IsNot Nothing Then
        ' Enumerate the beds in the Bed-Box family
        Dim fsCollector As New FilteredElementCollector(document)
        Dim fsCollection As ICollection(Of Element) = fsCollector.WherePasses(New FamilySymbolFilter(family.Id)).ToElements()
        Dim symbolItor As IEnumerator(Of Element) = fsCollection.GetEnumerator()

        Dim x As Integer = 0, y As Integer = 0
        Dim i As Integer = 0
        While symbolItor.MoveNext()
            Dim symbol As FamilySymbol = TryCast(symbolItor.Current, FamilySymbol)
            Dim location As New XYZ(x, y, 0)
            Dim direction As New XYZ()
            Select Case i Mod 3
                Case 0
                    direction = New XYZ(1, 1, 0)
                    Exit Select
                Case 1
                    direction = New XYZ(0, 1, 1)
                    Exit Select
                Case 2
                    direction = New XYZ(1, 0, 1)
                    Exit Select
            End Select
            Dim instance As FamilyInstance = document.Create.NewFamilyInstance(location, symbol, direction, floor, StructuralType.NonStructural)
            x += 10
            i += 1
        End While
    End If
End If

Exceptions

Exception	Condition
Autodesk.Revit.Exceptions..::..ArgumentException	Thrown if The symbol is not active.