Menu
AWS SDK for .NET
Developer Guide

This documentation is for version 2.0 of the AWS SDK for .NET. For the latest version, see the AWS SDK for .NET Developer Guide for version 3.

Amazon Web Services Asynchronous APIs for .NET

Asynchronous API for .NET 4.5, Windows Store, and Windows Phone 8

The AWS SDK for .NET uses the new task-based asynchronous pattern for .NET 4.5, Windows Store, and Windows Phone 8. You can use the async and await keywords to perform and manage asynchronous operations for all AWS products without blocking.

To learn more about the task-based asynchronous pattern, see Task-based Asynchronous Pattern (TAP) on MSDN.

Asynchronous API for .NET 3.5

The AWS SDK for .NET supports asynchronous (async) versions of most of the method calls exposed by the .NET client classes. The async methods enable you to call AWS services without having your code block on the response from the service. For example, you could make a request to write data to Amazon S3 or DynamoDB and then have your code continue to do other work while AWS processes the requests.

Syntax of Async Request Methods

There are two phases to making an asynchronous request to an AWS service. The first is to call the Begin method for the request. This method initiates the asynchronous operation. Then, after some period of time, you would call the corresponding End method. This method retrieves the response from the service and also provides an opportunity to handle exceptions that might have occurred during the operation.

Note

It is not required that you call the End method. Assuming that no errors are encountered, the asynchronous operation will complete whether or not you call End.

Begin Method Syntax

In addition to taking a request object parameter, such as PutItemRequest, the async Begin methods take two additional parameters: a callback function, and a state object. Instead of returning a service response object, the Begin methods return a result of type IAsyncResult. For the definition of this type, go to the MSDN documentation.

Synchronous Method
Copy
PutItemResponse PutItem( PutItemRequest putItemRequest )
Asynchronous Method
Copy
IAsyncResult BeginPutItem( GetSessionTokenRequest getSessionTokenRequest, {AsyncCallback callback}, {Object state} )
AsyncCallback callback

The callback function is called when the asynchronous operation completes. When the function is called, it receives a single parameter of type IAsyncResult. The callback function has the following signature.

Copy
void Callback(IAsyncResult asyncResult)
Object state

The third parameter, state, is a user-defined object that is made available to the callback function as the AsyncState property of the asyncResult parameter, that is, asyncResult.AsyncState.

Calling Patterns

  • Passing a callback function and a state object.

  • Passing a callback function, but passing null for the state object.

  • Passing null for both the callback function and the state object.

This topic provides an example of each of these patterns.

Examples

All of the following examples assume the following initialization code.

