System
2.0.0.0
4.0.0.0
System.ComponentModel.Component
System.ComponentModel.DefaultEvent("DoWork")
The class allows you to run an operation on a separate, dedicated thread. Time-consuming operations like downloads and database transactions can cause your user interface (UI) to seem as though it has stopped responding while they are running. When you want a responsive UI and you are faced with long delays associated with such operations, the class provides a convenient solution.
To execute a time-consuming operation in the background, create a and listen for events that report the progress of your operation and signal when your operation is finished. You can create the programmatically or you can drag it onto your form from the Components tab of the Toolbox. If you create the in the Windows Forms Designer, it will appear in the Component Tray, and its properties will be displayed in the Properties window.
To set up for a background operation, add an event handler for the event. Call your time-consuming operation in this event handler. To start the operation, call . To receive notifications of progress updates, handle the event. To receive a notification when the operation is completed, handle the event.
You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the and events.
events are not marshaled across boundaries. Do not use a component to perform multithreaded operations in more than one .
If your background operation requires a parameter, call with your parameter. Inside the event handler, you can extract the parameter from the property.
For more information about , see How to: Run an Operation in the Background.
Executes an operation on a separate thread.
Constructor
2.0.0.0
4.0.0.0
This constructor initializes a .
Initializes a new instance of the class.
Method
2.0.0.0
4.0.0.0
System.Void
submits a request to terminate the pending background operation and sets the property to true.
When you call , your worker method has an opportunity to stop its execution and exit. The worker code should periodically check the property to see if it has been set to true.
Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to true. In this case, the flag of in your 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.
Requests cancellation of a pending background operation.
Property
2.0.0.0
4.0.0.0
System.ComponentModel.Browsable(false)
System.Boolean
To be added.
If is true, then the method has been called on the .
This property is meant for use by the worker thread, which should periodically check and abort the background operation when it is set to true.
Gets a value indicating whether the application has requested cancellation of a background operation.
Event
2.0.0.0
4.0.0.0
System.ComponentModel.DoWorkEventHandler
This event is raised when you call the method. This is where you start the operation that performs the potentially time-consuming work.
Your code in the event handler should periodically check the property value and abort the operation if it is true. When this occurs, you can set the flag of to true, and the flag of in your event handler will be set to true.
Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to true. In this case, the flag of in your 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.
If your operation produces a result, you can assign the result to the property. This will be available to the event handler in the property.
If the operation raises an exception that your code does not handle, the catches the exception and passes it into the event handler, where it is exposed as the property of . If you are running under the Visual Studio debugger, the debugger will break at the point in the event handler where the unhandled exception was raised. If you have more than one , you should not reference any of them directly, as this would couple your event handler to a specific instance of . Instead, you should access your by casting the parameter in your event handler.
You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the events.
For more information about handling events, see Consuming Events.
Occurs when is called.
Property
2.0.0.0
4.0.0.0
System.ComponentModel.Browsable(false)
System.Boolean
To be added.
The starts an asynchronous operation when you call .
Gets a value indicating whether the is running an asynchronous operation.
Method
2.0.0.0
4.0.0.0
System.Void
To be added.
Raises the event.
An that contains the event data.
Method
2.0.0.0
4.0.0.0
System.Void
Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.
The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
Raises the event.
An that contains the event data.
Method
2.0.0.0
4.0.0.0
System.Void
Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.
The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
Raises the event.
An that contains the event data.
Event
2.0.0.0
4.0.0.0
System.ComponentModel.ProgressChangedEventHandler
This event is raised when you call the method.
For more information about handling events, see Consuming Events.
Occurs when is called.
Method
2.0.0.0
4.0.0.0
System.Void
If you need the background operation to report on its progress, you can call the method to raise the event. The property value must be true, or will throw an .
It is up to you to implement a meaningful way of measuring your background operation's progress as a percentage of the total task completed.
The call to the method is asynchronous and returns immediately. The event handler executes on the thread that created the .
Raises the event.
The percentage, from 0 to 100, of the background operation that is complete.
Method
2.0.0.0
4.0.0.0
System.Void
If you need the background operation to report on its progress, you can call the method to raise the event. The property value must true, or will throw an .
It is up to you to implement a meaningful way of measuring your background operation's progress as a percentage of the total task completed.
Raises the event.
The percentage, from 0 to 100, of the background operation that is complete.
The state object passed to .
Method
2.0.0.0
4.0.0.0
System.Void
The method submits a request to start the operation running asynchronously. When the request is serviced, the event is raised, which in turn starts execution of your background operation.
If the background operation is already running, calling again will raise an .
Starts execution of a background operation.
Method
2.0.0.0
4.0.0.0
System.Void
The method submits a request to start the operation running asynchronously. When the request is serviced, the event is raised, which in turn starts execution of your background operation.
If your operation requires a parameter, you can provide it as the parameter to .
If the background operation is already running, calling again will raise an .
Starts execution of a background operation.
A parameter for use by the background operation to be executed in the event handler.
Event
2.0.0.0
4.0.0.0
System.ComponentModel.RunWorkerCompletedEventHandler
This event is raised when the event handler returns.
If the operation completes successfully and its result is assigned in the event handler, you can access the result through the property.
The property of indicates that an exception was thrown by the operation.
The property of indicates whether a cancellation request was processed by the background operation. If your code in the event handler detects a cancellation request by checking the flag and setting the flag of to true, the flag of also will be set to true.
Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to true. In this case, the flag of in your 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.
Your event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception.
Occurs when the background operation has completed, has been canceled, or has raised an exception.
Property
2.0.0.0
4.0.0.0
System.ComponentModel.DefaultValue(false)
System.Boolean
To be added.
Set the property to true if you want the to support progress updates. When this property is true, user code can call the method to raise the event.
Gets or sets a value indicating whether the can report progress updates.
Property
2.0.0.0
4.0.0.0
System.ComponentModel.DefaultValue(false)
System.Boolean
To be added.
Set the property to true if you want the to support cancellation. When this property is true, you can call the method to interrupt a background operation.
Gets or sets a value indicating whether the supports asynchronous cancellation.