AsyncOperationManager.CreateOperation Method
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Returns an AsyncOperation for tracking the duration of a particular asynchronous operation.
Namespace: System.ComponentModel
Assembly: System (in System.dll)
Syntax
'Declaration
Public Shared Function CreateOperation ( _
userSuppliedState As Object _
) As AsyncOperation
public static AsyncOperation CreateOperation(
Object userSuppliedState
)
Parameters
- userSuppliedState
Type: System.Object
An object that is used to associate a piece of client state, such as a task ID, with a particular asynchronous operation.
Return Value
Type: System.ComponentModel.AsyncOperation
An AsyncOperation that you can use to track the duration of an asynchronous method invocation.
Remarks
The CreateOperation method returns an System.ComponentModel.AsyncOperation that you can use to track the duration of a particular asynchronous operation and to alert the application model when the operation completes. You can also use it to post progress updates and incremental results without ending the operation. The System.ComponentModel.AsyncOperation will correctly marshal these calls to the appropriate thread or context for the application model.
If you implement a class that supports the event-based asynchronous pattern, your class should call CreateOperation every time that your MethodNameAsync method is called. The client application that makes calls to the method can use the userSuppliedState parameter to uniquely identify each invocation, so as to distinguish events raised during the execution of the asynchronous operation.
.gif "Caution note") Caution: |
|---|
Client code must provide a unique value for the userSuppliedState parameter. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and throw an System.ArgumentException if one is detected. |
Your code should track every System.ComponentModel.AsyncOperation returned by CreateOperation and use the object in the corresponding underlying asynchronous operation to post updates and end the operation. This tracking can be as simple as passing the System.ComponentModel.AsyncOperation as a parameter among delegates. In more sophisticated designs, your class can maintain a collection of System.ComponentModel.AsyncOperation objects, adding objects when tasks are started and removing them when tasks are completed or canceled. This approach enables you to check for unique userSuppliedState parameter values, and is the method that you should use when you work with classes that support multiple concurrent invocations.
For more information about how to implement asynchronous classes, see Implementing the Event-based Asynchronous Pattern in the .NET Framework documentation.
Examples
The following code example demonstrates how to use the CreateOperation method to create an System.ComponentModel.AsyncOperation for tracking the duration of asynchronous operations. This code example is part of a larger example provided for the AsyncOperationManager class.
' Start GetPersons as an asynchronous process.
Public Sub GetPersonsAsync(ByVal itemsCount As Integer, _
ByVal name As String, _
ByVal taskId As Object)
Dim asyncOp As AsyncOperation
' First make sure this is not an attempt to start the
' same thread twice. Multiple threads will access the
' taskID Dictionary, so it must be locked to serialize
' access.
SyncLock Me
If taskIDs.ContainsKey(taskId) Then
Throw New ArgumentException _
("Task ID already exists", "taskID")
End If
' Create a new AsyncOperation object
' and put it in the taskID Dictionary.
asyncOp = AsyncOperationManager.CreateOperation(taskId)
taskIDs(taskId) = asyncOp
End SyncLock
' Start the asynchronous process.
Dim myThread As New Thread(AddressOf StartThread)
myThread.Start(New ThreadStartParms With _
{.ItemsCount = itemsCount, .Name = name, .AsyncOp = asyncOp})
End Sub
Private Sub StartThread(ByVal parms As ThreadStartParms)
GetPersons(parms.ItemsCount, parms.Name, parms.AsyncOp)
End Sub
// Start GetPersons as an asynchronous process.
public void GetPersonsAsync
(int itemsCount, string name, object taskId)
{
AsyncOperation asyncOp;
// First make sure this is not an attempt to start the
// same thread twice. Multiple threads will access the
// taskID Dictionary, so it must be locked to serialize
// access.
lock (this)
{
if (taskIDs.ContainsKey(taskId))
{
throw new ArgumentException
("Task ID already exists", "taskID");
}
// Create a new AsyncOperation object
// and put it in the taskID Dictionary.
asyncOp =
AsyncOperationManager.CreateOperation(taskId);
taskIDs[taskId] = asyncOp;
}
// Start the asynchronous process.
// The following line is the least amount of code to do
// this. It uses a lambda expression. Following it is
// commented code showing an alternative method.
new Thread(() =>
{ GetPersons(itemsCount, name, asyncOp); }).Start();
// The alternative is to include two lines here and
// define separately the method that they reference and
// a class you can use to pass parameters to Thread.Start:
// Thread myThread =
// new Thread(new ThreadStart(StartThread));
// myThread.Start(new ThreadStartParms
// {.ItemsCount=itemsCount,
// .Name=name,
// .AsyncOp=asyncOp });
// void StartThread()
// {
// GetPersons(itemsCount, name, asyncOp);
// }
// public class ThreadStartParms)
// {
// public int ItemsCount { get; set; }
// public string Name { get; set; }
// public AsyncOp AsyncOperation { get; set; }
// }
}
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.