Code Samples

Review the following code samples for more information about working with Family Instances. Please note that in the NewFamilyInstance() method, a StructuralType argument is required to specify the type of the family instance to be created. Here are some examples:

Table 34: The value of StructuralType argument in the NewFamilyInstance() method

Type of Family Instance	Value of StructuralType
Doors, tables, etc.	NonStructural
Beams	Beam
Braces	Brace
Columns	Column
Footings	Footing

Create Tables

The following function demonstrates how to load a family of Tables into a Revit project and create instances from all symbols in this family.

The LoadFamily() method returns false if the specified family was previously loaded. Therefore, in the following case, do not load the family, Table-Dining Round w Chairs.rfa, before this function is called. In this example, the tables are created at Level 1 by default.

Code Region 12-3: Creating tables

String fileName = @"C:\Documents and Settings\All Users\Application Data\Autodesk\RST 2011\Imperial Library\Furniture\Table-Dining Round w Chairs.rfa";
 
// try to load family
Family family = null;
if (!document.LoadFamily(fileName, out family))
{
        throw new Exception("Unable to load " + fileName);
}
// Loop through table symbols and add a new table for each
FamilySymbolSetIterator symbolItor = family.Symbols.ForwardIterator();
double x = 0.0, y = 0.0;
while (symbolItor.MoveNext())
{
        FamilySymbol symbol = symbolItor.Current as FamilySymbol;
        XYZ location = new XYZ(x, y, 10.0);
        // Do not use the overloaded NewFamilyInstance() method that contains 
        // the Level argument, otherwise Revit cannot show the instances 
        // correctly in 3D View, for the table is not level-based component.
        FamilyInstance instance = document.Create.NewFamilyInstance(location, symbol, StructuralType.NonStructural);

        x += 10.0;
}

The result of loading the Tables family and placing one instance of each FamilySymbol:

Figure 47: Load family and create tables in the Revit project

Create a Beam

In this sample, a family symbol is loaded instead of a family, because loading a single FamilySymbol is faster than loading a Family that contains many FamilySymbols.

Code Region 12-4: Creating a beam

// get the active view's level for beam creation
Level level = document.ActiveView.Level;

// load a family symbol from file
FamilySymbol gotSymbol = null;
String fileName = @"C:\Documents and Settings\All Users\Application Data\Autodesk\RST 2011\Imperial Library\Structural\Framing\Steel\W-Wide Flange.rfa";
String name = "W10X54";

FamilyInstance instance = null;

if (document.LoadFamilySymbol(fileName, name, out gotSymbol))
{
        // look for a model line in the list of selected elements
        UIDocument uidoc = new UIDocument(document);
        ElementSet sel = uidoc.Selection.Elements;
        ModelLine modelLine = null;
        foreach (Autodesk.Revit.DB.Element elem in sel)
        {
                if (elem is ModelLine)
                {
                        modelLine = elem as ModelLine;
                        break;
                }
        }
        if (null != modelLine)
        {
                // create a new beam
                instance = document.Create.NewFamilyInstance(modelLine.GeometryCurve, gotSymbol, level, StructuralType.Beam);
        }
        else
        {
                throw new Exception("Please select a model line before invoking this command");
        }

}
else
{
        throw new Exception("Couldn't load " + fileName);
}

Create Doors

Create a long wall about 180' in length and select it before running this sample. The host object must support inserting instances; otherwise the NewFamilyInstance() method will fail. If a host element is not provided for an instance that must be created in a host, or the instance cannot be inserted into the specified host element, the method NewFamilyInstance() does nothing.

Code Region 12-5: Creating doors

void CreateDoorsInWall(Autodesk.Revit.DB.Document document, Wall wall)
{
        String fileName = @"C:\Documents and Settings\All Users\Application Data\Autodesk\RST 2011\Imperial Library\Doors\Single-Decorative 2.rfa";
 
        Family family = null;
        if (!document.LoadFamily(fileName, out family))
        {
                throw new Exception("Unable to load " + fileName);
        }

        // get the active view's level for beam creation
        Level level = document.ActiveView.Level;
        
        FamilySymbolSetIterator symbolItor = family.Symbols.ForwardIterator();
        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;
        }
}

The result of the previous code in Revit is shown in the following picture. Notice that if the specified location is not at the specified level, the NewFamilyInstance() method uses the location elevation instead of the level elevation.

Figure 48: Insert doors into a wall

Create FamilyInstances Using Reference Directions

Use reference directions to insert an item in a specific direction.

Code Region 12-6: Creating FamilyInstances using reference directions

String fileName = @"C:\Documents and Settings\All Users\Application Data\Autodesk\RST 2011\Imperial Library\Furniture\Bed-Box.rfa";
 
Autodesk.Revit.DB.Family family = null;
if (!document.LoadFamily(fileName, out family))
{
        throw new Exception("Couldn't load " + fileName);
}

FilteredElementCollector collector = new FilteredElementCollector(document);
Floor floor = collector.OfClass(typeof(Floor)).FirstElement() as Floor;
if (floor != null)
{
        FamilySymbolSetIterator symbolItor = family.Symbols.ForwardIterator();
        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++;
        }
}
else
{
        throw new Exception("Please open a model with at least one floor element before invoking this command.");
}

The result of the previous code appears in the following picture:

Figure 49: Create family instances using different reference directions