• Article

AsyncOperation.Post Method

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

Invokes a delegate on the thread or context appropriate for the application model.

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

Syntax

'Declaration
Public Sub Post ( _
    d As SendOrPostCallback, _
    arg As Object _
)

public void Post(
    SendOrPostCallback d,
    Object arg
)

Parameters

  • arg
    Type: System.Object
    An argument for the delegate that is contained in the d parameter.

Exceptions

Exception Condition
InvalidOperationException

The PostOperationCompleted method has been called previously for this task.
ArgumentNullException

d is nulla null reference (Nothing in Visual Basic).

Remarks

The Post method invokes the delegate specified by the arg parameter without ending the lifetime of the asynchronous operation.

You can call the Post method as often as you like as long as the lifetime of the asynchronous operation has not been ended by a call to PostOperationCompleted. You can use the method to report progress or interim results back to clients.

The d parameter wraps the delegate you want called when you want to post an update about the status of the asynchronous task. The AsyncOperation object will make sure that your delegate is invoked on the thread or context appropriate for the application model. Your method can optionally raise an event that notifies clients of a status change, progress update, or newly available incremental results.

The arg parameter should be used to pass state to the delegate wrapped by the d parameter. It might be a reference to an AsyncOperation, or it might be a System.ComponentModel.ProgressChangedEventArgs object. It may be desirable to derive your own class from System.ComponentModel.ProgressChangedEventArgs to provide additional state storage.

Notes to Inheritors

Inheritors must make the Post invocation asynchronous, so that class library providers do not need to concern themselves with potential stack overflows if they assume asynchrony but a particular application model happens to be synchronous.

NoteNote:

Console applications do not synchronize the execution of Post calls. This can cause ProgressChanged events to be raised out of order. If you want to have serialized execution of Post calls, implement and install a System.Threading.SynchronizationContext class.

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 Post method for reporting progress and incremental results of an asynchronous operation. This code example is part of a larger example provided for the System.ComponentModel.AsyncOperationManager class.

' The GetPersons method will raise ProgressChanged and 
' Completed events by using AsyncOperation's Post 
' and PostOperationCompleted methods. Declare delegates 
' for them here. Methods for use 
' with these delegates will be defined below. 
Private AsyncOpProgressReportHandler As SendOrPostCallback
Private AsyncOpCompletedHandler As SendOrPostCallback

' Constructor 
Public Sub New()
    ' Attach the Completed and ProgressChanged methods that will 
    ' be called by AsyncOperation to their delegates. 
    AsyncOpProgressReportHandler = New SendOrPostCallback _
        (AddressOf AsyncOpGetPersonsProgressChanged)
    AsyncOpCompletedHandler = New SendOrPostCallback _
        (AddressOf AsyncOpGetPersonsCompleted)
End Sub

' ProgressChanged method for passing in to the 
' AsyncOperation Post method. 
Protected Sub AsyncOpGetPersonsProgressChanged(ByVal state As Object)
    Dim progressChangedEventArgs As GetPersonsProgressChangedEventArgs _
        = TryCast(state, GetPersonsProgressChangedEventArgs)
    OnGetPersonsProgressChanged(progressChangedEventArgs)
End Sub

' Completed-event method for passing in to the 
' AsyncOperation PostOperationCompleted method. 
Protected Sub AsyncOpGetPersonsCompleted(ByVal eventArgs As Object)
    Dim completedEventArgs As GetPersonsCompletedEventArgs _
        = TryCast(eventArgs, GetPersonsCompletedEventArgs)
    OnGetPersonsCompleted(completedEventArgs)
End Sub

' Raise the ProgressChanged event. 
Protected Sub OnGetPersonsProgressChanged _
(ByVal e As GetPersonsProgressChangedEventArgs)

    RaiseEvent GetPersonsProgressChangedEvent(e)
End Sub

' Raise the Completed event. 
Protected Sub OnGetPersonsCompleted _
    (ByVal e As GetPersonsCompletedEventArgs)

    RaiseEvent GetPersonsCompletedEvent(Me, e)
End Sub

// The GetPersons method will raise ProgressChanged and
// Completed events by using AsyncOperation's Post
// and PostOperationCompleted methods. Declare delegates
// for them here.  Methods for use 
// with these delegates will be defined below.
private SendOrPostCallback AsyncOpProgressReportHandler;
private SendOrPostCallback AsyncOpCompletedHandler;

// Constructor
public PersonDataSource()
{
    // Attach the Completed and ProgressChanged events that 
    // will be called by AsyncOperation to their delegates.
    AsyncOpProgressReportHandler =
        new SendOrPostCallback(AsyncOpGetPersonsProgressChanged);
    AsyncOpCompletedHandler =
        new SendOrPostCallback(AsyncOpGetPersonsCompleted);
}

// ProgressChanged method for passing in to the 
// AsyncOperation Post method.
protected void AsyncOpGetPersonsProgressChanged(object state)
{
    GetPersonsProgressChangedEventArgs e
        = state as GetPersonsProgressChangedEventArgs;
    OnGetPersonsProgressChanged(e);
}

// Completed-event method for passing in to the 
// AsyncOperation PostOperationCompleted method.
protected void AsyncOpGetPersonsCompleted(object eventArgs)
{
    GetPersonsCompletedEventArgs e =
        eventArgs as GetPersonsCompletedEventArgs;
    OnGetPersonsCompleted(e);
}

// Raise the ProgressChanged event.
protected void OnGetPersonsProgressChanged
    (GetPersonsProgressChangedEventArgs e)
{
    if (GetPersonsProgressChangedEvent != null)
    {
        GetPersonsProgressChangedEvent(e);
    }
}

// Raise the Completed event.
protected void OnGetPersonsCompleted
    (GetPersonsCompletedEventArgs e)
{
    if (GetPersonsCompletedEvent != null)
    {
        GetPersonsCompletedEvent(this, e);
    }
}

' 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

// 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;
}

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.