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

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

Syntax

C#
public FamilyInstance NewFamilyInstance(
	XYZ location,
	FamilySymbol symbol,
	Element host,
	Level level,
	StructuralType structuralType
)
Visual Basic
Public Function NewFamilyInstance ( _
	location As XYZ, _
	symbol As FamilySymbol, _
	host As Element, _
	level As Level, _
	structuralType As StructuralType _
) As FamilyInstance
Visual C++
public:
FamilyInstance^ NewFamilyInstance(
	XYZ^ location, 
	FamilySymbol^ symbol, 
	Element^ host, 
	Level^ level, 
	StructuralType structuralType
)

Parameters

location
Type: Autodesk.Revit.DB..::..XYZ
The physical location where the instance is to be placed on the specified level.
symbol
Type: Autodesk.Revit.DB..::..FamilySymbol
A FamilySymbol object that represents the type of the instance that is to be inserted.
host
Type: Autodesk.Revit.DB..::..Element
A host object into which the instance will be embedded
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 form of NewFamilyInstance is the most commonly used in Autodesk Revit since there are a large number of elements that use levels, such as Walls, Columns etc. 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: 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#
void CreateDoorsInWall(Autodesk.Revit.DB.Document document, Wall wall)
{
    // get wall's level for door creation
    Level level = document.GetElement(wall.LevelId) as Level;

    FilteredElementCollector collector = new FilteredElementCollector(document);
    ICollection<Element> collection = collector.OfClass(typeof(FamilySymbol))
                                               .OfCategory(BuiltInCategory.OST_Doors)
                                               .ToElements();
    IEnumerator<Element> symbolItor = collection.GetEnumerator();

    double x = 0, y = 0, z = 0;
    while (symbolItor.MoveNext())
    {
        FamilySymbol symbol = symbolItor.Current as FamilySymbol;
        XYZ location = new XYZ(x, y, z);
        FamilyInstance instance = document.Create.NewFamilyInstance(location, symbol, wall, level, StructuralType.NonStructural);
        x += 10;
        y += 10;
        z += 1.5;
    }
}
CopyVB.NET
Private Sub CreateDoorsInWall(document As Autodesk.Revit.DB.Document, wall As Wall)
    ' get wall's level for door creation
    Dim level As Level = TryCast(document.GetElement(wall.LevelId), Level)

    Dim collector As New FilteredElementCollector(document)
    Dim collection As ICollection(Of Element) = collector.OfClass(GetType(FamilySymbol)).OfCategory(BuiltInCategory.OST_Doors).ToElements()
    Dim symbolItor As IEnumerator(Of Element) = collection.GetEnumerator()

    Dim x As Double = 0, y As Double = 0, z As Double = 0
    While symbolItor.MoveNext()
        Dim symbol As FamilySymbol = TryCast(symbolItor.Current, FamilySymbol)
        Dim location As New XYZ(x, y, z)
        Dim instance As FamilyInstance = document.Create.NewFamilyInstance(location, symbol, wall, level, StructuralType.NonStructural)
        x += 10
        y += 10
        z += 1.5
    End While
End Sub

Exceptions

ExceptionCondition
Autodesk.Revit.Exceptions..::..ArgumentExceptionThrown if the family symbol does not exist in the given document.
Autodesk.Revit.Exceptions..::..ArgumentExceptionThrown if the host does not exist in the given document.
Autodesk.Revit.Exceptions..::..ArgumentExceptionThrown if the level does not exist in the given document.
Autodesk.Revit.Exceptions..::..ArgumentExceptionThrown if The symbol is not active.

See Also