Creates Family instances within the document.

Namespace: Autodesk.Revit.Creation
Assembly: RevitAPI (in RevitAPI.dll) Version: 21.0.0.0 (21.1.1.109)

Syntax

C#
public ICollection<ElementId> NewFamilyInstances2(
	List<FamilyInstanceCreationData> dataList
)
Visual Basic
Public Function NewFamilyInstances2 ( _
	dataList As List(Of FamilyInstanceCreationData) _
) As ICollection(Of ElementId)
Visual C++
public:
ICollection<ElementId^>^ NewFamilyInstances2(
	List<FamilyInstanceCreationData^>^ dataList
)

Parameters

dataList
Type: System.Collections.Generic..::..List<(Of <(<'FamilyInstanceCreationData>)>)>
A list of FamilyInstanceCreationData which wraps the creation arguments of the families to be created.

Return Value

If the creation is successful, a set of ElementIds which contains the Family instances should be returned, otherwise the exception will be thrown.

Remarks

Note: ForbiddenForDynamicUpdateException might be thrown during a dynamic update if the inserted instance establishes a mutual dependency with another structure.

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

Examples

CopyC#
ICollection<ElementId> BatchCreateColumns(Autodesk.Revit.DB.Document document, Level level)
{
    List<FamilyInstanceCreationData> fiCreationDatas = new List<FamilyInstanceCreationData>();

    //ElementSet elementSet = null;
    ICollection<ElementId> elementSet = null;

    //Try to get a FamilySymbol
    FamilySymbol familySymbol = null;
    FilteredElementCollector collector = new FilteredElementCollector(document);
    ICollection<Element> collection = collector.OfClass(typeof(FamilySymbol)).ToElements();
    foreach (Element e in collection)
    {
        familySymbol = e as FamilySymbol;
        if (null != familySymbol.Category)
        {
            if ("Structural Columns" == familySymbol.Category.Name)
            {
                break;
            }
        }
    }

    if (null != familySymbol)
    {
        //Create 10 FamilyInstanceCreationData items for batch creation 
        for (int i = 1; i < 11; i++)
        {
            XYZ location = new XYZ(i * 10, 100, 0);
            FamilyInstanceCreationData fiCreationData =
                new FamilyInstanceCreationData(location, familySymbol, level,  StructuralType.Column);

            if (null != fiCreationData)
            {
                fiCreationDatas.Add(fiCreationData);
            }
        }

        if (fiCreationDatas.Count > 0)
        {
            // Create Columns
            elementSet = document.Create.NewFamilyInstances2(fiCreationDatas);
        }
        else
        {
            throw new Exception("Batch creation failed.");
        }
    }
    else
    {
        throw new Exception("No column types found.");
    }

    return elementSet;
}
CopyVB.NET
Private Function BatchCreateColumns(document As Autodesk.Revit.DB.Document, level As Level) As ICollection(Of ElementId)
    Dim fiCreationDatas As New List(Of FamilyInstanceCreationData)()

    'ElementSet elementSet = null;
    Dim elementSet As ICollection(Of ElementId) = Nothing

    'Try to get a FamilySymbol
    Dim familySymbol As FamilySymbol = Nothing
    Dim collector As New FilteredElementCollector(document)
    Dim collection As ICollection(Of Element) = collector.OfClass(GetType(FamilySymbol)).ToElements()
    For Each e As Element In collection
        familySymbol = TryCast(e, FamilySymbol)
        If familySymbol.Category IsNot Nothing Then
            If "Structural Columns" = familySymbol.Category.Name Then
                Exit For
            End If
        End If
    Next

    If familySymbol IsNot Nothing Then
        'Create 10 FamilyInstanceCreationData items for batch creation 
        For i As Integer = 1 To 10
            Dim location As New XYZ(i * 10, 100, 0)
            Dim fiCreationData As New FamilyInstanceCreationData(location, familySymbol, level, StructuralType.Column)

            If fiCreationData IsNot Nothing Then
                fiCreationDatas.Add(fiCreationData)
            End If
        Next

        If fiCreationDatas.Count > 0 Then
            ' Create Columns
            elementSet = document.Create.NewFamilyInstances2(fiCreationDatas)
        Else
            Throw New Exception("Batch creation failed.")
        End If
    Else
        Throw New Exception("No column types found.")
    End If

    Return elementSet
End Function

Exceptions

ExceptionCondition
Autodesk.Revit.Exceptions..::..ArgumentNullExceptionIf FamilyInstanceCreationData's 'curve' or 'symbol' member is nullNothingnullptra null reference (Nothing in Visual Basic).
Autodesk.Revit.Exceptions..::..InvalidOperationExceptionIf regeneration fails at the end of the batch creation.

See Also