Article
11/18/2011

AsyncCompletedEventArgs.Cancelled Property

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

Gets a value that indicates whether an asynchronous operation has been canceled.

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

Syntax

'Declaration
Public ReadOnly Property Cancelled As Boolean

public bool Cancelled { get; }

Property Value

Type: System.Boolean
true if the asynchronous operation has been canceled; otherwise, false. The default is false.

Remarks

When the Cancelled property is true, the asynchronous operation was interrupted.

The client application's event-handler delegate should check the Cancelled property before accessing any properties in a class derived from AsyncCompletedEventArgs; otherwise, the property will raise an InvalidOperationException if the asynchronous operation was interrupted.

Notes to Inheritors

If you provide read-only properties in a derived class, make sure that you call the RaiseExceptionIfNecessary method. 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 the using the Cancelled property to inform a client that an asynchronous operation was canceled. The property is not referenced by name in this example, but the value for it is passed in to the AsyncCompletedEventArgs constructor. This code example is part of a larger example provided for the System.ComponentModel.AsyncOperationManager class.

' The worker process for data retrieval. Simulates a 
' time-consuming operation by using Thread.Sleep. 
Public Sub GetPersons(ByVal itemsCount As Integer, _
                      ByVal Name As String, _
                      ByVal asyncOperation As AsyncOperation)

    Dim canceled As Boolean = False
    Dim exception As Exception = Nothing

    Dim personList As New List(Of Person)()

    Dim i As Integer = 1
    While i <= itemsCount OrElse itemsCount = 0
        Dim currentName As String = Name + CStr(i)
        personList.Add(New Person() With { _
                .Name = currentName, _
                .Age = i, _
                .Birthday = DateTime.Today.AddYears(-i), _
                .Available = (i Mod 2 = 0) _
            })

        ' Delay 1 second for each person. 
        Thread.Sleep(1000)

        ' Report progress by using AsyncOperation to raise 
        ' the ProgressChanged event. Pass in itemsCount of 
        ' zero to see effect of catching an exception. 
        Dim percentComplete As Integer
        Try
            percentComplete = Convert.ToInt32(i * 100 / itemsCount)
        Catch ex As Exception
            exception = ex
            Exit While
        End Try

        Dim progressChangedEventArgs As _
            New GetPersonsProgressChangedEventArgs _
                (currentName, _
                 percentComplete, _
                 asyncOperation.UserSuppliedState)

        asyncOperation.Post _
            (AsyncOpProgressReportHandler, progressChangedEventArgs)

        If GetPersonsCheckForCancellation _
            (asyncOperation.UserSuppliedState) Then
            canceled = True
            Exit While
        End If

        i += 1
    End While

    ' Report completion by raising the Completed event. 
    Dim completedEventArgs As _
        New GetPersonsCompletedEventArgs _
            (personList, _
             exception, _
             canceled, _
             asyncOperation.UserSuppliedState)

    asyncOperation.PostOperationCompleted _
        (AsyncOpCompletedHandler, completedEventArgs)
End Sub

// The worker process for data retrieval.  Simulates a 
// time-consuming operation by using Thread.Sleep.
public void GetPersons
    (int itemsCount, string Name, AsyncOperation asyncOperation)
{
    bool canceled = false;
    Exception exception = null;

    List<Person> personList = new List<Person>();

    for (int i = 1; i <= itemsCount || itemsCount == 0; i++)
    {
        string currentName = Name + i;
        personList.Add(new Person()
        {
            Name = currentName,
            Age = i,
            Birthday = DateTime.Today.AddYears(-i),
            Available = (i % 2 == 0)
        });
        // Delay 1 second for each person.
        Thread.Sleep(1000);

        // Report progress by using AsyncOperation to raise
        // the ProgressChanged event.
        int percentComplete = 0;
        try
        {
            percentComplete =
                Convert.ToInt32(i * 100 / itemsCount);
        }
        catch (Exception ex)
        {
            exception = ex;
            break;
        }

        GetPersonsProgressChangedEventArgs progressChangedEventArgs =
            new GetPersonsProgressChangedEventArgs(
                currentName,
                percentComplete,
                asyncOperation.UserSuppliedState);
        asyncOperation.Post(AsyncOpProgressReportHandler,
                            progressChangedEventArgs);

        if (GetPersonsCheckForCancellation
            (asyncOperation.UserSuppliedState))
        {
            canceled = true;
            break;
        }
    }

    // Report completion by raising the Completed event.
    GetPersonsCompletedEventArgs completedEventArgs =
        new GetPersonsCompletedEventArgs(
            personList,
            exception,
            canceled,
            asyncOperation.UserSuppliedState);

    asyncOperation.PostOperationCompleted
        (AsyncOpCompletedHandler, completedEventArgs);
}

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.

Share via