Building Coder（Revit 二次開發） - 失敗處理API（上）

Building Coder 連結：Failure API Take Two

Revit 二次開發論壇連結：翻譯 Building Coder - 失敗處理API（上）

我們之前在 失敗處理第一季中讨論過 Revit 2011 中最新的失敗處理API和SDK例程“ErrorHandling”。Revit API 最廣泛的用途之一就是屏蔽不需要的警告和錯誤。Revit 之前的版本中程式已經可以簡便地使用 DialogShowing 事件來實作了。但正如我另外兩篇博文 editing elements inside groups和 suppressing an unwanted dialogue中展現的那樣，失敗處理API提供更加強大和完備的解決方案。

下面是Joe Ye（譯者注：傳說中的葉雄進老師）整理的失敗處理API的使用方法：

在模型中出現錯誤時，Revit 通常是通過報告警告或者錯誤資訊的形式來提示使用者的。例如：當兩面牆部分重疊時，Revit彈出如下警告消息：

Revit 2011 公開失敗處理API用于釋出和處理這些類型的失敗。失敗釋出API能夠被用于定義和注冊新的自定義失敗。自定義失敗可以在插件中被自由地釋出。在針對模型的操作結束時，失敗釋出API可以删除或者解決 Revit 失敗。程式可以在失敗處理過程中針對模型進行進一步的操作。如果失敗處理API已經處理了失敗，使用者可能就察覺不到警告或者錯誤了。因為它們已經被你的程式處理了。

釋出錯誤

錯誤釋出API絕對屬于易用型。我們可以首先在外部應用程式的OnStartup方法中注冊新的錯誤定義，通常還需要設定其嚴重程度和解決方案類型。下面是注冊一個新警告的例子。自定義的錯誤被注冊之後，就可以在程式中自由地使用了。

public Result OnStartup( UIControlledApplication a )
{
  // Create failure definition Ids
 
  m_idWarning = new FailureDefinitionId( new Guid(
    "0C3F66B5-3E26-4d24-A228-7A8358C76D39" ) );    // VS工具菜單裡有GUID生成器
 
  // Create failure definition and add resolution
 
  m_fdWarning
    = FailureDefinition.CreateFailureDefinition(
      m_idWarning,
      FailureSeverity.Warning, // 嚴重程度
      "I am the warning." );
 
  m_fdWarning.AddResolutionType(
    FailureResolutionType.MoveElements,
    "MoveElements", typeof( DeleteElements ) );    // 解決方案類型
 
  return Result.Succeeded;
}
           

Document.PostFailure()方法用于告訴文檔對象目前有一個錯誤。

transaction.Start();    // 需要包含在一個事務中
FailureMessage fm = new FailureMessage( m_idWarning );
m_doc.PostFailure( fm );
transaction.Commit();
           

錯誤會在送出事務時被驗證，解決錯誤（如果需要的話）也是在事務被送出時進行。

未完待續……