RevitSdkSamples/SDK/Samples/ErrorHandling/CS/ReadMe_ErrorHandling.rtf

{\rtf1\fbidis\ansi\ansicpg1252\deff0\deflang1033\deflangfe2052\deftab420{\fonttbl{\f0\fswiss\fprq2\fcharset0 Arial;}{\f1\froman\fprq2\fcharset0 Times New Roman;}{\f2\fswiss\fprq2\fcharset0 Helvetica;}}
{\colortbl ;\red0\green0\blue255;\red0\green0\blue0;\red0\green51\blue102;}
{\info{\horzdoc}{\*\lchars (?[\'7b}{\*\fchars !),.:\'3b?D]\'7d}}
\viewkind4\uc1\pard\ltrpar\nowidctlpar\b\f0\fs20 Application:\b0  ErrorHandling\line\b Revit Platform:\b0  All\line\b Revit Version:\b0  2011.0\line\b First Released For:\b0  2011.0\line\b Programming Language:\b0  C#\line\b Skill Level:\b0  Medium\line\b Category:\b0  Basics\line\b Type:\b0  ExternalCommand, ExternalApplication\line\line\b Subject:\b0  How to use the error handling framework.\line\b Summary:\b0  \line This sample demonstrates how to create failure definition id, failure definition, failure message and how to resolve failures in failure (pro)processing steps\f1 .\par
\f0\par
\lang1036\b Classes:\b0  \f1\par
\pard\ltrpar\nowidctlpar\fi360\f0 Autodesk.Revit.Document\par
Autodesk.Revit.DB.FailureDefinitionId\par
Autodesk.Revit.DB.FailureDefinition\par
Autodesk.Revit.DB.FailureMessage\par
Autodesk.Revit.DB.IFailuresPreprocessor\par
Autodesk.Revit.DB.IFailuresProcessor\par
\par
\pard\ltrpar\nowidctlpar\b Project Files:\b0\i  \cf1\i0\f1\par
\pard\ltrpar\nowidctlpar\tx720\cf0\lang1033\f0 Command.cs\par
\pard\ltrpar\nowidctlpar\li420\tx720 It contains 3 classes.\par
\pard\ltrpar\nowidctlpar\fi-360\li780\tx720 -\tab Command which implements interface IExternalCommand and IExternalApplication. This is the entry of this external command and external application.\par
\pard\ltrpar\nowidctlpar\fi-360\li780 -\tab FailurePreproccessor which implements interface IFailuresPreprocessor.\par
-\tab FailuresProcessor which implements interface \lang1036 IFailuresProcessor.\lang1033\par
\pard\ltrpar\nowidctlpar\par
\b Description:\b0  \f1\par
\f0 Functionalities:\par
\pard\ltrpar\nowidctlpar\fi-360\li780\tx780 -\tab Shows how to create failure definition ids and failure definitions with different severities and different resolution types.\par
\pard\ltrpar\nowidctlpar\fi-360\li780 -\tab Shows how to create failure messages and post them.\par
-\tab Shows how to solve failures during \lang1036 failure preprocessor.\lang1033\par
-\tab Shows how to solve failures in failure processing event.\par
-\tab Shows how to solve failures during failure processor.\par
\pard\ltrpar\nowidctlpar\f1\par
\f0 Implements:\f1\par
\pard\ltrpar\nowidctlpar\fi-360\li780\tx780\f0 -\tab Failure definition id should be created with a guid.\par
\pard\ltrpar\nowidctlpar\fi-360\li780 -\tab Failure definition should be created with a failure definition id and the severity.\par
-\tab Failure message should be created with a failure definition id.\par
-\tab To solve a failure in \lang1036 failure preprocessor, a FailureHandlingOptions should be created inside the transaction and an instance of IFailuresPreprocessor should be set to the FailureHandlingOptions.\lang1033\par
-\tab To solve a failure in failure processing event, the Application.FailuresProcessing event should be subscribed. \par
-\tab To solve a failure in failure processor, an instance of \lang1036 IFailuresProcessor should be registered via the static method Application.RegisterFailuresProcessor.\lang1033\par
\pard\ltrpar\nowidctlpar\kerning2\fs21\par
\kerning0\fs20 Notes:\par
\pard\ltrpar\sb150\sa150\sl260\slmult0\cf2\f2 Each cycle of failures processing includes 3 steps:\par
\pard\ltrpar\fi-360\li780\sl260\slmult0\f0 -\tab\f2 preprocessing of failures (\cf3\ul FailuresPreprocessor\cf2\ulnone )\par
\pard\ltrpar\li780\sl260\slmult0 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 \i before\i0  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.\par
\pard\ltrpar\fi-360\li780\sl260\slmult0\f0 -\tab\f2 broadcasting of failures processing event (\cf3\ul FailuresProcessing event\cf2\ulnone )\par
\pard\ltrpar\li780\sl260\slmult0 FailuresProcessing event is raised after FailuresPreprocessor (if any) has finished. It can have arbitrary number of handlers, and \i all of them\i0  will be invoked.\par
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:\par
-  Only Continue, ProceedWithRollback or ProceedWithCommit can be set\par
-  If result is set to ProceedWithCommit, setting of Continue has no effect\par
-  If result is set to ProceedWithRollback, setting of a different result has no effect\par
\pard\ltrpar\fi-360\li780\sl260\slmult0\f0 -\tab\f2 final processing (\cf3\ul FailuresProcessor\cf2\ulnone )\par
\pard\ltrpar\li780\sl260\slmult0 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.\par
\pard\ltrpar\nowidctlpar\cf0\f0\par
\kerning2\fs21\par
\pard\ltrpar\nowidctlpar\fi-360\li360\kerning0\fs20\par
}