M

ItemFactoryBase.NewFamilyInstance

Description:
Inserts a new instance of a family onto a face referenced by the input Reference instance, using a location, reference direction, and a type/symbol.

Remarks:
Use this method to insert one family instance on a face of another element, using a point on the face and a vector 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 instances fails to be created an exception may be thrown.

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.

Overloads (10):

NewFamilyInstance(Face,Line,FamilySymbol)

NewFamilyInstance(Face,XYZ,XYZ,FamilySymbol)

NewFamilyInstance(Line,FamilySymbol,View)

NewFamilyInstance(Reference,Line,FamilySymbol)

NewFamilyInstance(Reference,XYZ,XYZ,FamilySymbol)

NewFamilyInstance(XYZ,FamilySymbol,Element,StructuralType)

NewFamilyInstance(XYZ,FamilySymbol,Level,StructuralType)

NewFamilyInstance(XYZ,FamilySymbol,StructuralType)

NewFamilyInstance(XYZ,FamilySymbol,View)

NewFamilyInstance(XYZ,FamilySymbol,XYZ,Element,StructuralType)

public FamilyInstance NewFamilyInstance(
	Reference reference,
	XYZ location,
	XYZ referenceDirection,
	FamilySymbol symbol
)

Public Function NewFamilyInstance ( _
	reference As Reference, _
	location As XYZ, _
	referenceDirection As XYZ, _
	symbol As FamilySymbol _
) As FamilyInstance

public:
FamilyInstance^ NewFamilyInstance(
	Reference^ reference, 
	XYZ^ location, 
	XYZ^ referenceDirection, 
	FamilySymbol^ symbol
)

Autodesk.Revit.DB.Reference

reference

A reference to a face.
Autodesk.Revit.DB.XYZ

location

Point on the face where the instance is to be placed.
Autodesk.Revit.DB.XYZ

referenceDirection

A vector that defines the direction of the family instance. Note that this direction defines the rotation of the instance on the face, and thus cannot be parallel to the face normal.
Autodesk.Revit.DB.FamilySymbol

symbol

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.

Return Value nullNothingnullptr An instance of the new object if creation was successful, otherwise null Nothing nullptr a null reference ( Nothing in Visual Basic) .

void CreateNurseCallDomeOnWall(Autodesk.Revit.DB.Document document, Wall wall)
{
    FilteredElementCollector collector = new FilteredElementCollector(document);
    collector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_NurseCallDevices);

    FamilySymbol symbol = collector.FirstElement() as FamilySymbol;

    // Get interior face of wall
    IList<Reference> sideFaces = HostObjectUtils.GetSideFaces(wall, ShellLayerType.Interior);
    Reference interiorFaceRef = sideFaces[0];

    XYZ location = new XYZ(4, 2, 8);
    XYZ refDir = new XYZ(0, 0, 1);

    FamilyInstance instance = document.Create.NewFamilyInstance(interiorFaceRef, location, refDir, symbol);
}

Private Sub CreateNurseCallDomeOnWall(document As Autodesk.Revit.DB.Document, wall As Wall)
    Dim collector As New FilteredElementCollector(document)
    collector.OfClass(GetType(FamilySymbol)).OfCategory(BuiltInCategory.OST_NurseCallDevices)

    Dim symbol As FamilySymbol = TryCast(collector.FirstElement(), FamilySymbol)

    ' Get interior face of wall
    Dim sideFaces As IList(Of Reference) = HostObjectUtils.GetSideFaces(wall, ShellLayerType.Interior)
    Dim interiorFaceRef As Reference = sideFaces(0)

    Dim location As New XYZ(4, 2, 8)
    Dim refDir As New XYZ(0, 0, 1)

    Dim instance As FamilyInstance = document.Create.NewFamilyInstance(interiorFaceRef, location, refDir, symbol)
End Sub

Autodesk.Revit.Exceptions.ArgumentNullException

Thrown when a non-optional argument was null.
Autodesk.Revit.Exceptions.ArgumentException

Thrown when the function cannot get the face from the reference, or, when the Family cannot be placed as line-based on an input face reference, because its FamilyPlacementType is not WorkPlaneBased
Autodesk.Revit.Exceptions.ArgumentsInconsistentException

Thrown when reference direction is parallel to face normal at insertion point.
Autodesk.Revit.Exceptions.InvalidOperationException

Thrown when Revit is unable to place the family instance.
Autodesk.Revit.Exceptions.ArgumentException

Thrown if The symbol is not active.