Copy
public static void TestPutObjectAsync() { // Create a client AmazonS3Client client = new AmazonS3Client(); PutObjectResponse response; IAsyncResult asyncResult; // // Create a PutObject request // // You will need to use your own bucket name below in order // to run this sample code. // PutObjectRequest request = new PutObjectRequest { BucketName = "{PUT YOUR OWN EXISTING BUCKET NAME HERE}", Key = "Item", ContentBody = "This is sample content..." }; // // additional example code // }

Using IAsyncResult.AsyncWaitHandle

In some circumstances, the code that calls the Begin method might need to enable another method that it calls to wait on the completion of the asynchronous operation. In these situations, it can pass the method the WaitHandle returned by the IAsyncResult.AsyncWaitHandle property of the IAsyncResult return value. The method can then wait for the asynchronous operation to complete by calling WaitOne on this WaitHandle.

No Callback Specified

The following example code calls BeginPutObject, performs some work, then calls EndPutObject to retrieve the service response. The call to EndPutObject is enclosed in a try block to catch any exceptions that might have been thrown during the operation.

Copy
asyncResult = client.BeginPutObject(request, null, null); while ( ! asyncResult.IsCompleted ) { // // Do some work here // } try { response = client.EndPutObject(asyncResult); } catch (AmazonS3Exception s3Exception) { // // Code to process exception // }

Simple Callback

This example assumes that the following callback function has been defined.

Copy
public static void SimpleCallback(IAsyncResult asyncResult) { Console.WriteLine("Finished PutObject operation with simple callback"); }

The following line of code calls BeginPutObject and specifies the above callback function. When the PutObject operation completes, the callback function is called. The call to BeginPutObject specifies null for the state parameter because the simple callback function does not access the AsyncState property of the asyncResult parameter. Neither the calling code or the callback function call EndPutObject. Therefore, the service response is effectively discarded and any exceptions that occur during the operation are ignored.

Copy
asyncResult = client.BeginPutObject(request, SimpleCallback, null);

Callback with Client

This example assumes that the following callback function has been defined.

Copy
public static void CallbackWithClient(IAsyncResult asyncResult) { try { AmazonS3Client s3Client = (AmazonS3Client) asyncResult.AsyncState; PutObjectResponse response = s3Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject operation with client callback"); } catch (AmazonS3Exception s3Exception) { // // Code to process exception // } }

The following line of code calls BeginPutObject and specifies the preceding callback function. When the PutObject operation completes, the callback function is called. In this example, the call to BeginPutObject specifies the Amazon S3 client object for the state parameter. The callback function uses the client to call the EndPutObject method to retrieve the server response. Because any exceptions that occurred during the operation will be received when the callback calls EndPutObject, this call is placed within a try block.

Copy
asyncResult = client.BeginPutObject(request, CallbackWithClient, client);

Callback with State Object

This example assumes that the following class and callback function have been defined.

Copy
class ClientState { AmazonS3Client client; DateTime startTime; public AmazonS3Client Client { get { return client; } set { client = value; } } public DateTime Start { get { return startTime; } set { startTime = value; } } }
Copy
public static void CallbackWithState(IAsyncResult asyncResult) { try { ClientState state = asyncResult.AsyncState as ClientState; AmazonS3Client s3Client = (AmazonS3Client)state.Client; PutObjectResponse response = state.Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject. Elapsed time: {0}", (DateTime.Now - state.Start).ToString()); } catch (AmazonS3Exception s3Exception) { // // Code to process exception // } }

The following line of code calls BeginPutObject and specifies the above callback function. When the PutObject operation completes, the callback function is called. In this example, the call to BeginPutObject specifies, for the state parameter, an instance of the ClientState class defined previously. This class embeds the Amazon S3 client as well as the time at which BeginPutObject is called. The callback function uses the Amazon S3 client object to call the EndPutObject method to retrieve the server response. The callback also extracts the start time for the operation and uses it to print the time it took for the asynchronous operation to complete.

As in the previous examples, because exceptions that occur during the operation are received when EndPutObject is called, this call is placed within a try block.

Copy
asyncResult = client.BeginPutObject( request, CallbackWithState, new ClientState { Client = client, Start = DateTime.Now } );

Complete Sample

The following code sample demonstrates the various patterns that you can use when calling the asynchronous request methods.

Copy
using System; using System.Collections.Generic; using System.Diagnostics; using System.IO; using System.Text; using System.Threading; using Amazon; using Amazon.Runtime; using Amazon.S3; using Amazon.S3.Model; namespace async_aws_net { class ClientState { AmazonS3Client client; DateTime startTime; public AmazonS3Client Client { get { return client; } set { client = value; } } public DateTime Start { get { return startTime; } set { startTime = value; } } } class Program { public static void Main(string[] args) { TestPutObjectAsync(); } public static void SimpleCallback(IAsyncResult asyncResult) { Console.WriteLine("Finished PutObject operation with simple callback"); Console.Write("\n\n"); } public static void CallbackWithClient(IAsyncResult asyncResult) { try { AmazonS3Client s3Client = (AmazonS3Client) asyncResult.AsyncState; PutObjectResponse response = s3Client.EndPutObject(asyncResult); Console.WriteLine("Finished PutObject operation with client callback"); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine(response); Console.Write("\n\n"); } catch (AmazonS3Exception s3Exception) { // // Code to process exception // } } public static void CallbackWithState(IAsyncResult asyncResult) { try { ClientState state = asyncResult.AsyncState as ClientState; AmazonS3Client s3Client = (AmazonS3Client)state.Client; PutObjectResponse response = state.Client.EndPutObject(asyncResult); Console.WriteLine( "Finished PutObject operation with state callback that started at {0}", (DateTime.Now - state.Start).ToString() + state.Start); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine(response); Console.Write("\n\n"); } catch (AmazonS3Exception s3Exception) { // // Code to process exception // } } public static void TestPutObjectAsync() { // Create a client AmazonS3Client client = new AmazonS3Client(); PutObjectResponse response; IAsyncResult asyncResult; // // Create a PutObject request // // You will need to change the BucketName below in order to run this // sample code. // PutObjectRequest request = new PutObjectRequest { BucketName = "PUT-YOUR-OWN-EXISTING-BUCKET-NAME-HERE", Key = "Item", ContentBody = "This is sample content..." }; response = client.PutObject(request); Console.WriteLine("Finished PutObject operation for {0}.", request.Key); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine("{0}", response); Console.Write("\n\n"); request.Key = "Item1"; asyncResult = client.BeginPutObject(request, null, null); while ( ! asyncResult.IsCompleted ) { // // Do some work here // } try { response = client.EndPutObject(asyncResult); } catch (AmazonS3Exception s3Exception) { // // Code to process exception // } Console.WriteLine("Finished Async PutObject operation for {0}.", request.Key ); Console.WriteLine("Service Response:"); Console.WriteLine("-----------------"); Console.WriteLine(response); Console.Write("\n\n"); request.Key = "Item2"; asyncResult = client.BeginPutObject(request, SimpleCallback, null); request.Key = "Item3"; asyncResult = client.BeginPutObject(request, CallbackWithClient, client); request.Key = "Item4"; asyncResult = client.BeginPutObject(request, CallbackWithState, new ClientState { Client = client, Start = DateTime.Now } ); Thread.Sleep( TimeSpan.FromSeconds(5) ); } } }

See Also