Application: ErrorHandling
Revit Platform: All
Revit Version: 2011.0
First Released For: 2011.0
Programming Language: C#
Skill Level: Medium
Category: Basics
Type: ExternalCommand, ExternalApplication

Subject: How to use the error handling framework.
Summary: 
This sample demonstrates how to create failure definition id, failure definition, failure message and how to resolve failures in failure (pro)processing steps.

Classes: 
Autodesk.Revit.Document
Autodesk.Revit.DB.FailureDefinitionId
Autodesk.Revit.DB.FailureDefinition
Autodesk.Revit.DB.FailureMessage
Autodesk.Revit.DB.IFailuresPreprocessor
Autodesk.Revit.DB.IFailuresProcessor

Project Files: 
Command.cs
It contains 3 classes.
-	Command which implements interface IExternalCommand and IExternalApplication. This is the entry of this external command and external application.
-	FailurePreproccessor which implements interface IFailuresPreprocessor.
-	FailuresProcessor which implements interface IFailuresProcessor.

Description: 
Functionalities:
-	Shows how to create failure definition ids and failure definitions with different severities and different resolution types.
-	Shows how to create failure messages and post them.
-	Shows how to solve failures during failure preprocessor.
-	Shows how to solve failures in failure processing event.
-	Shows how to solve failures during failure processor.

Implements:
-	Failure definition id should be created with a guid.
-	Failure definition should be created with a failure definition id and the severity.
-	Failure message should be created with a failure definition id.
-	To solve a failure in failure preprocessor, a FailureHandlingOptions should be created inside the transaction and an instance of IFailuresPreprocessor should be set to the FailureHandlingOptions.
-	To solve a failure in failure processing event, the Application.FailuresProcessing event should be subscribed. 
-	To solve a failure in failure processor, an instance of IFailuresProcessor should be registered via the static method Application.RegisterFailuresProcessor.

Notes:
Each cycle of failures processing includes 3 steps:
-	preprocessing of failures (FailuresPreprocessor)
FailuresPreprocessor is being set for one transaction and used only during finishing of this one transaction. It gets control first during failure resolution process. It is nearly equivalent to checking and resolving failures before finishing transaction, except that FailuresPreprocessor gets control "at the right time" when all failures guaranteed to be posted and/or all irrelevant ones get deleted, so that there are no false positives or negatives.
-	broadcasting of failures processing event (FailuresProcessing event)
FailuresProcessing event is raised after FailuresPreprocessor (if any) has finished. It can have arbitrary number of handlers, and all of them will be invoked.
Because event handlers have no way to return value, setProcessingResult() on event argument should be used to communicate status. There is a restriction on result that can be set:
-  Only Continue, ProceedWithRollback or ProceedWithCommit can be set
-  If result is set to ProceedWithCommit, setting of Continue has no effect
-  If result is set to ProceedWithRollback, setting of a different result has no effect
-	final processing (FailuresProcessor)
FailuresProcessor gets control last, after FailuresProcessing event is processed. There is only one active FailuresProcessor in Revit session. There is a default one in Revit UI - it invoked all regular Revit error dialogs. If new FailuresProcessor is set, any previously set one is completely abandoned. If FailuresProcessor is set to NULL, any transaction that has any failures is silently aborted (unless failures are resolved by first two steps of failures processing). FailuresProcessor is allowd to return WaitForUserInput which leaves transaction pending. It is expected that in this case FailuresProcessor leaves some UI on the screen that will eventually commit or rollback pending transaction - otherwise pending state will last forever, killing user's ability to work with the document.