AsyncCompletedEventArgs.RaiseExceptionIfNecessary Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Raises a user-supplied exception if an asynchronous operation failed.

Namespace:  System.ComponentModel
Assembly:  System (in System.dll)

Syntax

'Declaration
Protected Sub RaiseExceptionIfNecessary
protected void RaiseExceptionIfNecessary()

Exceptions

Exception Condition
InvalidOperationException

The Cancelled property is true.

TargetInvocationException

The Error property has been set by the asynchronous operation.

Remarks

Notes to Inheritors

If you have derived your own class from the AsyncCompletedEventArgs class, your read-only properties should call the RaiseExceptionIfNecessary method before they return the property value. If the component's asynchronous worker code assigns an exception to the Error property or sets the Cancelled property to true, the property will raise an exception if a client tries to read its value. This prevents clients from accessing properties that are potentially not valid because of a failure in the asynchronous operation.

Examples

The following code example demonstrates how to use RaiseExceptionIfNecessary in derived class properties. This code example is part of a larger example provided for the System.ComponentModel.AsyncOperationManager class.

' Define a custom Completed-event arguments class allowing 
' the data gathered by GetPersons to be returned. 
Public Class GetPersonsCompletedEventArgs
    Inherits AsyncCompletedEventArgs
    Private m_dataListValue As List(Of Person)
    Public Sub New _
        (ByVal dataList As List(Of Person), _
         ByVal exception As Exception, _
         ByVal cancelled As Boolean, _
         ByVal userState As Object)

        MyBase.New(exception, cancelled, userState)
        m_dataListValue = dataList
    End Sub

    Public ReadOnly Property DataListValue() As List(Of Person)
        Get
            Me.RaiseExceptionIfNecessary()
            Return m_dataListValue
        End Get
    End Property
End Class
// Define a custom Completed-event arguments class allowing 
// the data gathered by GetPersons to be returned.
public class GetPersonsCompletedEventArgs : AsyncCompletedEventArgs
{
    private List<Person> dataListValue;
    public GetPersonsCompletedEventArgs(
        List<Person> dataList,
        Exception error,
        bool cancelled,
        object userState)
        : base(error, cancelled, userState)
    {
        dataListValue = dataList;
    }
    public List<Person> DataListValue
    {
        get
        {
            this.RaiseExceptionIfNecessary();
            return dataListValue;
        }
    }
}
Public Delegate Sub GetPersonsCompletedEventHandler _
    (ByVal sender As Object, _
     ByVal e As GetPersonsCompletedEventArgs)
public delegate void GetPersonsCompletedEventHandler
    (object sender, GetPersonsCompletedEventArgs e);

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.