Posts a failure to be displayed to the user at the end of transaction.

Namespace: Autodesk.Revit.DB
Assembly: RevitAPI (in RevitAPI.dll) Version: 21.0.0.0 (21.1.1.109)
Since:  2011

Syntax

C#
public FailureMessageKey PostFailure(
	FailureMessage failure
)
Visual Basic
Public Function PostFailure ( _
	failure As FailureMessage _
) As FailureMessageKey
Visual C++
public:
FailureMessageKey^ PostFailure(
	FailureMessage^ failure
)

Parameters

failure
Type: Autodesk.Revit.DB..::..FailureMessage
The failure to be posted.

Return Value

A unique key that identifies posted failure message in a document. If exactly the same error is posted more than once, and not removed between the postings, returned key will be the same every time.

Remarks

If code inside transaction detects a problem that needs to be communicated to the user, it should report these conditions via this method. Failures will be validated and possibly resolved at the end of transaction. Warnings posted via this method will not be stored in the document after they are resolved. A unique key returned by postFailure can be stored for the lifetime of transaction and used to remove failure message if it is no longer relevant.

Examples

CopyC#
// Execute function for an Updater triggered when new FamilyInstances are added
public void Execute(UpdaterData data)
{
    Document doc = data.GetDocument();
    Autodesk.Revit.ApplicationServices.Application app = doc.Application;
    foreach (ElementId id in data.GetModifiedElementIds())
    {
        FamilyInstance fi = doc.GetElement(id) as FamilyInstance;
        if (fi.StructuralType == StructuralType.Beam)
        {
            AnalyticalModel analyticalModel = fi.GetAnalyticalModel();
            if (analyticalModel.IsSingleCurve() == true)
            {
                Curve beamCurve = analyticalModel.GetCurve();
                // enforce beam length minimum of 12 inches
                if (beamCurve.Length < 12.0)
                {
                    FailureMessage failMessage = 
                        new FailureMessage(BuiltInFailures.CurveFailures.TooShort);
                    failMessage.SetFailingElement(id);
                    doc.PostFailure(failMessage);
                }
            }
        }
    }
}
CopyVB.NET
' Execute function for an Updater triggered when new FamilyInstances are added
Public Sub Execute(data As UpdaterData) Implements IUpdater.Execute
    Dim doc As Document = data.GetDocument()
    Dim app As Autodesk.Revit.ApplicationServices.Application = doc.Application
    For Each id As ElementId In data.GetModifiedElementIds()
        Dim fi As FamilyInstance = TryCast(doc.GetElement(id), FamilyInstance)
        If fi.StructuralType = StructuralType.Beam Then
            Dim analyticalModel As AnalyticalModel = fi.GetAnalyticalModel()
            If analyticalModel.IsSingleCurve() = True Then
                Dim beamCurve As Curve = analyticalModel.GetCurve()
                ' enforce beam length minimum of 12 inches
                If beamCurve.Length < 12.0 Then
                    Dim failMessage As New FailureMessage(BuiltInFailures.CurveFailures.TooShort)
                    failMessage.SetFailingElement(id)
                    doc.PostFailure(failMessage)
                End If
            End If
        End If
    Next
End Sub

Exceptions

ExceptionCondition
Autodesk.Revit.Exceptions..::..ArgumentNullException A non-optional argument was NULL
Autodesk.Revit.Exceptions..::..InvalidOperationException Document must be in state of accepting posted failures and the failures must be appropriate for that current state.
Autodesk.Revit.Exceptions..::..ModificationForbiddenException The document is in failure mode: an operation has failed, and Revit requires the user to either cancel the operation or fix the problem (usually by deleting certain elements). -or- The document is being loaded, or is in the midst of another sensitive process.
Autodesk.Revit.Exceptions..::..ModificationOutsideTransactionException The document has no open transaction.

See Also