Getting Started with the AWS SDK for .NET

Watch the following video to get started with the AWS SDK for .NET or read the text version below.

The AWS .NET SDK is a single, downloadable package that includes Visual Studio project templates, the AWS .NET library, C# code samples, and documentation. The AWS .NET SDK makes it easier for Windows developers to build .NET applications that tap into the cost-effective, scalable, and reliable AWS infrastructure services such as Amazon S3, EC2, and SimpleDB.

The AWS .NET SDK features:

• AWS .NET Library — Build .NET applications on top of APIs that take the complexity out of coding directly against web services interfaces. The all-in-one library provides .NET developer-friendly APIs that hide much of the lower-level plumbing associated with programming for the AWS cloud, including authentication, request retries, and error handling.
• Code Samples — Practical examples in C# for how to use the libraries to build applications.
• Documentation — Learn more about how to use the libraries and code samples with online video tutorials and reference documentation.
• Visual Studio Support — Get started quickly with building solutions for the AWS cloud using Visual Studio Project Templates.

The AWS SDK for .NET supports the AWS infrastructure products, including:

• Amazon Elastic Compute Cloud (Amazon EC2)
• Amazon Simple Storage Service (Amazon S3)
• Amazon Virtual Private Cloud (Amazon VPC)
• Amazon SimpleDB
• Amazon Relational Database Service (Amazon RDS)
• Amazon CloudFront
• Amazon Simple Queue Service (Amazon SQS)
• Amazon Simple Notification Service (Amazon SNS)
• Amazon Elastic MapReduce
• Amazon CloudWatch
• Elastic Load Balancing
• Auto Scaling

The AWS .NET SDK supports development on any platform that supports the .NET Framework 2.0 (or later), allowing most developers to start building solutions for the AWS cloud without having to upgrade to a new operating system, .NET Framework, or Visual Studio version.

You must individually sign up for each service you want to use. You can sign up for a service on the following pages:

• Amazon Elastic Compute Cloud (Amazon EC2), which includes Amazon CloudWatch, Elastic Load Balancing, and Auto Scaling
• Amazon Simple Storage Service (Amazon S3)
• Amazon Virtual Private Cloud (Amazon VPC)
• Amazon SimpleDB
• Amazon Relational Database Service (Amazon RDS)
• Amazon CloudFront
• Amazon Simple Queue Service (Amazon SQS)
• Amazon Simple Notification Service (Amazon SNS)
• Amazon Elastic MapReduce

Signing Up for a Service

1. Go to the home page listed above.
2. Click the Sign Up button on the top right corner of the page. If you don't already have an AWS account, you are prompted to create one as part of the sign up process.
3. Follow the on-screen instructions.

AWS sends you a confirmation e-mail after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to https://aws.amazon.com and clicking Your Account.

In order to use the AWS SDK for .NET, you will need your AWS security credentials, which AWS assigned you when you created your AWS account. Security credentials are used to authenticate requests to a service identify yourself as the sender of a request. The security credentials used with the AWS SDK for .NET is a pair of public/private keys:

• Access Key ID (For example: 022QF06E7MXBSH9DHM02)
• Secret Access Key (For example: kWcrlUX5JEDGM/LtmEENI/aVmYvHNif5zB+d9+ct)

IMPORTANT: Your Secret Access Key is a secret, which only you and AWS should know. It is important to keep it confidential to protect your account. Store it securely in a safe place. Never include it in your requests to AWS, and never e-mail it to anyone. Do not share it outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your Secret Access Key.

Viewing Your AWS Security Credentials

• To view your security credentials, go to the Security Credentials page at https://aws.amazon.com/security-credentials.

To use the AWS SDK for .NET, you'll need the following software:

• Microsoft .NET Framework 2.0 or later
• Any of the following Visual Studio editions:
  • Microsoft Visual Studio 2008 Professional Edition or later
  • Microsoft Visual C# 2008 Express Edition
  • Microsoft Visual Web Developer 2008 Express Edition

1. Open your Visual Studio product.
2. Select About... from the Help menu. A dialog box opens that lists Microsoft Visual Studio and.NET Framework versions.

Download and install the AWS .NET SDK as follows:

1. Go to https://aws.amazon.com/sdkfornet.
2. Click the Download button on the top right corner of the page. Your browser will prompt you to save the file.
3. Open the saved installer to begin the installation process and follow the on-screen instructions.

By default, the AWS SDK for .NET is installed in the Program Files directory, which requires administrator privileges. You can install the AWS SDK for .NET as a non-administrator if you choose a different installation directory.

The AWS SDK for .NET has three project templates you can use to build a new project on Amazon Web Services:

• AWS Console Project—Creates a console application that references the AWS .NET library (AWSSDK.dll) with a sample Program.cs file that makes a basic request to Amazon S3, Amazon SimpleDB, and Amazon EC2.
• AWS Web Project—Creates an ASP.NET application that references the AWS .NET library (AWSSDK.dll) with a sample Program.cs file that makes a basic request to Amazon S3, Amazon SimpleDB, and Amazon EC2.
• AWS Empty Project—Creates a console application that references the AWS .NET library (AWSSDK.dll), but does not include any code in the Program.cs file.

The general process to creating a new project based on a project template is similar across Visual Studio editions, but we'll go through the steps for Visual Studio Professional 2008.

Creating a New Project in Visual Studio Professional Edition 2008

1. Open Visual Studio.
2. Click New -> Project from the File menu. The New Project dialog box opens.
3. Select "AWS" in the list of project types, select the project template you want to use, enter a project name, and then click OK.
4. On project creation, the template prompts you for your Access Key ID and Secret Access Key. Enter these security credentials, and then click OK. The template automatically configures the project with your security credentials.

NOTE: For the AWS Console Project and AWS Empty Project, your security credentials are added to the App.config file. For the AWS Web Project, your security credentials are added to the Web.config file.

Running the Project

You can run the project immediately after the project is created by pressing the F5 key (or selecting Start Debugging from the Debug menu).

The AWS Console project will look like this:

The AWS Web Project output will look like this:

The AWS SDK for .NET includes code samples as additional examples for how to build software on Amazon Web Services.

• Amazon SimpleDB Sample—Demonstrates how to create domains, put data into a domain, get data from a domain, replace an attribute, and more. See the Amazon SimpleDB Getting Started Guide for more information about this sample.
• Amazon SQS Sample—Demonstrates how to create a queue, send a message, retrieve a message, and more. See the Amazon SQS Getting Started Guide for more information about this sample.
• Amazon S3 Sample—Demonstrates how to create a bucket, put an object, list objects in a bucket, and more. See the Amazon S3 Getting Started Guide for more information about this sample.
• AWS Console Sample—Similar to the AWS Console Project template, the AWS Console Sample makes a sample request to every service supported by the AWS SDK for .NET and prints the response information to the SDK.

NOTE: Additional resources, such as articles & tutorials, and code samples are available on the Windows & .NET Developer Center at https://aws.amazon.com/net.

You can find the code samples in the /samples folder under the installation directory for the AWS SDK for .NET. By default, the samples are available under C:\Program Files\AWS SDK for .NET\samples.

The steps for running the samples are below. Be sure to check out the related Getting Started Guides for each service for more detailed information.

1. Extract the sample code into a directory on your machine.
2. Open the sample solution in Visual Studio.
3. For the Amazon SimpleDB Sample, open AmazonSimpleDB_Sample/AmazonSimpleDB_Sample.sln.
4. For the Amazon SQS Sample, open AmazonSQS_Sample/AmazonSQS_Sample.sln.
5. For the Amazon S3 Sample, open AmazonS3Sample/AmazonS3Sample.sln.
6. For the AWS Console Sample, open AWS_ConsoleSample/AWS_ConsoleSample.sln.
7. Edit the App.config file to include your security credentials as follows:

   
     ="[ENTER  YOUR ACCESS KEY ID HERE]"/>
     ="[ENTER  YOUR SECRET ACCESS KEY HERE]"/>
   

4. Save the App.config file.
5. Run the sample in debugging mode by typing F5.

Now that you have installed the AWS SDK for .NET and know more about how to use it, you are ready to start designing your own application. Although most applications built on Amazon Web Services are not as simple as the examples in this guide, the principles used in the example can be readily applied to more complex applications.

This section lists some additional resources that may be helpful as you develop your application.

Reference documentation for the AWS SDK for .NET is added to Visual Studio's Help when you install the SDK. You can view reference documentation for the AWS SDK for .NET anytime by opening Visual Studio, and then selecting Contents from the Help menu.

To make the service call to a different region, instantiate the client with the configuration object, and pass the region-specific endpoint. For example:

AmazonEC2 ec2 = AWSClientFactory.CreateAmazonEC2Client(
      appConfig["AWSAccessKey"],
      appConfig["AWSSecretKey"],
      new AmazonEC2Config().WithServiceURL("https://eu-west-1.ec2.amazonaws.com")
      ); 

DescribeInstancesRequest ec2Request = new DescribeInstancesRequest();

See the Developer Guide for each service for a list of region endpoints.

If you have an existing application built on one of the stand-alone C# libraries, you can migrate to the AWS SDK for .NET with minimal impact on your application. Namespaces, objects, and most methods will continue to work as they have done previously. However, the AWS SDK for .NET no longer allows developers to set lists. Instead, developers should use the accompanying .With* methods. If you want to update the items in a List, use its getter and update the list in-place.

You can get help with your .NET development through the AWS .NET Development forum. AWS Premium Support customers also can get support for the AWS SDK for .NET through the Support Center at https://aws.amazon.com/support.