Click to Rate and Give Feedback
MSDN
MSDN Library
.NET Development
Previous Versions
.NET Framework 2.0
 CancelAsync Method

  Switch on low bandwidth view
This page is specific to
Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:
BackgroundWorker.CancelAsync Method
Requests cancellation of a pending background operation.

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

Visual Basic (Declaration)
Public Sub CancelAsync
Visual Basic (Usage)
Dim instance As BackgroundWorker

instance.CancelAsync
C#
public void CancelAsync ()
C++
public:
void CancelAsync ()
J#
public void CancelAsync ()
JScript
public function CancelAsync ()
XAML
Not applicable.
Exception typeCondition

InvalidOperationException

WorkerSupportsCancellation is false.

CancelAsync submits a request to terminate the pending background operation and sets the CancellationPending property to true.

When you call CancelAsync, your worker method has an opportunity to stop its execution and exit. The worker code should periodically check the CancellationPending property to see if it has been set to true.

Caution noteCaution:

Be aware that your code in the DoWork event handler may finish its work as a cancellation request is being made, and your polling loop may miss CancellationPending being set to true. In this case, the Cancelled flag of System.ComponentModel.RunWorkerCompletedEventArgs in your RunWorkerCompleted event handler will not be set to true, even though a cancellation request was made. This situation is called a race condition and is a common concern in multithreaded programming. For more information about multithreading design issues, see Managed Threading Best Practices.

The following code example demonstrates the use of the CancelAsync method to cancel an asynchronous ("background") operation. This code example is part of a larger example provided for the BackgroundWorker class.

Visual Basic
Private Sub cancelAsyncButton_Click( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
Handles cancelAsyncButton.Click
    
    ' Cancel the asynchronous operation.
    Me.backgroundWorker1.CancelAsync()

    ' Disable the Cancel button.
    cancelAsyncButton.Enabled = False
    
End Sub 'cancelAsyncButton_Click
C#
private void cancelAsyncButton_Click(System.Object sender, 
    System.EventArgs e)
{   
    // Cancel the asynchronous operation.
    this.backgroundWorker1.CancelAsync();

    // Disable the Cancel button.
    cancelAsyncButton.Enabled = false;
}
C++
void cancelAsyncButton_Click( System::Object^ /*sender*/, System::EventArgs^ /*e*/ )
{  
   // Cancel the asynchronous operation.
   this->backgroundWorker1->CancelAsync();
   
   // Disable the Cancel button.
   cancelAsyncButton->Enabled = false;
}
J#
private void cancelAsyncButton_Click(Object sender, System.EventArgs e)
{   
    // Cancel the asynchronous operation.
    this.backgroundWorker1.CancelAsync();

    // Disable the Cancel button.
    cancelAsyncButton.set_Enabled(false);
}

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0
Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Don't forget to set 'e.Cancel = True' when you check the CancellationPending flag!      Andrew_F   |   Edit   |   Show History
As the Remarks state, this trips the CancellationPending flag which you need to check for periodically inside your BackgroundWorker.DoWork() method.

Buried in the code example (http://msdn.microsoft.com/en-us/library/system.componentmodel.backgroundworker(VS.80).aspx), are the lines:

If worker.CancellationPending Then
e.Cancel = True
Else

I thought I'd point it out as I was checking for the CancellationPending flag and exiting my DoWork() method when it was True, then wondered why the e.Cancelled flag wasn't set when I checked it in the RunWorkerCompleted() event..

I hope this saves you some time :o)



Tags What's this?: Add a tag
Flag as ContentBug
Processing
© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker