Developer Guide

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

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.

Migrating Your Code to the Version 2 of the AWS SDK for .NET

This guide describes changes in the version 2 of the SDK, and how you can migrate your code to this version of the SDK.


The AWS SDK for .NET was released in November 2009 and was originally designed for .NET Framework 2.0. Since then, .NET has improved with .NET 4.0 and .NET 4.5. Since .NET 2.0, .NET has also added new target platforms: WinRT and Windows Phone 8.

AWS SDK for .NET version 2 has been updated to take advantage of the new features of the .NET platform and to target WinRT and Windows Phone 8.

What's New#

  • Support for Task-based asynchronous API
  • Support for Windows Store apps
  • Support for Windows Phone 8
  • Ability to configure service region via App.config or Web.config
  • Collapsed Response and Result classes
  • Updated names for classes and properties to follow .NET conventions

What's Different#


The AWS SDK for .NET uses a common runtime library to make AWS service requests. In version 1 of the SDK, this "common" runtime was added after the initial release, and several of the older AWS services did not use it. As a result, there was a higher degree of variability among services in the functionality provided by the AWS SDK for .NET version 1.

In version 2 of the SDK, all services now use the common runtime, so future changes to the core runtime will propagate to all services, increasing their uniformity and easing demands on developers who want to target multiple services.

However, separate runtimes are provided for .NET 3.5 and .NET 4.5:

  • The version 2 runtime for .NET 3.5 is similar to the existing version 1 runtime, which is based on the System.Net.HttpWebRequest class and uses the Begin and End pattern for asynchronous methods.
  • The version 2 runtime for .NET 4.5 is based on the new System.Net.Http.HttpClient class and uses Tasks for asynchronous methods, which enables users to use the new async and await keywords in C# 5.0.

The WinRT and Windows Phone 8 versions of the SDK reuse the runtime for .NET 4.5, with the exception that they support asynchronous methods only. Windows Phone 8 doesn't natively support System.Net.Http.HttpClient, so the SDK depends on Microsoft's portable class implementation of HttpClient, which is hosted on NuGet at the following URL:

Removal of the "With" Methods#

The "With" methods have been removed from version 2 of the SDK for the following reasons:
  • In .NET 3.0, constructor initializers were added, making the "With" methods redundant.
  • The "With" methods added significant overhead to the API design and worked poorly in cases of inheritance.

For example, in version 1 of the SDK, you would use "With" methods to set up a TransferUtilityUploadRequest:

TransferUtilityUploadRequest uploadRequest = new TransferUtilityUploadRequest()

In the current version of the SDK, use constructor initializers instead:

TransferUtilityUploadRequest uploadRequest = new TransferUtilityUploadRequest() {
  BucketName = "my-bucket", Key = "test", FilePath = "c:\test.txt",
  ServerSideEncryptionMethod = ServerSideEncryptionMethod.AES256

Removal of SecureString#

The use of System.Security.SecureString was removed in version 2 of the SDK because it is not available on the WinRT and Windows Phone 8 platforms.

Breaking Changes#

Many classes and properties were changed to either meet .NET naming conventions or more closely follow service documentation. Amazon Simple Storage Service (Amazon S3) and Amazon Elastic Compute Cloud (Amazon EC2) were the most affected by this because they are the oldest services in the SDK and were moved to the new common runtime. Below are the most visible changes.

Amazon DynamoDB#

  • The amazon.dynamodb namespace has been removed; only the amazon.dynamodbv2 namespace remains.
  • Service-response collections that were set to null in version 1 are now set to an empty collection. For example, QueryResult.LastEvaluatedKey and ScanResponse.LastEvaluatedKey will be set to empty collections when there are no more items to query/scan. If your code depends on LastEvaluatedKey to be null, it now has to check the collection's Count field to avoid a possible infinite loop.

Amazon EC2#

  • Amazon.EC2.Model.RunningInstance has been renamed Instance.

    Additionally, the GroupName and GroupId properties of RunningInstance have been combined into the SecurityGroups property, which takes a GroupIdentifier object, in Instance.

  • Amazon.EC2.Model.IpPermissionSpecification has been renamed IpPermission.

  • Amazon.EC2.Model.Volume.Status has been renamed State.

  • AuthorizeSecurityGroupIngressRequest removed root properties for ToPort and FromPort in favor of always using IpPermissions.

    This was done because the root properties were silently ignored when set for an instance running in a VPC.

  • The AmazonEC2Exception class is now based on AmazonServiceException instead of System.Exception.

    As a result, many of the exception properties have changed; the XML property is no longer provided, for example.

Amazon Redshift#

Amazon S3#

Amazon Simple Workflow Service#

Configuring the AWS Region#

Regions can be set in the App.config or Web.config files (depending on your project type). The recommended approach is to use the aws element, although using the appSettings element is still supported.

For example, the following specification configures all clients that don't explicitly set the region to point to |region_api_default| through use of the aws element.

<configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK"/> </configSections> <aws profileName="{profile_name}" region="|region_console_default|"/>

Alternatively, you can use the appSettings element.

 <configuration> <appSettings> <add key="AWSProfileName" value="{profile_name}"/>
    <add key="AWSRegion" value="|region_console_default|"/>

Response and Result Classes#

To simplify your code, the Response and Result classes that are returned when creating a service object have been collapsed. For example, the code to get an Amazon SQS queue URL previously looked like this:

GetQueueUrlResponse response = SQSClient.GetQueueUrl(request);

You can now get the queue URL simply by referring to the QueueUrl member of the CreateQueueResponse returned by the AmazonSQSClient.CreateQueue method:


The CreateQueueResult property still exists, but has been marked as deprecated, and may be removed in a future version of the SDK. Use the QueueUrl member instead.

Additionally, all of the service response values are based on a common response class, AmazonWebServiceResponse, instead of individual response classes per service. For example, the PutBucketResponse class in Amazon S3 is now based on this common class instead of S3Response in version 1. As a result, the methods and properties available for PutBucketResponse have changed.

Refer to the return value type of the Create* method for the service client that you're using to see what values are returned. These are all listed in the AWS SDK for .NET Reference.