Building Coder（Revit 二次开发） - NewFamilyInstance() 重载版本的选择

今天开始恢复中断了三个月的 Building Coder 翻译任务。认真回顾了中断之前的工作和 Jeremy 的帖子，决定从他老人家 2011 年的文章开始，争取在半年内赶上他的更新进度。

原文链接： NewFamilyInstance Overloads

如大家所知， NewFamilyInstance() 方法是 Revit API 中用于创建族实例的 API，而且它有多个重载的版本。我们经常遇到的问题是：针对不同特征的族，究竟应该使用哪个重载版本？下面是一个针对这个问题的提问，我想借回答它的机会把我们之前相关的讨论总结一下。

提问：
我有一个场景需要插入一组族实例，代码如下：

FamilyInstance instance = documentProject.Create.NewFamilyInstance(location, symbol, StructuralType.NonStructural);

这句代码在操作只需要一个定位点的族时工作得很好，但是在族需要宿主或者两个定位点时就不工作了。我应该如何确认使用何种NewFamilyInstance方法呢？

回答：
你的现象和理解是正确的。NewFamilyInstance方法有多个重载版本。你必须根据需要创建的族的特征选择正确的版本。这个问题在开发者指南 12.3.5 '创建族实例' 中有说明。另外我的博客里也多次讨论过。其中这篇博文中有一个很实用的方法“TestAllOverloads”来测试所有的重载版本以确认合适的那个。

void TestAllOverloads(
  Document doc,
  XYZ startPoint,
  XYZ endPoint,
  FamilySymbol familySymbol )
{
  StructuralType stNon = StructuralType.NonStructural;
  StructuralType stBeam = StructuralType.Beam;
 
  Autodesk.Revit.Creation.Document cd = doc.Create;
 
  View view = doc.ActiveView;
  SketchPlane sk = view.SketchPlane;
  Level level = view.Level;
 
  // 根据用户指定的两点创建“线”
 
  Curve curve = doc.Application.Create.NewLineBound( startPoint, endPoint );
 
  // 根据用户指定的两点得到“创建方向”
 
  XYZ dirVec = endPoint - startPoint;
 
  bool done = false;
  int index = 1;
  while( !done )
  {
    FamilyInstance instance = null;
 
    // 尝试不同的 NewFamilyInstance() 重载版本
 
    try
    {
      switch( index )
      {
        // public FamilyInstance NewFamilyInstance(
        //   XYZ location, FamilySymbol symbol,
        //   StructuralType structuralType );
 
        case 1:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, stNon );
          break;
 
        case 2:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, stBeam );
          break;
 
        // public FamilyInstance NewFamilyInstance(
        //   XYZ origin, FamilySymbol symbol,
        //   View specView );
 
        case 3:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, null );
          break;
 
        case 4:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, view );
          break;
 
        // public FamilyInstance NewFamilyInstance(
        //   XYZ location, FamilySymbol symbol,
        //   Element host, StructuralType structuralType );
 
        case 5:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, sk, stNon );
          break;
 
        case 6:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, sk, stBeam );
          break;
 
        // public FamilyInstance NewFamilyInstance(
        //   XYZ location, FamilySymbol symbol,
        //   XYZ referenceDirection, Element host,
        //   StructuralType structuralType );
 
        case 7:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, dirVec, sk, stNon );
          break;
 
        case 8:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, dirVec, sk, stBeam );
          break;
 
        // public FamilyInstance NewFamilyInstance(
        //   Curve curve, FamilySymbol symbol,
        //   Level level, StructuralType structuralType );
 
        case 9:
          instance = cd.NewFamilyInstance( curve, familySymbol, null, stNon );
          break;
 
        case 10:
          instance = cd.NewFamilyInstance( curve, familySymbol, null, stBeam );
          break;
 
        case 11:
          instance = cd.NewFamilyInstance( curve, familySymbol, level, stNon );
          break;
 
        case 12:
          instance = cd.NewFamilyInstance( curve, familySymbol, level, stBeam );
          break;
 
        // public FamilyInstance NewFamilyInstance(
        //   XYZ location, FamilySymbol symbol,
        //   Level level, StructuralType structuralType );
 
        case 13:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, null, stNon );
          break;
 
        case 14:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, null, stBeam );
          break;
 
        case 15:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, level, stNon );
          break;
 
        case 16:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, level, stBeam );
          break;
 
        // public FamilyInstance NewFamilyInstance(
        //   XYZ location, FamilySymbol symbol,
        //   Element host, Level level,
        //   StructuralType structuralType );
 
        case 17:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, null, stNon );
          break;
 
        case 18:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, null, stBeam );
          break;
 
        case 19:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, sk, stNon );
          break;
 
        case 20:
          instance = cd.NewFamilyInstance( startPoint, familySymbol, sk, stBeam );
          break;
 
        default:
          done = true;
          break;
      }
    }
    catch
    { }
 
    // 如果族实例被创建，标记使用的重载版本编号。
 
    if( null != instance )
    {
      Parameter param = instance.get_Parameter( "InstanceIndex" );
      if( null != param )
      {
        param.Set( index );
      }
    }
    index++;
  }
}